Kubernetes Scale Subresource Usage

Kubernetes Scale Subresource Usage covers the mechanics of the /scale subresource itself — the standardized, minimal API surface that lets any resource type participate in horizontal scaling without exposing its full specification, and the specific requirements a resource must satisfy to be usable as an HPA target or with kubectl scale.

The Scale Object

A Minimal, Standardized Shape

Regardless of which underlying resource type it belongs to, the /scale subresource always returns and accepts the same simplified Scale object shape: a spec.replicas field representing desired replica count, and a status.replicas field (plus, for HPA compatibility, a status.selector) reporting current state, decoupling the scaling interface from the full complexity of the underlying resource's own spec.

apiVersion: autoscaling/v1
kind: Scale
metadata:
  name: api-service
  namespace: payments
spec:
  replicas: 5
status:
  replicas: 5
  selector: app=api-service

Reading and Writing Through the Subresource

Any client, including kubectl scale and the HPA controller, interacts with this subresource independently of the resource's main endpoint, meaning a scale operation is a PATCH or PUT against /apis/apps/v1/namespaces/<ns>/deployments/<name>/scale rather than against the deployment's own primary resource path.

kubectl scale deployment api-service --replicas=5 -n payments

Requirements for Custom Resources

Declaring subresources.scale in a CRD

A CustomResourceDefinition must explicitly declare scale subresource support, specifying JSON paths within the custom resource's own schema that map to the standardized spec.replicas and status.replicas fields, and optionally a path or fixed value for status.selector.

apiVersion: apiextensions.k8s.io/v1
kind: CustomResourceDefinition
metadata:
  name: workerpools.batch.example.com
spec:
  versions:
  - name: v1
    subresources:
      scale:
        specReplicasPath: .spec.workerCount
        statusReplicasPath: .status.readyWorkers
        labelSelectorPath: .status.labelSelector

The Importance of status.selector for HPA

The HPA controller uses status.selector from the scale subresource to identify which pods belong to the target, which it needs in order to compute aggregate metrics like average CPU utilization across all of a workload's pods; a custom resource that implements the scale subresource without correctly populating this selector will cause the HPA to fail to compute meaningful metrics even though replica adjustment itself works.

kubectl get workerpool my-pool -o jsonpath='{.status.labelSelector}'

Consumers of the Scale Subresource

kubectl scale

The kubectl scale command is a thin client over the scale subresource, working uniformly across Deployment, ReplicaSet, StatefulSet, and any properly configured custom resource, without needing separate logic per resource type.

kubectl scale statefulset cache-cluster --replicas=6
kubectl scale workerpool my-pool --replicas=10

The HorizontalPodAutoscaler Controller

The HPA controller reads current replica count and pod selector through the scale subresource, computes a new desired replica count from observed metrics, and writes that new value back through the same subresource — never touching the target resource's primary spec fields directly, which is what allows the same HPA implementation to work uniformly across built-in and custom resource types.

Common Implementation Pitfalls

Mismatched Field Paths

A CustomResourceDefinition's specReplicasPath or statusReplicasPath pointing to a field that does not exist, or exists under a different structure than declared, causes scale subresource reads and writes to silently fail or behave unexpectedly; validating these paths against the actual custom resource schema during CRD development avoids a scale subresource that appears configured but does not function correctly.

Omitting the Selector for HPA Compatibility

A custom resource intended to work with the HPA but omitting labelSelectorPath will accept replica count changes but cause the HPA to report an inability to compute metrics, since it cannot determine which pods to aggregate — this is a frequently overlooked requirement distinct from basic scale subresource support.

Assuming Scale Subresource Support Implies Full HPA Compatibility

Implementing the scale subresource makes replica count adjustable through a standard interface, but full HPA support additionally depends on the underlying pods being correctly labeled and discoverable through the reported selector, and on metrics being available for those pods through the metrics pipeline the HPA queries.