What is a Resource

A Kubernetes Resource is a declarative API with a well defined Schema structureand endpoints. Because the structure of the Schema and Endpoints are predictableand structured, most Kubernetes tools work with any Kubernetes API even if theyare not part of the core (e.g. extensions through CRDs).

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: $ replicas 3

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 apply.

  1. # object.yaml contains an object declaration
  2. $ kubectl apply -f object.yaml

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

  1. apiVersion: apps/v1
  2. kind: Deployment

Versions

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

  • Unspecified fields may have different defaults
  • The same logical fields may have different names or representationsHowever resources with different versions frequently share the same features and controller.

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

Most Kubernetes Resource Schemas contain 3 components: Spec, Status and 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

  1. apiVersion: extensions/v1beta1
  2. kind: Deployment
  3. metadata:
  4.   name: nginx
  5.   namespace: default
  6. spec:
  7.   replicas: 1
  8.   template:
  9.     spec:
  10.       containers:
  11.       - image: nginx
  12.         name: nginx
  13. status:
  14.   replicas: 1
  15.   unavailableReplicas: 1
  16.   updatedReplicas: 1

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 /apis/apps/v1

  1. name: "deployments"
  2. kind: "Deployment"
  3. verbs:
  4. - "create"
  5. - "delete"
  6. - "deletecollection"
  7. - "get"
  8. - "list"
  9. - "patch"
  10. - "update"
  11. - "watch"

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).

When writing objects, the default values applied to fields may change between API versions, butthe written object should be visible when read from any version.

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 /apis/apps/v1

  1. name: "deployments/scale"
  2. group: "autoscaling"
  3. version: "v1"
  4. kind: "Scale"
  5. verbs:
  6. - "get"
  7. - "patch"
  8. - "update"

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

While most resources are Namespaced, that is the objects are scoped to a Namespace, some resourcesare non-namespaced and scoped to the cluster. Examples of non-namespaced resources includeNodes, Namespaces and ClusterRole.