Merge pull request #51078 from lmktfy/20250526_tweak_hpa_task

Align HorizontalPodAutoscaler page to docs style guidance

Author: k8s-ci-robot

content/en/docs/tasks/run-application/horizontal-pod-autoscale.md

@@ -51,7 +51,7 @@ horizontal pod autoscaling.
 {{< mermaid >}}
 graph BT
 
-hpa[Horizontal Pod Autoscaler] --> scale[Scale]
+hpa[HorizontalPodAutoscaler] --> scale[Scale]
 
 subgraph rc[RC / Deployment]
     scale
@@ -170,12 +170,12 @@ determining whether to set aside certain CPU metrics. Instead, it
 considers a Pod "not yet ready" if it's unready and transitioned to
 ready within a short, configurable window of time since it started.
 This value is configured with the `--horizontal-pod-autoscaler-initial-readiness-delay`
-flag, and its default is 30 seconds.
+command line option, and its default is 30 seconds.
 Once a pod has become ready, it considers any transition to
 ready to be the first if it occurred within a longer, configurable time
 since it started. This value is configured with the
-`--horizontal-pod-autoscaler-cpu-initialization-period` flag, and its
-default is 5 minutes.
+`--horizontal-pod-autoscaler-cpu-initialization-period` command line option,
+and its default is 5 minutes.
 
 The \\( currentMetricValue \over desiredMetricValue \\) base scale ratio is then
 calculated, using the remaining pods not set aside or discarded from above.
@@ -212,47 +212,49 @@ the current value.
 
 Finally, right before HPA scales the target, the scale recommendation is recorded. The
 controller considers all recommendations within a configurable window choosing the
-highest recommendation from within that window. This value can be configured using the
-`--horizontal-pod-autoscaler-downscale-stabilization` flag, which defaults to 5 minutes.
+highest recommendation from within that window. You can configure this value using the
+`--horizontal-pod-autoscaler-downscale-stabilization` command line option, which defaults to 5 minutes.
 This means that scaledowns will occur gradually, smoothing out the impact of rapidly
 fluctuating metric values.
 
-### Pod readiness and autoscaling metrics
+## Pod readiness and autoscaling metrics
 
-The HorizontalPodAutoscaler (HPA) controller includes two flags that influence how CPU metrics are collected from Pods during startup:
+The HorizontalPodAutoscaler (HPA) controller includes two command line options 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.
+  This command line option helps **exclude misleading high CPU usage** from initializing Pods (for example: Java apps warming up) in HPA scaling decisions.
 
-2. `--horizontal-pod-autoscaler-initial-readiness-delay` (default: 30 seconds)
+1. `--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:**
+
+You can only set these command line options cluster-wide.
+
+### Key behaviors for pod readiness {#pod-readiness-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:
+### Good practice for pod readiness {#pod-readiness-good-practices}
 
 - Configure a `startupProbe` that doesn't pass until the high CPU usage has passed, or
 - Ensure your `readinessProbe` only reports `Ready` **after** the CPU spike subsides, using `initialDelaySeconds`.
 
 And ideally also set `--horizontal-pod-autoscaler-cpu-initialization-period` to **cover the startup duration**.
 
-## API Object
+## API object
 
-The Horizontal Pod Autoscaler is an API resource in the Kubernetes
+The HorizontalPodAutoscaler is an API kind in the Kubernetes
 `autoscaling` API group. The current stable version can be found in
 the `autoscaling/v2` API version which includes support for scaling on
 memory and custom metrics. The new fields introduced in
@@ -512,7 +514,7 @@ default can be updated for both scale-up and scale-down using the
 `--horizontal-pod-autoscaler-tolerance` command line argument. (You can't use the Kubernetes API
 to configure this default value.)
 
-### Default Behavior
+### Default behavior
 
 To use the custom scaling not all fields have to be specified. Only values which need to be
 customized can be specified. These custom values are merged with default values. The default values
@@ -538,7 +540,7 @@ behavior:
     selectPolicy: Max
 ```
 For scaling down the stabilization window is _300_ seconds (or the value of the
-`--horizontal-pod-autoscaler-downscale-stabilization` flag if provided). There is only a single policy
+`--horizontal-pod-autoscaler-downscale-stabilization` command line option, if provided). There is only a single policy
 for scaling down which allows a 100% of the currently running replicas to be removed which
 means the scaling target can be scaled down to the minimum allowed replicas.
 For scaling up there is no stabilization window. When the metrics indicate that the target should be