# Native Subresource Support in Kubectl
> Interact with Kubernetes subresources like `status` and `scale` using `kubectl` natively with the new `--subresource` flag, no more raw HTTP calls.

Canonical: https://blog.abhimanyu-saharan.com/posts/native-subresource-support-in-kubectl
Published: 2025-06-29
Last updated: 2025-06-29
Authors: Abhimanyu Saharan
Categories: Kubernetes

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](https://github.com/kubernetes/enhancements/tree/master/keps/sig-cli/2590-kubectl-subresource-support) 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

```sh
# 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

```sh
# 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:

```sh
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`.

## FAQ

### What is the --subresource flag in kubectl?

The `--subresource` flag allows users to interact directly with subresources such as `status`, `scale`, and `resize` using standard kubectl commands like `get`, `patch`, `edit`, `apply`, and `replace`.

### Why was this feature introduced?

Previously, managing subresources required raw API calls or `curl`, making it inconvenient. This enhancement integrates subresource access into `kubectl`, making it more intuitive and script-friendly.

### Which subresources are currently supported?

Only `status` and `scale` are supported as of now. Attempting to use other subresources (e.g., `logs`) will return an error.

### Can I use this with Custom Resource Definitions (CRDs)?

Yes, provided the CRD defines a `status` or `scale` subresource. The same `--subresource` flag will work for CRDs that support these subresources.

### Is this feature available in all Kubernetes versions?

No. It requires Kubernetes v1.24+ due to API changes introduced in that version. Full GA support is available starting with v1.33.