5.17 Kubernetes API Subresource Model

Kubernetes API Subresource Model is the mechanism by which a specific operation or view on a parent object is exposed as its own independently addressable API endpoint, allowing distinct access control, update semantics, or specialized behavior to apply to a narrow slice of an object's data or functionality without requiring that slice to be a separate top-level resource entirely.

What Makes Something a Subresource

A Distinct Path Under the Parent

A subresource is addressed by appending its name as an additional path segment after the parent object's name, such as /api/v1/namespaces/default/pods/my-pod/status or /api/v1/namespaces/default/pods/my-pod/log, making it reachable only in the context of a specific parent object instance rather than as an independent collection.

Independent RBAC Scoping

Because subresources are distinct API endpoints, RBAC rules can grant or deny access to them separately from the parent resource, such as permitting a service account to read a Pod's log subresource without granting broader read access to the Pod's full specification, or permitting a controller to write status without granting it write access to spec.

Status as the Most Common Subresource

Separating Desired From Observed State

The status subresource, enabled on nearly all built-in workload and infrastructure resource types, is the canonical example: updates to spec go through the main resource endpoint, while updates to status go through the /status subresource endpoint, enforcing the architectural separation between desired and observed state at the API access-control level, not merely by convention.

Controllers as Status Writers

A controller reconciling a resource is typically granted write access only to that resource's status subresource, alongside read access to the main resource, reflecting its role as an observer and reporter of outcome rather than an author of intent.

Scale as a Generic Subresource

Uniform Interface Across Workload Types

The scale subresource exposes a minimal, standardized shape, primarily a replicas field, on top of Deployment, ReplicaSet, StatefulSet, and other workload types, allowing generic autoscaling tooling such as the Horizontal Pod Autoscaler to read and adjust replica counts without needing type-specific logic for each different kind of scalable workload.

Decoupling Autoscaling From Workload Specifics

Because the scale subresource presents the same interface regardless of the underlying workload kind, an autoscaler can be written once against the generic scale shape and function correctly against any resource type that implements it, rather than requiring separate integration code per workload controller.

Action-Oriented Subresources

eviction

The eviction subresource on Pod objects provides a controlled, PodDisruptionBudget-aware way to request a pod's removal, distinct from a direct delete, allowing the eviction API to reject a request if honoring it would violate a configured disruption budget, something a plain delete operation would not check.

exec, attach, and portforward

Pods expose exec, attach, and portforward subresources that establish specialized, often streaming, connections into a running container, used by commands like kubectl exec and kubectl port-forward, representing subresources that model an interactive operation rather than a data view.

log

The log subresource streams a container's log output on demand, supporting parameters such as tailing a specific number of lines or following new output continuously, functioning as a read-oriented but dynamically generated subresource rather than a static, persisted piece of the object.

binding

The binding subresource is used specifically by the scheduler to assign a Pod to a Node, a narrowly scoped write operation that only the scheduler, or components with equivalent permission, is typically authorized to perform, keeping this sensitive assignment operation separate from general Pod update access.

Subresources on Custom Resources

Opting Into Status and Scale

Custom Resource Definitions can explicitly opt into status and scale subresource behavior through their schema configuration, allowing custom resource authors to adopt the same field-separation and generic-tooling-compatibility benefits that built-in resources have, without needing to define entirely new subresource machinery themselves.

Custom Subresources via Aggregated APIs

Resources served through the API aggregation layer, rather than through CRDs, can implement entirely bespoke subresources beyond status and scale, since an aggregated API server has full control over its own served endpoints, offering an extension point for functionality that the CRD-supported subresource set does not cover.