Native Subresource Support in Kubectl

Managing Kubernetes subresources like status and scale has traditionally been clunky for CLI users. Until recently, interacting with these required raw HTTP calls or complex curl invocations, making operations difficult to script and error-prone. With the graduation of KEP-2590 to stable in Kubernetes v1.33, users now have native support for subresource manipulation directly within kubectl.

Why It Matters¶

The Kubernetes API defines subresources such as status, scale, and resize to isolate specific update operations. These endpoints are commonly used by controllers, but until now, human users had no clean way to interact with them using kubectl. For example:

• Fetching the current status of a deployment required querying the full object or making raw HTTP requests.
• Updating replica counts through the scale subresource was either not possible via kubectl or required complex scripting.
• CustomResourceDefinitions (CRDs) with subresources were even more tedious to handle.

This KEP introduces a --subresource flag across key kubectl commands, streamlining these workflows.

New Capability: --subresource Flag¶

You can now use the --subresource flag with the following commands:

• kubectl get
• kubectl patch
• kubectl edit
• kubectl apply
• kubectl replace

This change enables consistent and declarative interaction with subresources for both built-in and custom resource types.

Example: Get Deployment Status or Scale¶

# View status subresource (same output as full object)
kubectl get deployment nginx-deployment --subresource=status

# View current replica counts via scale subresource
kubectl get deployment nginx-deployment --subresource=scale

Example: Patch Subresource¶

# Update replica count using scale subresource
kubectl patch deployment nginx-deployment --subresource=scale --type=merge -p '{"spec":{"replicas":2}}'

This is particularly powerful for CRDs that expose scale or status endpoints.

Behavior for Unsupported Subresources¶

The CLI includes input validation and proper error handling:

kubectl get pod nginx --subresource=logs
# error: --subresource must be one of [status scale], not "logs"

kubectl get pod nginx --subresource=scale
# Error from server (NotFound): the server could not find the requested resource

How It Works¶

The enhancement builds on the resource builder and visitor pattern already in use within kubectl, adding a .WithSubresource() chain to target the correct API path. Table printer support was extended to pretty-print responses from status and scale subresources, ensuring consistency in output formatting.

For CRDs:

• status output reuses additionalPrinterColumns defined in the CRD spec.
• scale output mimics native resources by adding desired/available replicas.

Maturity Timeline¶

• Alpha: Introduced in Kubernetes v1.25 with initial support for get, patch, edit, and replace.
• Beta: Promoted in v1.27 with apply support and e2e coverage.
• GA: Graduated in v1.33 after over a year of stable usage with no critical issues.

Compatibility and Rollback¶

• The enhancement is entirely client-side.
• Users on older kubectl binaries will simply not see the flag.
• The API behavior remains unchanged, so operations can still be performed using curl as before.

Monitoring Usage¶

Cluster admins can track usage by inspecting audit logs for subresource API requests, particularly those hitting /status, /scale, or /resize.

Final Thoughts¶

This enhancement significantly improves the developer experience when managing Kubernetes objects via kubectl. By exposing subresources as first-class citizens, it simplifies scripting, debugging, and day-to-day cluster operations. Whether you're scaling CRDs, inspecting status updates, or editing a subset of object fields, --subresource brings much-needed ergonomics to Kubernetes CLI workflows.

If you're using custom controllers or automation pipelines that rely on subresources, it's time to update your toolchains and start leveraging this feature natively through kubectl.