> ## Documentation Index
> Fetch the complete documentation index at: https://notes.kodekloud.com/llms.txt
> Use this file to discover all available pages before exploring further.
# HPA Scaling Policy
> Kubernetes Horizontal Pod Autoscaler scaling policies and configuration for predictable, stable autoscaling covering policy types, periodSeconds, selectPolicy, stabilization windows, and tuning guidance
In this lesson we cover Horizontal Pod Autoscaler (HPA) scaling policies — what they are, how they work, and how to configure them for predictable, stable autoscaling. HPA scaling policies define rules that tell Kubernetes how to change the number of pods in a Deployment/ReplicaSet based on metrics (CPU, memory, or custom/external metrics). Think of policies as the guardrails that control how aggressively or conservatively the HPA changes replica counts so your application has enough capacity without being overprovisioned.
Below are core concepts, examples, and practical guidance to make HPA scaling behavior clear and actionable.
## Policy structure and attributes
Policies are specified under `behavior` in the HPA spec. Each policy entry contains:
* `type` — the unit of change. Supported values include:
* `Pods` — an absolute number of pods to add or remove.
* `Percent` — a percentage change relative to the current replica count.
* `value` — numeric amount associated with `type` (e.g., `4` pods or `10` percent).
* `periodSeconds` — the minimum time window (in seconds) that must elapse between applications of this policy (limits how often that specific policy can be used).
Table: Policy attributes
| Attribute | Meaning | Example |
| --------------: | ------------------------------------------- | ----------- |
| `type` | Unit of change: `Pods` or `Percent` | `Pods` |
| `value` | Numeric amount for the chosen type | `4` or `10` |
| `periodSeconds` | Minimum seconds between policy applications | `60` |
When multiple policies are defined, you also control how the HPA chooses among them using `selectPolicy` (set under `scaleUp` or `scaleDown`). `selectPolicy` typically accepts values such as `Max` or `Min` to choose the largest or smallest allowed change among applicable policies.
Example combining `Pods` and `Percent` policies:
```yaml theme={null}
policies:
- type: Pods
value: 4
periodSeconds: 60
- type: Percent
value: 10
periodSeconds: 60
```
Explanation:
* The controller evaluates metrics frequently (by default every \~15s). A policy with `periodSeconds: 60` will not allow its change to be applied more often than once per 60 seconds.
* In the example above, the `Pods` policy allows changing replica count by up to 4 pods no more than once every 60 seconds. The `Percent` policy allows a 10% change every 60 seconds.
* Use `selectPolicy` to control which policy is selected when more than one policy could apply.
Practical calculation example:
* Current replicas: `20`
* `Percent` policy: `10%` → allows `2` pods
* `Pods` policy: `4` → allows `4` pods
* With `selectPolicy: Max` the HPA would allow up to `4` pods; with `selectPolicy: Min` it would allow `2` pods.
Default HPA controller sync period is typically 15 seconds (`--horizontal-pod-autoscaler-sync-period`). Policies control the minimum interval for specific changes via `periodSeconds`, so frequent metric checks can still be gated by policy limits.
Be cautious with overly aggressive policies (large `value` and short `periodSeconds`). They can cause rapid scaling that overshoots capacity or generates instability. Start conservative and validate with load testing.
## Configuring `behavior` with `scaleUp` and `scaleDown`
You configure policies inside `behavior.scaleUp` and `behavior.scaleDown`. You can also set `stabilizationWindowSeconds` to reduce thrashing for downward scaling.
Example full `behavior` section with `selectPolicy` and stabilization:
```yaml theme={null}
behavior:
scaleUp:
policies:
- type: Percent
value: 20
periodSeconds: 60
- type: Pods
value: 10
periodSeconds: 60
selectPolicy: Max
scaleDown:
stabilizationWindowSeconds: 300
policies:
- type: Percent
value: 10
periodSeconds: 60
- type: Pods
value: 4
periodSeconds: 60
selectPolicy: Max
```
Notes on this example:
* `scaleUp` permits up to 20% increase or 10 pods per 60 seconds, and `selectPolicy: Max` chooses the more permissive option when both apply.
* `scaleDown.stabilizationWindowSeconds: 300` instructs the controller to avoid scaling down below the highest recommended replica count seen in the last 5 minutes, helping prevent rapid downscales due to transient dips.
## Stabilization window (preventing thrash)
The stabilization window reduces thrashing — rapid up/down scaling — by making downward adjustments conservative. Key points:
* `stabilizationWindowSeconds` is typically applied under `behavior.scaleDown` (you can also set it for `scaleUp` if needed).
* When set (e.g., `300` seconds), the HPA looks back over the last X seconds of recommendations and will not scale down below the highest recommendation seen during that window.
* Typical pattern: allow scale-ups to happen quickly, but make scale-downs cautious to avoid oscillation due to short-lived metric drops.
Example timeline:
* Minute 1: HPA recommends 40 replicas (spike).
* Minute 2: metrics return and HPA recommends 30 replicas.
* With a 5-minute stabilization window, the controller will avoid reducing below the highest recommendation seen in that window (40) until the window elapses or until later metrics justify a smaller value.
Defaults and best practices:
* Many clusters tune scale-up to react quickly (short or zero stabilization) and scale-down to use a longer window (e.g., 300 seconds).
* Adjust stabilization windows based on workload volatility:
* Latency-sensitive workloads with short-lived spikes: shorter windows.
* Bursty or noisy workloads: longer windows to reduce churn.
## Practical guidance and tuning checklist
* Start conservative: combine small `Percent` values and modest `Pods` caps to avoid overshoot.
* Use `selectPolicy` to control behavior when multiple policies could apply (`Max` vs `Min`).
* Set `periodSeconds` to limit how often a policy can be enforced; avoid extremely short intervals.
* Add `stabilizationWindowSeconds` for scale-down to prevent thrash.
* Validate behavior with controlled load tests while monitoring pods, application latency, and metrics.
* Monitor the HPA events (`kubectl describe hpa `) to see recommendations, policy applications, and stabilization influences.
## Summary
* Policies under `behavior` govern how many pods (absolute or percent) can be added/removed and how often (`periodSeconds`).
* The HPA controller evaluates metrics frequently (default \~15s), but policy `periodSeconds` determines the minimum interval a specific rule can be applied.
* Use `selectPolicy` to choose how multiple policies are resolved (e.g., `Max` or `Min`).
* A stabilization window (especially for `scaleDown`) prevents rapid downscales and reduces oscillation.
* Combine policies, stabilization windows, and `selectPolicy` to balance responsiveness and stability for your application.
## Links and references
* [Horizontal Pod Autoscaler — Kubernetes](https://kubernetes.io/docs/tasks/run-application/horizontal-pod-autoscale/)
* [kube-controller-manager options — `--horizontal-pod-autoscaler-sync-period`](https://kubernetes.io/docs/reference/command-line-tools-reference/kube-controller-manager/)
* For examples and HPA API fields, consult the Kubernetes API reference and HPA v2/v2beta2 docs.