Kubernetes API Resource Model

Kubernetes API Resource Model is the specific pattern by which the Kubernetes API exposes each type of manageable entity — Pods, Deployments, Services, and so on — as a "resource," a named, addressable collection of objects that supports a consistent, predictable set of operations regardless of what that resource actually represents. This model is what allows a single generic client like kubectl or a single generic library to interact with wildly different kinds of cluster state — networking, storage, workloads, policy — through one uniform interaction pattern, rather than requiring bespoke client logic for every distinct resource type.

Resources, Kinds, and Objects

Kind Versus Resource

A "Kind" identifies the schema of an object type in Go-like naming, such as Pod or Deployment, while a "resource" identifies the pluralized, URL-addressable collection through which instances of that Kind are accessed, such as pods or deployments; the API server maintains an explicit mapping between these, since some Kinds can be exposed as more than one resource path, particularly through subresources.

Objects as Instances

An individual object is a specific instance of a Kind, uniquely identified within its resource collection by name (and namespace, for namespace-scoped resources); the resource model's URL scheme reflects this hierarchy directly, with paths structured around group, version, resource, optional namespace, and optional object name.

The Standard REST Verb Set

CRUD Operations Mapped to HTTP

Every resource in the model supports a consistent set of operations mapped onto HTTP methods: list and get (HTTP GET) to read a collection or a single object, create (HTTP POST) to add a new object, update and patch (HTTP PUT and PATCH) to modify an existing object, and delete (HTTP DELETE) to remove one, and this consistency is what allows generic tooling to operate on any resource without type-specific logic for basic CRUD behavior.

Watch as a First-Class Operation

Beyond simple CRUD, the resource model treats watch as a first-class operation, allowing a client to open a long-lived connection and receive a stream of add, update, and delete events for a resource collection as they happen, rather than needing to poll list repeatedly; this watch capability is the foundation that every controller's reconciliation loop is built on.

Subresources

Purpose of Subresources

Certain resources expose subresources — additional, more specifically scoped endpoints nested under the main resource path, such as a Pod's status or log subresource, or a Deployment's scale subresource — which allow finer-grained access control and specialized operations without requiring an entirely separate top-level resource type.

Status as the Canonical Subresource Example

The status subresource, present on most built-in workload and infrastructure types, is what allows the API server to enforce that only components with the appropriate permission (typically the responsible controller) can write observed state, while ordinary users retain permission to modify only the spec portion of the same object through the main resource path.

Field Selectors, Label Selectors, and Filtering

Label Selectors as Query Mechanisms

The resource model supports filtering list and watch operations by label selector, allowing a client to request only objects matching specific label key-value criteria, which is the mechanism Services, ReplicaSets, and many controllers use internally to determine which objects they are responsible for, in addition to being available directly to API clients.

Field Selectors

A more limited field selector mechanism allows filtering on a small set of specific, indexed fields such as an object's name or a Pod's node assignment, complementing label selectors for the narrower set of cases where filtering on a structural field rather than a user-assigned label is needed.

Resource Versioning and Optimistic Concurrency

resourceVersion as a Concurrency Token

Every object carries a resourceVersion string, opaque to clients but monotonically meaningful to the API server, which is used to implement optimistic concurrency control: an update or delete operation can specify the resourceVersion it expects the object to currently have, and the API server rejects the operation with a conflict error if the object has since changed, preventing silent lost updates from concurrent writers.

resourceVersion in Watch Resumption

The same resourceVersion mechanism allows a client to resume a watch from a specific point rather than from the beginning, which is essential for controllers that need to recover from a dropped connection without missing or duplicating events, reconnecting with the last resourceVersion they successfully processed.