# Pod 水平自动扩缩
LLMS index: [llms.txt](/llms.txt)
---
在 Kubernetes 中，**HorizontalPodAutoscaler** 自动更新工作负载资源
（例如 Deployment 或者
StatefulSet），
目的是容量自动扩缩以满足需求。
水平扩缩意味着对增加的负载的响应是部署更多的 Pod。
这与“垂直（Vertical）”扩缩不同，对于 Kubernetes，
垂直扩缩意味着将更多资源（例如：内存或 CPU）分配给已经为工作负载运行的 Pod。
如果负载减少，并且 Pod 的数量高于配置的最小值，
HorizontalPodAutoscaler 会指示工作负载资源（Deployment、StatefulSet 或其他类似资源）缩减。
水平 Pod 自动扩缩不适用于无法扩缩的对象（例如：DaemonSet。）
HorizontalPodAutoscaler 被实现为 Kubernetes API
资源和控制器。资源决定了控制器的行为。
在 Kubernetes 控制平面内运行的水平
Pod 自动扩缩控制器会定期调整其目标（例如：Deployment）的所需规模，以匹配观察到的指标，
例如，平均 CPU 利用率、平均内存利用率或你指定的任何其他自定义指标。
使用水平 Pod 自动扩缩[演练示例](/zh-cn/docs/tasks/run-application/horizontal-pod-autoscale-walkthrough/)。
## HorizontalPodAutoscaler 是如何工作的？ {#how-does-a-horizontalpodautoscaler-work}
graph BT
hpa[HorizontalPodAutoscaler] --> scale[规模]
subgraph rc[Deployment]
scale
end
scale -.-> pod1[Pod 1]
scale -.-> pod2[Pod 2]
scale -.-> pod3[Pod N]
classDef hpa fill:#D5A6BD,stroke:#1E1E1D,stroke-width:1px,color:#1E1E1D;
classDef rc fill:#F9CB9C,stroke:#1E1E1D,stroke-width:1px,color:#1E1E1D;
classDef scale fill:#B6D7A8,stroke:#1E1E1D,stroke-width:1px,color:#1E1E1D;
classDef pod fill:#9FC5E8,stroke:#1E1E1D,stroke-width:1px,color:#1E1E1D;
class hpa hpa;
class rc rc;
class scale scale;
class pod1,pod2,pod3 pod
图 1. HorizontalPodAutoscaler 控制 Deployment 及其 ReplicaSet 的规模
Kubernetes 将水平 Pod 自动扩缩实现为一个间歇运行的控制回路（它不是一个连续的过程）。间隔由
[`kube-controller-manager`](/zh-cn/docs/reference/command-line-tools-reference/kube-controller-manager/)
的 `--horizontal-pod-autoscaler-sync-period` 参数设置（默认间隔为 15 秒）。
在每个时间段内，控制器管理器都会根据每个 HorizontalPodAutoscaler 定义中指定的指标查询资源利用率。
控制器管理器找到由 `scaleTargetRef` 定义的目标资源，然后根据目标资源的 `.spec.selector` 标签选择 Pod，
并从资源指标 API（针对每个 Pod 的资源指标）或自定义指标获取指标 API（适用于所有其他指标）。
* 对于按 Pod 统计的资源指标（如 CPU），控制器从资源指标 API 中获取每一个
HorizontalPodAutoscaler 指定的 Pod 的度量值，如果设置了目标使用率，控制器获取每个 Pod
中的容器[资源请求使用](/zh-cn/docs/concepts/configuration/manage-resources-containers/#requests-and-limits)情况，
并计算资源使用率。如果设置了目标原始值，将直接使用原始度量值（不再计算百分比）。
接下来，控制器根据平均的资源使用率或原始值（取决于指定的目标的类型）计算出扩缩的比例，进而计算出目标副本数。
需要注意的是，如果 Pod 某些容器未设置相关的资源请求，那么此 Pod 的 CPU 利用率将不会被定义。
自动扩缩器将不会为该指标采取任何操作。下面的[算法细节](#algorithm-details)章节将会介绍自动扩缩的详细算法。
* 如果 Pod 使用自定义指示，控制器机制与资源指标类似，区别在于自定义指标只使用原始值，而不是使用率。
* 如果 Pod 使用对象指标和外部指标（每个指标描述一个对象信息）。
这个指标将直接根据目标设定值相比较，并生成一个上面提到的扩缩比例。
在 `autoscaling/v2` 版本 API 中，这个指标也可以根据 Pod 数量平分后再计算。
HorizontalPodAutoscaler 的常见用途是将其配置为从聚合 API
（`metrics.k8s.io`、`custom.metrics.k8s.io` 或 `external.metrics.k8s.io`）获取指标。
`metrics.k8s.io` API 通常由名为 Metrics Server 的插件提供，需要单独启动。有关资源指标的更多信息，
请参阅 [Metrics Server](/zh-cn/docs/tasks/debug/debug-cluster/resource-metrics-pipeline/#metrics-server)。
对 [Metrics API 的支持](#support-for-metrics-apis)解释了这些不同 API 的稳定性保证和支持状态。
HorizontalPodAutoscaler 控制器访问支持扩缩的相应工作负载资源（例如：Deployment 和 StatefulSet）。
这些资源每个都有一个名为 `scale` 的子资源，该接口允许你动态设置副本的数量并检查它们的每个当前状态。
有关 Kubernetes API 子资源的一般信息，
请参阅 [Kubernetes API 概念](/zh-cn/docs/reference/using-api/api-concepts/)。
### 算法细节 {#algorithm-details}
从最基本的角度来看，Pod 水平自动扩缩控制器根据当前指标和期望指标来计算扩缩比例。
```math
\begin{equation*}
\text{期望副本数} = ceil\left\lceil \text{当前副本数} \times \frac{\text{当前指标}}{\text{期望指标}} \right\rceil
\end{equation*}
```
例如，如果当前指标值为 `200m`，而期望值为 `100m`，则副本数将加倍，
因为 \\( { 200.0 \div 100.0 } = 2.0 \\)。如果当前值为 `50m`，则副本数将减半，
因为 \\( { 50.0 \div 100.0 } = 0.5 \\)。如果比率足够接近 1.0（在[可配置的容差范围内](#tolerance)，默认为 0.1），
则控制平面会跳过扩缩操作。
如果 HorizontalPodAutoscaler 指定的是 `targetAverageValue` 或 `targetAverageUtilization`，
那么将会把指定 Pod 度量值的平均值做为 `currentMetricValue`。
在检查容差并决定最终值之前，控制平面还会考虑是否缺少任何指标，
以及有多少 Pod [`Ready`](/zh-cn/docs/concepts/workloads/pods/pod-lifecycle/#pod-conditions)。
对于 Pod 级资源指标，所有设置了删除时间戳（即正在终止或删除中的对象）的 Pod 都会被忽略，
同时会剔除所有处于 Failed 状态的 Pod。对于外部指标和对象指标，副本数基于处于 Running 且
Ready 状态的 Pod 数量进行计算；对于已进入终止流程但仍处于 Ready 状态的 Pod，仍会被计入副本总数。
如果某个 Pod 缺失度量值，它将会被搁置，只在最终确定扩缩数量时再考虑。
当使用 CPU 指标来扩缩时，任何还未就绪（还在初始化，或者可能是不健康的）状态的 Pod
**或**最近的指标度量值采集于就绪状态前的 Pod，该 Pod 也会被搁置。
由于技术限制，HorizontalPodAutoscaler 控制器在确定是否保留某些 CPU 指标时无法准确确定 Pod 首次就绪的时间。
相反，如果 Pod 未准备好并在其启动后的一个可配置的短时间窗口内转换为准备好，它会认为 Pod “尚未准备好”。
此值使用 `--horizontal-pod-autoscaler-initial-readiness-delay` 命令行选项配置，默认值为 30 秒。
一旦 Pod 准备就绪，如果它发生在自启动后较长的、可配置的时间内，它就会认为任何向准备就绪的转换都是第一个。
此值由 `--horizontal-pod-autoscaler-cpu-initialization-period` 命令行选项配置，默认值为 5 分钟。
在排除掉被搁置的 Pod 后，扩缩比例就会根据 \\( 当前指标 \over 预期指标 \\)
计算出来。
如果缺失某些度量值，控制平面会更保守地重新计算平均值，在需要缩小时假设这些 Pod 消耗了目标值的 100%，
在需要放大时假设这些 Pod 消耗了 0% 目标值。这可以在一定程度上抑制扩缩的幅度。
此外，如果存在任何尚未就绪的 Pod，工作负载会在不考虑遗漏指标或尚未就绪的 Pod 的情况下进行扩缩，
控制器保守地假设尚未就绪的 Pod 消耗了期望指标的 0%，从而进一步降低了扩缩的幅度。
考虑到尚未准备好的 Pod 和缺失的指标后，控制器会重新计算使用率。
如果新的比率与扩缩方向相反，或者在容差范围内，则控制器不会执行任何扩缩操作。
在其他情况下，新比率用于决定对 Pod 数量的任何更改。
注意，平均利用率的**原始**值是通过 HorizontalPodAutoscaler 状态体现的，
而不考虑尚未准备好的 Pod 或缺少的指标，即使使用新的使用率也是如此。
如果创建 HorizontalPodAutoscaler 时指定了多个指标，
那么会按照每个指标分别计算扩缩副本数，取最大值进行扩缩。
如果任何一个指标无法顺利地计算出扩缩副本数（比如，通过 API 获取指标时出错），
并且可获取的指标建议缩容，那么本次扩缩会被跳过。
这表示，如果一个或多个指标给出的 `desiredReplicas` 值大于当前值，HPA 仍然能实现扩容。
最后，在 HPA 控制器执行扩缩操作之前，会记录扩缩建议信息。
控制器会在操作时间窗口中考虑所有的建议信息，并从中选择得分最高的建议。
你可以使用 `--horizontal-pod-autoscaler-downscale-stabilization` 命令行选项来配置这个值，
默认值为 5 分钟。这个配置可以让系统更为平滑地进行缩容操作，从而消除短时间内指标值快速波动产生的影响。
## Pod 准备就绪和自动伸缩指标 {#pod-readiness-and-autoscaling-metrics}
HorizontalPodAutoscaler（HPA）控制器有两个命令行选项会影响 Pod 启动期间如何收集其 CPU 指标：
1. `--horizontal-pod-autoscaler-cpu-initialization-period`（默认：5 分钟）
此命令行选项所定义的是 Pod 启动后的一个时间窗口，在此期间内其 **CPU 使用率被忽略**，除非：
- Pod 处于 `Ready` 状态**且**
- 指标样本完全是在它处于 `Ready` 状态期间采集的。
此命令行选项有助于**排除初始化 Pod 中的误导性高 CPU 使用率**
（例如，Java 应用程序预热）对 HPA 扩缩决策的影响。
2. `--horizontal-pod-autoscaler-initial-readiness-delay`（默认：30 秒）
这定义了一个短暂的延迟期，在 Pod 启动后，HPA 控制器将当前为 `Unready`
的 Pod 视为仍在初始化中，**即使它们之前曾短暂转变为 `Ready`**。
其设计目的是：
- 避免包含在启动期间快速在 `Ready` 和 `Unready` 之间波动的 Pod。
- 确保在 HPA 认为它们的指标有效之前，初始就绪信号的稳定性。
你可以在集群范围设置这些命令行选项。
### Pod 就绪的关键行为 {#pod-readiness-key-behaviors}
- 如果一个 Pod 是 `Ready` 状态并且保持 `Ready`，即使在延迟期间，
它也可以被视为贡献指标。
- 如果一个 Pod 在 `Ready` 和 `Unready` 之间快速切换，那么它的指标将被忽略，
直到它被认为稳定在 `Ready` 状态。
### Pod 就绪的良好实践 {#pod-readiness-good-practices}
- 配置 `startupProbe`，使其在高 CPU 使用率结束之前不会传递，或
- 使用 `initialDelaySeconds`，确保你的 `readinessProbe` **在 CPU 峰值过后**才报告为 `Ready`。
理想情况下，还应设置 `--horizontal-pod-autoscaler-cpu-initialization-period`，以**覆盖启动持续时间**。
## API 对象 {#api-object}
HorizontalPodAutoscaler 是 Kubernetes `autoscaling` API 组中的一个 API 类别。
当前的稳定版本可以在 `autoscaling/v2` API 版本中找到，其中包括对基于内存和自定义指标执行扩缩的支持。
在使用 `autoscaling/v1` 时，`autoscaling/v2` 中引入的新字段作为注释保留。
创建 HorizontalPodAutoscaler 对象时，需要确保所给的名称是一个合法的
[DNS 子域名](/zh-cn/docs/concepts/overview/working-with-objects/names#dns-subdomain-names)。
有关 API 对象的更多信息，请查阅
[HorizontalPodAutoscaler 对象文档](/docs/reference/generated/kubernetes-api/v1.36/#horizontalpodautoscaler-v2-autoscaling)。
## 工作量规模的稳定性 {#flapping}
在使用 HorizontalPodAutoscaler 管理一组副本的规模时，由于评估的指标的动态特性，
副本的数量可能会经常波动。这有时被称为 **抖动（thrashing）** 或 **波动（flapping）**。
它类似于控制论中的 **滞后（hysteresis）** 概念。
## 滚动升级时扩缩 {#autoscaling-during-rolling-update}
Kubernetes 允许你在 Deployment 上执行滚动更新。在这种情况下，Deployment 为你管理下层的 ReplicaSet。
当你为一个 Deployment 配置自动扩缩时，你要为每个 Deployment 绑定一个 HorizontalPodAutoscaler。
HorizontalPodAutoscaler 管理 Deployment 的 `replicas` 字段。
Deployment Controller 负责设置下层 ReplicaSet 的 `replicas` 字段，
以便确保在上线及后续过程副本个数合适。
如果你对一个副本个数被自动扩缩的 StatefulSet 执行滚动更新，该 StatefulSet
会直接管理它的 Pod 集合（不存在类似 ReplicaSet 这样的中间资源）。
## 对资源指标的支持 {#support-for-resource-metrics}
HPA 的任何目标资源都可以基于其中的 Pod 的资源用量来实现扩缩。
在定义 Pod 规约时，类似 `cpu` 和 `memory` 这类资源请求必须被设定。
这些设定值被用来确定资源利用量并被 HPA 控制器用来对目标资源完成扩缩操作。
要使用基于资源利用率的扩缩，可以像下面这样指定一个指标源：
```yaml
type: Resource
resource:
name: cpu
target:
type: Utilization
averageUtilization: 60
```
基于这一指标设定，HPA 控制器会维持扩缩目标中的 Pod 的平均资源利用率在 60%。
利用率是 Pod 的当前资源用量与其请求值之间的比值。
关于如何计算利用率以及如何计算平均值的细节可参考[算法](#algorithm-details)小节。
说明：
由于所有的容器的资源用量都会被累加起来，Pod 的总体资源用量值可能不会精确体现各个容器的资源用量。
这一现象也会导致一些问题，例如某个容器运行时的资源用量非常高，但因为 Pod
层面的资源用量总值让人在可接受的约束范围内，HPA 不会执行扩大目标对象规模的操作。
### 容器资源指标 {#container-resource-metrics}
特性状态：Kubernetes v1.30 [stable]（默认启用）
HorizontalPodAutoscaler API 也支持容器指标源，这时 HPA 可以跟踪记录一组 Pod
中各个容器的资源用量，进而触发扩缩目标对象的操作。
容器资源指标的支持使得你可以为特定 Pod 中最重要的容器配置规模扩缩阈值。
例如，如果你有一个 Web 应用和一个提供记录日志功能的边车容器，你可以基于 Web
应用的资源用量来执行扩缩，忽略边车容器的存在及其资源用量。
如果你更改扩缩目标对象，令其使用新的、包含一组不同的容器的 Pod 规约，你就需要修改
HPA 的规约才能基于新添加的容器来执行规模扩缩操作。
如果指标源中指定的容器不存在或者仅存在于部分 Pod 中，那么这些 Pod 会被忽略，
HPA 会重新计算资源用量值。参阅[算法](#algorithm-details)小节进一步了解计算细节。
要使用容器资源用量来完成自动扩缩，可以像下面这样定义指标源：
```yaml
type: ContainerResource
containerResource:
name: cpu
container: application
target:
type: Utilization
averageUtilization: 60
```
在上面的例子中，HPA 控制器会对目标对象执行扩缩操作以确保所有 Pod 中
`application` 容器的平均 CPU 用量为 60%。