5.2 Kubernetes API Resource Model

Kubernetes API Resource Model is the structural framework that defines how every manageable entity in a Kubernetes cluster, from a Pod to a custom application-specific type, is represented as a discrete, addressable resource with a consistent shape, a defined location within the API's grouping and versioning scheme, and a standard set of operations that can be performed against it.

The Concept of a Resource

Resources as Nouns

Within the API, a resource represents a category of object, such as pods, deployments, or configmaps, functioning as the noun against which HTTP-style verbs like create, get, list, update, and delete are applied, mirroring REST conventions while adding Kubernetes-specific semantics like server-side patching and watch streams.

Resources Versus Kinds

A kind describes the schema of an individual object, such as Pod or Deployment, while a resource is the pluralized, API-addressable collection of objects of that kind, such as pods or deployments; most kinds map to exactly one resource, though some kinds, like Scale, are exposed as subresources of multiple different parent resources.

Namespaced Versus Cluster-Scoped Resources

Every resource type is designated as either namespaced, meaning instances exist within the boundary of a specific Namespace and are only unique within that namespace, or cluster-scoped, meaning instances exist at the cluster level with names unique across the entire cluster, such as Nodes or PersistentVolumes.

API Groups and Versions

The Purpose of Grouping

API groups partition the overall resource space into logical collections, such as apps, batch, or networking.k8s.io, allowing related resource types to evolve together and allowing the API surface to grow without every resource competing for the same flat namespace of endpoints.

The Core Group

A special, unnamed core group, referenced as simply v1 in manifests, contains foundational resource types such as Pods, Services, and ConfigMaps that predate the introduction of formal API grouping and remain at the root of the API path structure for backward compatibility.

Version Maturity Levels

Within a group, resources are exposed at specific versions following a maturity progression, typically alpha, beta, and stable (denoted simply as v1, v2, and so on), with alpha versions subject to change or removal without notice and stable versions carrying strong backward compatibility guarantees.

Subresources

Purpose of Subresources

Subresources expose a distinct, separately addressable operation or view on a parent resource, such as a Pod's status or log subresource, or a Deployment's scale subresource, allowing different access controls and update semantics to apply independently from the main resource body.

Status as a Subresource

For most built-in resources, status is managed as a distinct subresource, meaning updates to the desired state in spec and updates to the observed state in status go through separate API calls, which is central to how controllers avoid interfering with each other when one writes intent and another writes observed outcome.

The Scale Subresource

Many workload resources, including Deployments, ReplicaSets, and StatefulSets, expose a common scale subresource with a uniform shape, allowing generic tooling such as the Horizontal Pod Autoscaler to adjust replica counts without needing resource-specific logic for each workload type.

Discovery and Introspection

The API Discovery Documents

The API server exposes discovery endpoints that enumerate every available API group, version, and resource, along with metadata about which HTTP verbs each resource supports, allowing clients like kubectl to dynamically discover the full resource model of a given cluster rather than relying on a hardcoded list.

OpenAPI Schema Publication

Alongside discovery, the API server publishes an OpenAPI schema describing the exact structure of every resource type's fields, which powers client-side validation, code generation for typed clients, and interactive documentation tooling.

Extending the Resource Model

Custom Resource Definitions

Custom Resource Definitions allow cluster operators to register entirely new resource types that participate in the same discovery, versioning, validation, and storage machinery as built-in resources, without requiring changes to the API server's own codebase.

The Aggregation Layer

For cases requiring custom storage or processing logic beyond what CRDs alone provide, the API aggregation layer allows a separate API server to be registered under the main API server's namespace, serving specific resource types while still appearing as a unified part of the overall resource model to clients.

Practical Implications of the Model

Uniform Client Behavior

Because every resource, built-in or custom, follows the same structural and versioning conventions, generic tools such as kubectl get, kubectl apply, and RBAC policy enforcement work identically regardless of whether a resource is a core type like Pod or a domain-specific custom resource defined by a third-party operator.