Kubernetes API Subresource Model

Kubernetes API Subresource Model is the pattern by which a single resource exposes additional, narrowly scoped API endpoints nested beneath its main path, each subresource carrying its own access control, its own accepted content, and often its own semantics distinct from the resource's primary CRUD interface, allowing fine-grained separation of concerns within what is conceptually a single object. Subresources exist because treating every operation on an object as a single undifferentiated read/write surface would make it impossible to grant, for instance, permission to scale a Deployment without also granting permission to change its container image, or to view a Pod's logs without granting permission to delete it.

Why Subresources Exist

Separating Concerns Within One Object

Many objects need to expose operations that are conceptually related to the object but require different access rules, different payload formats, or different write semantics than the object's core spec; rather than inventing an entirely separate top-level resource type for each such concern, the subresource model nests these operations under the parent resource's own path, keeping the relationship between object and operation explicit in the URL structure itself.

Independent RBAC Grants

Because RBAC rules can target a subresource specifically (expressed as resource/subresource in a Role's rules), granting access to pods/log without granting access to pods itself, or to deployments/scale without granting write access to a Deployment's full spec, becomes a straightforward policy statement rather than requiring custom authorization logic.

The status Subresource

Enforcing the Spec/Status Separation

The status subresource, present on nearly every built-in workload and infrastructure type, is what makes the broader spec/status object model pattern actually enforceable: write access to the main resource path can be granted to ordinary users for editing spec, while write access to the status subresource is reserved for the specific controller responsible for that type, preventing accidental or malicious status tampering by clients that should only be declaring desired state.

Independent resourceVersion Semantics

Updates through the status subresource still participate in the same overall object's optimistic concurrency, sharing the object's single resourceVersion, but the API server restricts what portion of the object a status-subresource write is permitted to modify, silently or explicitly rejecting changes to spec fields submitted through that path depending on the request format used.

The scale Subresource

A Minimal, Uniform View for Scaling

The scale subresource exposes a deliberately reduced schema — essentially a target replica count and a label selector — shared across every scalable type (Deployments, ReplicaSets, StatefulSets, and custom types that opt in), which is what allows a single, type-agnostic component such as the Horizontal Pod Autoscaler to read and adjust replica counts across many different Kinds without needing type-specific client code for each.

Enabling Scale on Custom Resources

CustomResourceDefinitions can opt into exposing a scale subresource by declaring which JSON paths within their schema correspond to the replica count and selector fields the generic scale interface expects, letting custom controllers participate in the same generic autoscaling and scaling tooling built-in types use.

Action-Oriented and Non-Object Subresources

eviction as an Action

The eviction subresource on Pods accepts an Eviction object as its request payload but behaves as an action trigger rather than a conventional object update, initiating the same graceful termination sequence a manual deletion would, while additionally consulting any applicable PodDisruptionBudget before proceeding, which is why voluntary disruption tooling uses this subresource rather than a plain delete request.

log and exec as Non-JSON Subresources

Some subresources, such as a Pod's log and exec, do not operate on structured JSON objects at all; log streams raw container log output, and exec upgrades the connection to a bidirectional streaming protocol for running commands inside a container interactively, illustrating that the subresource model extends beyond CRUD-style object management to cover fundamentally different interaction patterns layered onto the same underlying resource identity.

Subresources and CustomResourceDefinitions

Declaring Status and Scale for Custom Types

CRD authors can enable the status and scale subresources for their custom types through explicit configuration in the CustomResourceDefinition itself, and doing so is what allows a custom controller managing that type to follow the same spec/status separation and RBAC-enforceable boundaries that built-in types benefit from, rather than exposing every field through a single undifferentiated write path.