Kubernetes API and Object Model

Kubernetes API and Object Model provide a structured way to manage and interact with containerized applications in a scalable and automated infrastructure environment.

Kubernetes API and Object Model is the schema and set of conventions by which every entity in a cluster, from a single container's specification to cluster-wide policy, is represented, addressed, and manipulated. Rather than exposing bespoke interfaces for each feature, Kubernetes represents everything as a resource with a uniform structure, accessible through a single, consistent RESTful API. This uniformity is what allows generic tools, such as kubectl, client libraries, and controllers, to operate over arbitrary object types, including ones defined by users, without needing type-specific logic.

Structure of a Kubernetes Object

The Four Core Fields

Every persisted Kubernetes object shares four top-level fields:

apiVersion: Identifies the API group and version the object belongs to, such as apps/v1 or v1.
kind: Identifies the type of object, such as Pod, Deployment, or ConfigMap.
metadata: Contains identifying information common to all objects, including name, namespace, labels, annotations, uid, and resourceVersion.
spec: Contains the user-supplied desired state of the object, whose structure is specific to the object's kind.

Most objects additionally carry a status field, populated and updated by the system rather than the user, reflecting the object's observed, current state.

apiVersion: v1
kind: ConfigMap
metadata:
  name: codartium-config
  namespace: default
  labels:
    app: codartium
data:
  log-level: "info"

Spec and Status Separation

The separation between spec and status encodes the fundamental distinction between intent and observation. Clients write to spec to express what they want; controllers write to status to report what is actually true. This separation allows multiple controllers to safely observe and report on the same object without conflicting over ownership of the user's original intent.

object = (metadata, spec, status)

API Groups and Versioning

Core and Named Groups

The API is partitioned into groups to allow independent evolution of related resources. The core group, addressed simply as v1, contains foundational resources such as Pod, Service, and Namespace. Named groups, such as apps, batch, and networking.k8s.io, contain resources introduced later or organized by functional area.

Version Stability Levels

Each API version carries a stability designation:

alpha (e.g., v1alpha1): May contain bugs, is disabled by default, and can change or be removed without notice.
beta (e.g., v1beta1): Enabled by default, well tested, but the schema may still change in incompatible ways before becoming stable.
stable (e.g., v1): Appears in released software for many subsequent versions and is subject to a formal deprecation policy before removal.

Conversion and Storage

The API server can accept and serve a resource in multiple versions simultaneously, internally converting between them, while persisting a single canonical storage version to etcd, ensuring that clients using different API versions remain interoperable.

Identity, Namespacing, and Labels

Uniquely Identifying Objects

Within a namespace, an object is uniquely identified by the combination of its kind and name. Across the cluster's lifetime, every object additionally receives a globally unique identifier, uid, that remains stable even if an object of the same name and kind is deleted and recreated.

Namespaced vs. Cluster-Scoped Resources

Some resource kinds, such as Pods, Services, and Deployments, are namespaced, existing only within the context of a Namespace object and isolated from like-named resources in other namespaces. Others, such as Nodes and PersistentVolumes, are cluster-scoped, existing independently of any namespace.

Labels, Annotations, and Selectors

Labels are key-value metadata used for identification and grouping, queried through label selectors that support equality-based and set-based matching. Annotations, by contrast, store arbitrary non-identifying metadata, useful for tooling or descriptive information, and are not used in selection.

kubectl get pods -l app=codartium,tier=backend
kubectl label pod codartium-app-abc123 environment=production
kubectl annotate pod codartium-app-abc123 build-id=2024-04-11.1

Resource Versions, Optimistic Concurrency, and Watches

resourceVersion

Every object carries a resourceVersion, an opaque value that changes each time the object is modified. This value underpins optimistic concurrency control: an update request that includes a stale resourceVersion is rejected, requiring the client to re-read the object and reapply its intended change, preventing lost updates when multiple clients modify the same object concurrently.

The Watch Interface

Clients can establish a long-lived watch against a resource or collection of resources, receiving a stream of ADDED, MODIFIED, and DELETED events as the underlying state changes, without needing to repeatedly poll the API server. This mechanism is the foundation on which every controller's reconciliation loop is built.

Extending the Object Model

Custom Resource Definitions

A Custom Resource Definition (CRD) registers an entirely new resource kind with the API server, complete with its own schema, versioning, and validation rules, after which the new kind behaves identically to a built-in resource: it can be created, watched, labeled, and managed with the same tooling.

API Aggregation

For cases requiring behavior beyond what CRDs support, an aggregated API server can be registered to serve a distinct API group directly, while still appearing to clients as part of the unified Kubernetes API surface accessed through the primary API server endpoint.