Kubernetes HPA Spec Structure

Kubernetes HPA Spec Structure is the precise schema of the HorizontalPodAutoscaler object's spec field, defining every configurable field a workload owner can set to control scaling target, boundaries, metric sources, and scaling behavior. Understanding the exact structure and semantics of each field is necessary for writing correct HPA manifests rather than relying on partial or copied examples that may not fit a given workload's actual requirements.

Top-Level Spec Fields

scaleTargetRef

Identifies the controller the HPA manages, requiring apiVersion, kind, and name; this is the only required field establishing what the rest of the spec applies to.

spec:
  scaleTargetRef:
    apiVersion: apps/v1
    kind: Deployment
    name: api-service

minReplicas and maxReplicas

minReplicas (optional, defaulting to 1) and maxReplicas (required) bound the range within which the HPA is permitted to set the replica count; the computed desired replica count is always clamped to this range regardless of what the metric-based calculation would otherwise produce.

spec:
  minReplicas: 2
  maxReplicas: 20

The metrics Array

Metric Types

Each entry in metrics has a type of Resource, Pods, Object, ContainerResource, or External, each with its own nested structure specifying what is measured and how the target is expressed.

metrics:
- type: Resource
  resource:
    name: cpu
    target:
      type: Utilization
      averageUtilization: 70
- type: Pods
  pods:
    metric:
      name: packets-per-second
    target:
      type: AverageValue
      averageValue: "1k"

Target Types Within a Metric

target.type determines how the target value is interpreted: Utilization (a percentage of the requested resource, valid only for Resource and ContainerResource types), AverageValue (an average per-pod value), or Value (an absolute value, valid for Object and External types).

metrics:
- type: External
  external:
    metric:
      name: queue_depth
    target:
      type: Value
      value: "100"

ContainerResource Metrics

ContainerResource metrics target a specific named container within a multi-container pod rather than aggregating across all containers, useful when a sidecar's resource consumption should not influence the scaling decision meant to track only the primary application container's load.

metrics:
- type: ContainerResource
  containerResource:
    name: cpu
    container: app
    target:
      type: Utilization
      averageUtilization: 70

The behavior Field

scaleUp and scaleDown Substructures

behavior.scaleUp and behavior.scaleDown each independently configure stabilizationWindowSeconds, one or more policies (each with a type of Pods or Percent, a value, and a periodSeconds), and a selectPolicy determining how multiple applicable policies combine.

behavior:
  scaleDown:
    stabilizationWindowSeconds: 300
    selectPolicy: Min
    policies:
    - type: Percent
      value: 50
      periodSeconds: 60
    - type: Pods
      value: 2
      periodSeconds: 60

selectPolicy Semantics

selectPolicy: Max (the default for scale-up) chooses the policy resulting in the largest replica change; Min (the default for scale-down) chooses the smallest; Disabled turns off scaling in that direction entirely, useful for a workload that should only ever scale up automatically while scale-down is handled through a separate, deliberate process.

behavior:
  scaleDown:
    selectPolicy: Disabled

Reading the status Subresource

Observing Current State

The HPA's status field, populated by the controller rather than set by the user, reports currentReplicas, desiredReplicas, currentMetrics (the most recently observed values), and conditions (AbleToScale, ScalingActive, ScalingLimited), which together explain the controller's most recent decision and any obstacles it encountered.

kubectl get hpa api-service -o jsonpath='{.status.conditions}'

Version Differences: autoscaling/v1 vs autoscaling/v2

The original autoscaling/v1 API version supports only CPU-based scaling with a simpler spec structure; autoscaling/v2 (which superseded the now-removed v2beta1/v2beta2 versions) introduced the full metrics array and behavior field described here, and is the version that should be used for any new HPA definition requiring more than basic CPU scaling.