1.5 Kubernetes API Definition
The Kubernetes API Definition provides structured endpoints for managing clusters, enabling programmatic control of containerized applications.
Kubernetes API Definition is the precise characterization of the Kubernetes API as a versioned, resource-oriented HTTP interface exposed by the API server, through which every representation of cluster state, and every change to that state, is read from or written to, forming the single authoritative interface for interacting with a cluster.
Defining the API by Its Contract
A REST-Style Resource Model
The Kubernetes API is defined by a consistent contract: every entity it manages is represented as a resource with a defined schema, identified by a URL path, and manipulated using standard HTTP verbs such as GET, POST, PUT, PATCH, and DELETE, rather than through operation-specific endpoints.
One Interface for All Clients
Every client of a Kubernetes cluster, whether a command-line tool, a controller, or a custom application, interacts with the cluster exclusively through this same API surface, meaning there is no separate, privileged interface available only to internal components.
What Constitutes an API Resource
Schema and Identity
An API resource is defined by its apiVersion and kind, which together identify its schema, and by metadata that includes a unique name within its scope, ensuring that every object the API manages can be unambiguously addressed.
Spec and Status as Defining Fields
The API's resource model is further defined by the convention of separating a spec field, representing desired state supplied by clients, from a status field, representing observed state reported by controllers, a distinction that holds across nearly every resource type in the system.
Versioning as Part of the Definition
Stability Guarantees Tied to Version
The API is explicitly defined with a versioning scheme, distinguishing alpha, beta, and stable versions, each carrying different guarantees about whether its schema may change in incompatible ways in future releases.
Multiple Versions Coexisting
A single resource type may be available simultaneously under multiple API versions during a transition period, with the API server responsible for converting between them, which is part of what allows the API to evolve without breaking existing clients immediately.
Boundaries of the API Definition
The API Server as the Sole Implementer
While many components read from and act on data exposed through the API, only the API server implements the API itself, meaning direct manipulation of the underlying data store, bypassing the API server, falls outside the scope of the API and is explicitly unsupported.
Extension Without Redefinition
Custom Resource Definitions and the aggregation layer extend the set of resources available through the API without altering the fundamental contract of the API itself; new resource types still follow the same versioning, schema, and verb conventions as built-in ones.