What is a Resource

    What is a Declarative API

    A declarative API expresses a fixed state that the cluster must continuallywork towards. Declarative APIs define the what, but not the how.Example:

    An imperative API expresses an operation that may change state, but does notdefine an absolute state that must be maintained. Imperative APIs express thehow, but not what. Example: $ add-pods 2.

    In the declarative case, if a replica is lost the cluster has a clear directiveto create another one, whereas in the latter case this is not necessarily true.

    Declarative API usage example by invoking .

    Declarative How

    Constraints on the how may be defined within declarative APIs, such as performing a rolling updateversus deleting and recreating all Pods immediately.

    Resource Schema

    Group, Version, Kind

    Every Kubernetes resource has a Group, Version and Kind that uniquely identifies it.

    • The resource Kind is the name of the API - such as Deployment or Service.
    • The resource Version defines the stability of the API and backward compatibility guarantees -such as v1beta1 or v1.
    • The resource Group is similar to package in a language. It disambiguates different APIsthat may happen to have identically named _Kind_s. Groups often contain a domain name, such as k8s.io.

    Deployment yaml config Group Version Kind

    Versions

    Resources with different Version_s but the same _Group and Kind differ in the following ways:

    • Unspecified fields may have different defaults

    Alpha APIs may break backwards compatibility by changing field names, defaults or behavior. Theyalso may not be supported in the future.

    Beta APIs maintain backwards compatibility on field names, defaults and behavior. They may bemissing features required for GA. However once the API goes GA, the features should be availablein the Beta version.

    GA APIs have been available and running in production for sufficient time to have developeda stable set of field names and defaults, as well as a complete feature set.

    Spec, Status, Metadata

    Spec: the Resource Spec defines the desired state of the cluster as specified by the user.

    Status: the Resource Status publishes the state of the cluster as observed by the controller.

    Metadata: the Resource Metadata contains information common to most resources about the objectincluding as the object name, annotations, labels and more.

    Note: this config has been abbreviated for the purposes of display

    Deployment yaml config with Spec Status and Metadata

    Spec vs Status

    The resource Status should not contain the source of truth for any information, and should bepossible for Controllers to recreate by looking at the cluster state. Other values assigned byControllers, such as the Service spec.clusterIp, should be set on the Spec not the Status.

    Resource Endpoints

    Kubernetes Resources have well defined endpoints as described below.

    Create, Update, Patch, Delete

    The create, update, patch and delete endpoints may be used to modify objects. The update endpointreplaces the object with what is provided, whereas the patch endpoint selectively updatesfields.

    Get, List, Watch

    The get, list and watch endpoints may be used to get a specific resource by name, list allresources matching a labels, or continually watch for updates.

    Deployment Endpoints under

    API versions

    When reading objects, the same objects should be returned regardless of which version of the API endpoint isread from (though the structure may differ between versions).

    Warning on Updates

    The update API should only be used to read-then-write an object, and never used toupdate an object directly from declarative config. This is because the object statemay be partially managed by Controllers running in the cluster and this state wouldbe lost when the update replaces the current object with the declarative config.

    Illustrative example: updating a Service from declarative config rather than a read-then-writewould clear the Service spec.clusterIp field set by the controller.

    Watch Timeouts

    If used directly, a watch API call will timeout and need to be re-established. The kubebuilderlibraries hide the details behind watches from users and automatically re-establish connections.

    Subresources

    While most operations can be represented declaratively, some may not, such aslogs, attach or exec. These operations may be implemented as subresources.

    Subresources are functions attached to resources, but that have theirown Schema and Endpoints. By having different resources each implementthe same subresource API, resources can implemented shared interfaces.

    For example Deployment, ReplicaSet and StatefulSet each implement thescale subresource API, making it easy to build tools which scale any of themas well as scale any other resources that implement the scale subresource.

    Deployment Scale Subresource Endpoints under

    Labels, Selectors and Annotations

    Labels in ObjectMeta data are key-value pairs that may be queried to find matching objects.Labels are used to connect objects together in a Kubernetes cluster. For instanceServices use labels to determine which Pods to direct traffic to, and Deployments use labels(along with OwnersReferences) to identify Pods they created.

    Annotations allow arbitrary data to be written to resources that may not fit within theSchema of the resource, but may be needed by end users or tools.

    Extending Built In Types

    Annotations may be used to define new extension fields on resources without modifying theSchema of the object. This allows users to define their own private schema extensions forexisting core Kubernetes resources.

    Namespaces