5 Kubernetes API and Object Model

Kubernetes API and Object Model is the design foundation through which every entity in a Kubernetes cluster, from workloads to configuration to infrastructure abstractions, is represented as a structured, versioned resource accessible through a single consistent REST API, rather than through disparate ad hoc interfaces.

The API Server as the Single Entry Point

Uniform Access

All interaction with a Kubernetes cluster, whether from the kubectl command-line tool, a controller, or an external application, passes through the same API server using the same HTTP conventions, meaning any client capable of speaking REST can inspect or modify cluster state.

Resource-Oriented Design

The API is organized around resources rather than actions. Instead of exposing an endpoint that performs a specific operation, Kubernetes exposes resources that can be created, read, updated, or deleted, with the underlying controllers deciding what actions to take in response to those changes.

Anatomy of an Object

apiVersion, kind, metadata, spec, and status

Every Kubernetes object follows the same basic structure: an apiVersion and kind identifying the resource type, metadata describing identifying information such as name and labels, a spec describing the desired state, and a status describing the last observed actual state.

Spec and Status Separation

This separation is fundamental to the declarative model. Clients only ever write to spec, describing what they want, while controllers write to status, reporting what is actually happening, which prevents clients and controllers from fighting over the same fields.

API Groups and Versioning

Grouping Resources

Resources are organized into API groups, such as the core group for fundamental resources like Pods and Services, and named groups like apps or batch for higher-level workload resources like Deployments and Jobs.

Version Stability Levels

Each API version carries a stability designation: alpha versions may change or be removed without notice, beta versions are more stable but may still evolve, and stable (v1) versions are guaranteed to remain backward compatible across releases.

Labels, Selectors, and Annotations

Labels

Labels are arbitrary key-value pairs attached to objects, used to organize and select subsets of resources. They are the mechanism by which loosely coupled relationships, such as a Service selecting the Pods it should route to, are expressed.

Selectors

Selectors are queries against labels, used throughout the API by Services, ReplicaSets, and NetworkPolicies to dynamically determine which objects they apply to.

Annotations

Annotations also attach key-value metadata to objects but are intended for non-identifying information, such as build details or tooling-specific configuration, and are not used for selection.

Watch and Informers

The Watch Mechanism

Rather than requiring clients to poll for changes, the API server supports a watch mechanism that streams change events as they happen, allowing controllers to react to cluster state changes with low latency.

Informers

Client libraries build on the watch mechanism with informers, which maintain a local, continuously updated cache of resources, reducing load on the API server when many controllers need to observe the same resource type.

Extending the Object Model

Custom Resource Definitions

Custom Resource Definitions (CRDs) allow new object types to be registered with the API server, extending the object model to represent domain-specific concepts using the same conventions as built-in resources.

API Aggregation

The aggregation layer allows entirely separate API servers to be registered underneath the main API server's URL space, enabling more advanced extension scenarios beyond what CRDs alone support.

API Interaction Diagram

This uniform, resource-centric API design is what makes Kubernetes extensible: any tool that understands the conventions of the API can interoperate with the cluster without requiring special-cased integrations.