Last reviewed: November 8, 2026 (Asia/Shanghai); official references checked November 7 UTC.
Direct answer
Review a Kubernetes HorizontalPodAutoscaler (HPA) in a coding-agent patch by checking its target workload, metric inputs, replica bounds, and scaling policy together. Then exercise a load increase and recovery in a disposable environment, retaining the HPA recommendation alongside actual Pod readiness and application results. An accepted manifest establishes configuration validity; working autoscaling requires additional evidence.
The Horizontal Pod Autoscaling reference explains the controller algorithm and its conservative handling of missing metrics. The official walkthrough demonstrates load and recovery observations. The autoscaling/v2 API reference defines the configuration and status fields used below.
Who this is for
Use this workflow when a coding agent changes an HPA, the Deployment it targets, CPU requests used for utilization, or Helm values and Kustomize overlays that render those resources. The worked example uses CPU utilization for a Service-backed Deployment. Custom metrics and StatefulSets require additional review of their metric and workload contracts.
Give the agent the supported cluster version, service availability requirement, expected load, resource policy, and capacity ceiling. Ask it to identify every field that changes the scaling decision. The configuration and test matrix below are proposed review fixtures; this article reports no executed cluster tests or deployment outcomes.
Key takeaways
- Confirm the exact target and establish which tool owns its replica count.
- Calculate CPU utilization against requests; changing a request also changes the HPA input.
- Verify the metrics provider before interpreting a scaling result.
- Distinguish the desired replica count from running, ready, and serving capacity.
- Review stabilization and scaling-rate policies separately.
- Test metric failure and recovery as well as the healthy load path.
Sources checked
Three primary Kubernetes pages were retrieved successfully on November 7, 2026 UTC:
- Horizontal Pod Autoscaling documents utilization, the replica formula, missing metrics, readiness handling, multiple metrics, scaling policies, and replica-ownership migration.
- HorizontalPodAutoscaler Walkthrough
documents Metrics Server, an
autoscaling/v2example, load testing, and HPA status conditions. - HorizontalPodAutoscaler API defines the target reference, replica bounds, behavior fields, and status fields.
These maintained technical references support an evergreen task. Their pages report modifications on August 3, March 15, and August 26, 2026, respectively; the generated API page identifies its refresh as Kubernetes v1.37. Match the references to the target cluster version. This guide uses established autoscaling/v2 fields and leaves newer tolerance and scale-to-zero features outside the example.
Contract details to verify
Establish the target and replica owner
Render the HPA and Deployment from the candidate’s actual environment values. Check scaleTargetRef.apiVersion, kind, and name, the namespace, and the target’s scale subresource. Record both objects’ UIDs and generations. Also retain the Deployment selector and rendered Pod template so observations can be connected to the workload being reviewed.
Inventory every process that writes the target replica count. The concept reference recommends removing spec.replicas from manifests when HPA manages scale: repeatedly applying a fixed count can reset the workload and cause flapping. That includes values generated by release tooling, not just a literal field in one YAML file.
Treat adoption as a separate transition. Simply deleting spec.replicas can have a one-time defaulting effect, depending on field ownership and the apply method. Follow the documented client-side or server-side ownership-transfer procedure and test the repository’s actual deployment path. For an existing HPA-managed workload, verify that a routine release preserves HPA ownership of scale.
Calculate what the CPU target means
For a Resource CPU metric with a Utilization target, inspect CPU requests on all relevant containers, including injected sidecars. Kubernetes calculates utilization relative to requests. Missing relevant requests can leave a Pod’s utilization undefined; they are not a zero-usage reading.
Consider four identical ready Pods, each using 200m CPU. Assume all metric samples are usable, no other metric is configured, and no bound or scaling policy limits the basic recommendation:
| CPU request per Pod | Observed utilization | Target | Basic replica recommendation |
|---|---|---|---|
250m | 200 / 250 = 80% | 60% | ceil(4 × 80 / 60) = 6 |
125m | 200 / 125 = 160% | 60% | ceil(4 × 160 / 60) = 11 |
The second row is an illustrative calculation at unchanged measured usage. Lowering the request increases utilization and the basic recommendation. It is therefore an autoscaling change even when the HPA YAML stays untouched. Conversely, increasing the request can suppress utilization-based scaling at the same usage. Neither choice establishes that the application has enough capacity.
The controller’s final decision also accounts for missing metrics, readiness, tolerance, stabilization, and rate policies. Use the calculation to expose the patch’s intended effect, then inspect the actual controller decision. The requests and limits review guide covers admission defaults, quota, scheduling, and runtime resource evidence.
Make replica bounds and removal rates explicit
The following HPA targets an existing reviewed Deployment named api in a disposable namespace. The numbers illustrate a policy to discuss with the service owner; derive real values from workload measurements and capacity constraints.
apiVersion: autoscaling/v2
kind: HorizontalPodAutoscaler
metadata:
name: api
namespace: agent-review
spec:
scaleTargetRef:
apiVersion: apps/v1
kind: Deployment
name: api
minReplicas: 2
maxReplicas: 12
metrics:
- type: Resource
resource:
name: cpu
target:
type: Utilization
averageUtilization: 60
behavior:
scaleUp:
stabilizationWindowSeconds: 0
policies:
- type: Pods
value: 4
periodSeconds: 60
scaleDown:
stabilizationWindowSeconds: 300
policies:
- type: Pods
value: 1
periodSeconds: 60
Here the lower bound is two desired replicas, while the upper bound permits twelve. Neither bound guarantees that those replicas can schedule or serve. Check quota, eligible node capacity, startup time, downstream connection limits, and the application’s required redundancy. Raising maxReplicas needs an explicit capacity decision.
The scale-up policy permits an increase of at most four replicas over its 60-second policy interval. The scale-down policy permits removal of at most one over its interval. These are limits on changes, not instructions to add or remove that many Pods on a timer. The metric recommendation and other rules still apply.
The 300-second scale-down stabilization window considers recent recommendations and uses the highest in that window. It can retain capacity after a short load dip; it does not promise that every recovery finishes exactly five minutes after load stops. The API distinguishes the recommendation window from the rate-policy interval. When several policies are configured for one direction, the concept reference explains that Max selects the largest permitted change and Min the smallest; review that selection explicitly.
Verify the metric path and capture current status
The walkthrough requires a deployed and configured Metrics Server for resource metrics. Identify that provider before testing. For a custom or external metric, additionally record the adapter, metric name, label selector, units, aggregation rule, and owner. An accepted metric specification does not prove that a usable value is returned.
With kubectl and jq available, this read-only capture summarizes the example HPA. Replace the context and namespace with the approved test environment:
kubectl --context review-cluster --namespace agent-review get hpa api -o json |
jq '{uid: .metadata.uid,
generation: .metadata.generation,
observedGeneration: .status.observedGeneration,
target: .spec.scaleTargetRef,
bounds: {min: .spec.minReplicas, max: .spec.maxReplicas},
metrics: .spec.metrics,
behavior: .spec.behavior,
current: .status.currentReplicas,
desired: .status.desiredReplicas,
currentMetrics: .status.currentMetrics,
lastScaleTime: .status.lastScaleTime,
conditions: .status.conditions}'
Check the command’s exit status and preserve a timestamp with the result. Compare status.observedGeneration, when reported, with the current generation before attributing status to a new specification. Capture the target Deployment and its matching Pods alongside it. Retain desired, updated, ready, and available counts, Pod UIDs, scheduling diagnostics, and harmless application requests.
The walkthrough distinguishes three useful conditions. AbleToScale concerns access to the target scale and conditions that prevent updating it. ScalingActive indicates whether the controller can calculate a desired scale; metric-fetch problems commonly make it false. ScalingLimited indicates that a minimum or maximum bound constrained the desired scale. Read each condition’s reason and message instead of treating one true condition as an overall pass.
HPA desiredReplicas is its latest calculated count. New Pods may still be Pending or unready. For a Deployment, the Deployment controller continues to own ReplicaSets and replacement behavior. Use the Deployment rollout review guide
when the candidate also changes the Pod template or rollout strategy.
Exercise load, recovery, and metric failure
Start with a known healthy baseline in the disposable environment. Fix the image, requests, load generator, metric configuration, and observation duration between baseline and candidate runs. Use bounded synthetic traffic through the actual Service, with an explicit stop condition. Record both controller observations and application latency or error results.
The controller runs intermittently; the concept page gives a default synchronization interval of 15 seconds. Metric collection, scheduling, startup, readiness, and stabilization add delays. Set an observation deadline appropriate to the fixture and collect timestamps rather than requiring a change at an exact synchronization boundary.
| Controlled case | Evidence to retain |
|---|---|
| Sustained load above target | Metric reading, HPA desired count, target replica change, new Pod identities, readiness, and application results |
| Load returns to baseline | Metric recovery, stabilization and removal-policy timeline, minimum bound, and continued service checks |
| Metric becomes unavailable in an isolated fixture | Provider diagnostic, HPA conditions and events, observed replica behavior, and recovery after restoring the metric |
| Recommended scale reaches the maximum | Bound and limiting condition, actual schedulable capacity, and whether the application still meets its requirement |
| New replicas remain unready | Pod and workload diagnostics, HPA status, and evidence distinguishing desired capacity from serving capacity |
Use an isolated test provider or fixture-specific fault for the metric-failure case. Do not interrupt a shared production metrics service. Restore a healthy baseline between cases and retain the original candidate identity throughout.
The concept reference explains why missing data deserves its own test. Missing Pod metrics dampen possible scaling changes through conservative assumptions. Not-yet-ready Pods can also dampen CPU-driven scale-up. The utilization shown in HPA status does not necessarily include the adjustments used for the final decision.
If a patch adds multiple metrics, extend the test matrix. The controller calculates a proposal for each and uses the largest desired count. When one metric cannot be converted and the available metrics suggest scaling down, the controller skips that scale-down. A healthy metric can still trigger scale-up. Preserve every metric’s status so a missing input cannot be mistaken for low demand.
Failure modes
A CPU-request edit is approved as a scheduling-only change. Recalculate utilization at representative usage and review the HPA consequence. Lowering the request can increase the desired count.
A fixed replica field keeps overriding the controller. Inspect rendered releases and field ownership. Test the ownership-transfer procedure instead of simply deleting the field and assuming capacity remains stable.
A missing metric is recorded as zero. Preserve the provider error and controller diagnostic. The documented algorithm handles missing data conservatively.
The desired count is presented as healthy capacity. Correlate the HPA recommendation with workload status, Pod readiness, scheduling, and application requests.
A policy interval is described as a recurring action. It limits permitted changes over the interval. Actual changes still depend on recommendations, bounds, and stabilization.
Old status approves a new configuration. Retain UIDs, generations, metric settings, and timestamps. A replaced object or later edit needs its own evidence.
FAQ
Does a CPU utilization target mean a percentage of the CPU limit?
No. The documented utilization calculation uses the requested CPU resource. Inspect the effective requests, including admission defaults, before interpreting the percentage.
Does increasing maxReplicas add node capacity?
No. It raises the HPA’s permitted desired replica count. Scheduling, quota, available nodes, and downstream capacity remain separate constraints.
Does a 300-second stabilization window delay every scale-up?
The example configures that window only for scale-down. Its scale-up window is zero, while rate policies and the rest of the system can still delay usable capacity.
Can a healthy CPU metric force scale-down when another metric fails?
The concept reference says scale-down is skipped when a metric cannot be converted and the available metrics recommend reducing replicas. The controller can still scale up when a healthy metric calls for more.
Reader next step
Choose one coding-agent HPA patch. Render it with its target workload, calculate utilization before and after request changes, and write down the replica owner, capacity bounds, and scaling-rate policy. In a disposable environment, collect a healthy baseline, sustained-load response, recovery timeline, and isolated metric-failure result. Attach HPA generations and recommendations alongside Pod identities and application observations so the reviewer can judge the exact configuration being proposed.