Custom Subresources

Subresources are secondary API endpoints attached to a parent resource. Kubernetes uses them for scale and status operations, and you can define them for your custom resources.

Built-in Subresources

The most common subresources are scale and status:

# The scale subresource allows direct replica management
kubectl scale deployment myapp --replicas=5

# Behind the scenes, this PATCHes the scale subresource
kubectl get --raw /apis/apps/v1/namespaces/default/deployments/myapp/scale

# The status subresource separates spec updates from status updates
kubectl get --raw /apis/apps/v1/namespaces/default/deployments/myapp/status

Scale Subresource for CRDs

Enable the scale subresource on a CRD to integrate with kubectl scale and the Horizontal Pod Autoscaler:

apiVersion: apiextensions.k8s.io/v1
kind: CustomResourceDefinition
metadata:
  name: myapps.example.com
spec:
  group: example.com
  versions:
    - name: v1
      served: true
      storage: true
      subresources:
        scale:
          specReplicasPath: .spec.replicas
          statusReplicasPath: .status.replicas
          labelSelectorPath: .status.labelSelector
        status: {}
      schema:
        openAPIV3Schema:
          type: object
          properties:
            spec:
              type: object
              properties:
                replicas:
                  type: integer
            status:
              type: object
              properties:
                replicas:
                  type: integer

# Now you can scale your custom resource
kubectl scale myapp my-instance --replicas=3

# HPA can also target your custom resource
kubectl autoscale myapp my-instance --min=2 --max=10

Status Subresource

The status subresource enforces separation between user-managed spec and controller-managed status:

# With status subresource enabled:
# - kubectl apply only updates spec fields
# - Controllers update status via the /status endpoint

# Check status of a custom resource
kubectl get myapp my-instance -o jsonpath='{.status}'

# Controllers update status programmatically:
# PATCH /apis/example.com/v1/namespaces/default/myapps/my-instance/status

Custom Endpoints

For aggregated API servers, you can define arbitrary subresources beyond scale and status:

# Example: a "logs" subresource on your custom resource
kubectl get --raw /apis/example.com/v1/namespaces/default/myapps/my-instance/logs

# Example: an "exec" subresource for interactive access
kubectl get --raw /apis/example.com/v1/namespaces/default/myapps/my-instance/exec

Enable subresources on CRDs whenever your controller needs to update status independently of user-specified fields.