Kubernetes Autoscaling Manifest Management

Kubernetes Autoscaling Manifest Management is the practice of defining HPA, VPA, and Cluster Autoscaler node group configuration as version-controlled declarative manifests co-located with the workloads they govern, bringing the same review, history, and reproducibility benefits to autoscaling configuration that apply to the rest of a cluster's infrastructure-as-code.

Co-Locating Autoscaling Config With Workloads

Keeping HPA and VPA Alongside Their Target

Placing an HPA or VPA manifest in the same file or directory as the Deployment or StatefulSet it targets keeps the complete picture of a workload's scaling behavior reviewable in one place, avoiding a situation where the autoscaling configuration is edited separately from the workload's own resource requests, replica defaults, or update strategy.

# deployment.yaml
apiVersion: apps/v1
kind: Deployment
metadata:
  name: api-service
spec:
  replicas: 3
  template:
    spec:
      containers:
      - name: app
        resources:
          requests: { cpu: 250m, memory: 256Mi }
---
# hpa.yaml (same directory)
apiVersion: autoscaling/v2
kind: HorizontalPodAutoscaler
metadata:
  name: api-service
spec:
  scaleTargetRef:
    apiVersion: apps/v1
    kind: Deployment
    name: api-service
  minReplicas: 3
  maxReplicas: 20

Avoiding Conflicting Replica Specifications

Because an HPA continuously overwrites the replica count on its target, the base Deployment manifest's own replicas field becomes effectively advisory once an HPA is attached; documenting this clearly in the manifest (a comment noting the field is HPA-managed, or omitting it from the base template entirely if the deployment tool supports that) avoids confusion when someone edits replicas expecting it to take lasting effect.

Managing Cluster Autoscaler Configuration Separately

Infrastructure-Level Versus Workload-Level Manifests

Because Cluster Autoscaler configuration (node group boundaries, cloud provider settings) operates at the infrastructure level rather than per-workload, it typically belongs in a separate, platform-team-owned repository or directory distinct from application HPA/VPA manifests, reflecting the different ownership and blast radius of infrastructure-level scaling changes.

infrastructure/
  cluster-autoscaler/
    deployment.yaml
    node-groups.yaml
apps/
  payments/
    deployment.yaml
    hpa.yaml
    vpa.yaml

Coordinating Cross-Repository Changes

When a workload's HPA maxReplicas is raised significantly, coordinating with whoever manages Cluster Autoscaler node group maximums confirms the cluster can actually provide the capacity the new ceiling implies, which requires a review process spanning both the application and infrastructure manifest repositories.

Review Practices for Autoscaling Changes

Treating Bound Changes as Consequential

A pull request changing minReplicas, maxReplicas, VPA maxAllowed values, or Cluster Autoscaler node group limits directly affects cost and capacity, warranting review with attention to the practical implications of the new bounds, not merely the YAML's syntactic correctness.

Validating Before Applying

Running autoscaling manifests through kubectl apply --dry-run=server in CI catches schema errors and invalid scaleTargetRef references before they reach a live cluster, and testing HPA behavior against representative load in a staging environment validates that a changed target or bound actually produces the intended scaling response.

kubectl apply --dry-run=server -f apps/payments/hpa.yaml

Lifecycle and Cleanup

Removing Autoscaling Config With the Workload

When a workload is decommissioned, removing its HPA and VPA manifests alongside the Deployment manifest itself, through the same GitOps reconciliation process, avoids leaving an orphaned HPA referencing a deleted target, which produces a persistently unhealthy AbleToScale: False condition with no practical effect but ongoing noise in cluster state.

Auditing Autoscaler Coverage

Periodically comparing the set of workloads with an HPA or VPA manifest against the full set of deployed workloads surfaces gaps — variable-load workloads still running a fixed replica count, or resource-intensive workloads never given VPA-informed sizing — that represent missed opportunities for the same efficiency and resilience benefits already realized elsewhere in the cluster.

kubectl get deployments --all-namespaces -o name | \
  comm -23 - <(kubectl get hpa --all-namespaces -o jsonpath='{range .items[*]}deployment.apps/{.spec.scaleTargetRef.name}{"\n"}{end}' | sort)