Skip to content

Add more clarity for horizontal-pod-autoscaler-cpu-initialization-period #50558

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
wants to merge 1 commit into
base: main
Choose a base branch
from
+32 −0
Open

Add more clarity for horizontal-pod-autoscaler-cpu-initialization-period #50558

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
32 changes: 32 additions & 0 deletions content/en/docs/tasks/run-application/horizontal-pod-autoscale.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -217,6 +217,38 @@ highest recommendation from within that window. This value can be configured usi
This means that scaledowns will occur gradually, smoothing out the impact of rapidly
fluctuating metric values.

### Pod readiness and autoscaling metrics

The HorizontalPodAutoscaler (HPA) controller includes two flags that influence how CPU metrics are collected from Pods during startup:

1. `--horizontal-pod-autoscaler-cpu-initialization-period` (default: 5 minutes)

This defines the time window after a Pod starts during which its **CPU usage is ignored** unless:
- The Pod is in a `Ready` state **and**
- The metric sample was taken entirely during the period it was `Ready`.

This flag helps **exclude misleading high CPU usage** from initializing Pods (e.g., Java apps warming up) in HPA scaling decisions.

2. `--horizontal-pod-autoscaler-initial-readiness-delay` (default: 30 seconds)

This defines a short delay period after a Pod starts during which the HPA controller treats Pods that are currently `Unready` as still initializing, **even if they have previously transitioned to `Ready` briefly**.

It is designed to:
- Avoid including Pods that rapidly fluctuate between `Ready` and `Unready` during startup.
- Ensure stability in the initial readiness signal before HPA considers their metrics valid.

**Key behaviors:**
- If a Pod is `Ready` and remains `Ready`, it can be counted as contributing metrics even within the delay.
- If a Pod rapidly toggles between `Ready` and `Unready`, metrics are ignored until it’s considered stably `Ready`.

#### Best Practice:
If your Pod has a startup phase with high CPU usage, configure both:
- `--horizontal-pod-autoscaler-cpu-initialization-period` to **cover the startup duration**.
- Ensure your **readinessProbe** only reports `Ready` **after the CPU spike subsides**, using `initialDelaySeconds`.

This avoids scaling based on temporary spikes that do not reflect long-term workload needs.


## API Object

The Horizontal Pod Autoscaler is an API resource in the Kubernetes
Expand Down