Kubernetes 垂直 Pod 自动伸缩（VPA）API 完全指南：autoscaling.k8s.io/v1 详解

Kubernetes 垂直 Pod 自动伸缩（VPA）API 完全指南：autoscaling.k8s.io/v1 详解

【免费下载链接】autoscalerAutoscaling components for Kubernetes项目地址: https://gitcode.com/GitHub_Trending/au/autoscaler

导读

本指南以 Kubernetes Autoscaler 仓库中 VerticalPodAutoscaler API 参考文档 为骨架，结合autoscaling.k8s.io/v1的 Go 类型定义源码，系统讲解 VPA 的 API 对象结构、Spec 与 Status 字段语义、更新模式（UpdateMode）、资源策略（ResourcePolicy）、驱逐控制（EvictionRequirement）与启动加速（StartupBoost）等核心机制。读完本文，你将能够精准编写、校验和解读 VPA 清单文件，理解推荐结果（recommendation）各字段的业务含义，并能在生产集群中为不同工作负载挑选合适的更新与资源控制策略。

一、API 概览：包结构与核心对象

VPA 的 API 属于autoscaling.k8s.io/v1组版本。根据 register.go 源码，其组版本定义为autoscaling.k8s.io/v1，包内包含如下对象类型：

• VerticalPodAutoscaler：VPA 配置本身，即用户创建的 CR 对象；
• VerticalPodAutoscalerList：VPA 对象列表；
• VerticalPodAutoscalerCheckpoint与VerticalPodAutoscalerCheckpointList：Recommender 内部状态的检查点对象，用于推荐器重启后的恢复（恢复 CPU/内存使用直方图数据）。

从 types.go 源码 的 kubebuilder 注解可以看出，VPA 对象：

• 短名为vpa（kubectl get vpa可直接使用）；
• 启用了status子资源（+kubebuilder:subresource:status）；
• 提供了若干printcolumn打印列，执行kubectl get vpa时可直接看到Mode（更新模式）、CPU、Mem（当前推荐值）、Provided（推荐是否就绪）、Age、MinReplicas、OOMSeconds等摘要信息。

VerticalPodAutoscaler对象由标准的TypeMeta（kind/apiVersion）、ObjectMeta（metadata）以及spec、status四部分组成：

二、VerticalPodAutoscalerSpec：如何声明“伸缩什么、怎么伸缩”

VerticalPodAutoscalerSpec是 VPA 配置的主体，对应 types.go 中的定义，共包含五个字段：

2.1 targetRef：伸缩的目标控制器

targetRef指向需要被垂直伸缩的控制器（如 Deployment、StatefulSet）。源码注释明确指出：

• VPA 可以指向实现了 scale 子资源的控制器（通过该控制器的 ScaleStatus 获取 Pod 集合），也可以指向部分知名控制器（如 DaemonSet 时从控制器 spec 读取 Pod 集合）；
• 若 VPA 无法使用指定的目标，会在 status 中上报ConfigUnsupported条件；
• 注意 VPA 并不需要完整的 scale 子资源实现——它不会用它修改副本数，只读取能匹配到 Pod 组的标签选择器。

典型写法：

apiVersion: autoscaling.k8s.io/v1 kind: VerticalPodAutoscaler metadata: name: my-app-vpa spec: targetRef: apiVersion: "apps/v1" kind: Deployment name: my-app

2.2 updatePolicy：更新策略

updatePolicy描述“改动如何被应用到 Pod 上”。若未指定，其中所有字段取默认值。详见下文第三节。

2.3 resourcePolicy：推荐计算约束

resourcePolicy控制自动伸缩器如何计算推荐资源，可对单个容器设置约束。特别强调：如果某个容器需要被排除在 VPA 推荐之外，必须显式将containerPolicies中该容器的mode设为"Off"；若未指定该字段，则 VPA 为 Pod 内所有容器计算推荐，不附加额外约束。详见第四节。

2.4 recommenders：选择推荐器

recommenders指定负责为该对象生成推荐的推荐器。列表必须为空（使用默认推荐器）或恰好包含一个元素。配合--recommender-name与--target-cpu-percentile参数可以部署多个推荐器（例如 90 与 95 两个百分位），再通过本字段为不同工作负载指定不同的推荐器。源码中该结构仅含一个name字段，对应 VerticalPodAutoscalerRecommenderSelector。

2.5 startupBoost：Pod 级启动加速

startupBoost指定 Pod 级别的启动加速策略，可被容器级策略覆盖，详见第六节。

三、PodUpdatePolicy 与 UpdateMode：五种更新模式的完整语义

PodUpdatePolicy定义“何时”把推荐应用到 Pod，对应 types.go 定义，字段如下：

UpdateMode的枚举值定义在 types.go，结合 helpers.go 的 GetUpdateModesList（该函数明确跳过已弃用的Auto）可整理如下：

3.1 就地更新模式的落地要点

从仓库 features.md 的说明可以补充以下细节：

• InPlaceOrRecreate自 VPA v1.4.0（alpha）→ v1.5.0（beta）→ v1.6.0（ga）逐步演进，v1.7.0 起移除特性门控；更新时机包括“容器请求超出推荐边界”“快速 OOM”“长运行 Pod（>12h）且推荐变化超过 10%”等；
• 回退到重建的场景包括：就地更新不可行（节点资源不足等）、更新被延迟超过 5 分钟、更新进行中超过 1 小时、更新会改变 Pod 的 QoS 等级、在PreferNoRestart策略下需要下调内存 limit 等；
• 可通过--in-place-skip-disruption-budget标志（默认 false）跳过“无容器重启的”就地更新的干扰预算检查；
• Updater 暴露了vpa_updater_in_place_updatable_pods_total、vpa_updater_in_place_updated_pods_total、vpa_updater_failed_in_place_update_attempts_total等指标用于观测。

3.2 EvictionRequirement：按伸缩方向与资源控制驱逐

EvictionRequirement定义“驱逐一个 Pod 必须成立的条件”，出现在 PodUpdatePolicy 中，包含两个字段：

• resources（ResourceName 数组）：条件作用的资源列表；若给出多个资源，只要至少一个资源满足changeRequirement，该条件即成立；
• changeRequirement（EvictionChangeRequirement）：枚举TargetHigherThanRequests（新目标高于当前请求，即扩容）或TargetLowerThanRequests（新目标低于当前请求，即缩容）。

配置示例——仅允许 CPU 或内存被“扩容”时才驱逐，两者都缩容时禁止驱逐：

updatePolicy: evictionRequirements: - resources: ["cpu", "memory"] changeRequirement: TargetHigherThanRequests

注意：这并不完全阻止缩容——Pod 可能因其他原因被重建，从而应用新的推荐。可参阅 enhancements/4831-control-eviction-behavior 了解更完整的背景与用法。

四、PodResourcePolicy 与 ContainerResourcePolicy：推荐计算的“约束层”

4.1 PodResourcePolicy

PodResourcePolicy 仅有一个字段containerPolicies（ContainerResourcePolicy 数组）。源码注释强调两条规则：

• 每个具名容器至多有一个策略条目；
• 可选一个通配条目containerName: '*'，作为没有独立策略的容器的默认策略（源码常量DefaultContainerResourcePolicy = "*"定义于 types.go）。

4.2 ContainerResourcePolicy 全字段

该结构定义于 types.go，完整字段如下：

4.3 与 LimitRange 的交互行为

根据 features.md 的“Limits control”一节，设置 limit 时 VPA 会遵循资源策略并维持各容器模板中的 limit/request 比例；当 LimitRange 与 VPA 资源策略冲突时，VPA 遵循自身策略（可能将值设在 LimitRange 之外）。具体到 examples.md 的案例：

• 保持 limit 与 request 成比例：模板 request=500m CPU/1GB RAM、limit=2GB RAM，VPA 推荐 1000m/2GB，应用时内存 limit 会被设为 4GB（维持 2:1 比例）；
• 被 LimitRange 封顶：若 LimitRange 将单容器内存 limit 上限设为 3GB，则 VPA 会把内存 limit 设为 3GB，并把 request 设为 1.5GB 以维持 2:1 比例；
• 资源策略覆盖 LimitRange：当容器资源策略要求 request 至少 2GB 时，VPA 将 request 设为 2GB（遵循策略）、limit 设为 4GB（维持模板比例），从而突破 LimitRange 的 3GB 上限。

4.4 OOM 后内存提升机制

examples.md 给出了 OOMKill 后的推荐公式：

recommendation = max(memory-usage-in-oomkill-event + oom-min-bump-up-bytes, memory-usage-in-oomkill-event * oom-bump-up-ratio)

• oom-bump-up-ratio默认1.2（OOM 后内存增加 20%）；
• oom-min-bump-up-bytes默认100 * 1024 * 1024（100MiB）。

可以通过 Recommender 的启动参数覆盖全局默认，也可以在containerPolicies中以oomBumpUpRatio、oomMinBumpUp按容器定制：

resourcePolicy: containerPolicies: - containerName: app oomBumpUpRatio: 2.0 oomMinBumpUp: 500Mi

推荐器 Deployment 中对应的参数写法为：

containers: - name: recommender args: - --oom-bump-up-ratio=2.0 - --oom-min-bump-up-bytes=524288000

五、VerticalPodAutoscalerStatus 与推荐结果解读

VerticalPodAutoscalerStatus描述自动伸缩器的运行时状态，定义于 types.go：

5.1 RecommendedPodResources 与 RecommendedContainerResources

RecommendedPodResources含containerRecommendations数组，每个元素为RecommendedContainerResources（对应 types.go）：

源码注释明确：对ContainerScalingMode为Off的容器不产生推荐。

5.2 条件类型（Conditions）

VerticalPodAutoscalerCondition的标准字段包括type、status（True/False/Unknown）、lastTransitionTime、reason、message、observedGeneration（Minimum: 0）。已定义的条件类型常量见 types.go：

六、StartupBoost：CPU 启动加速策略

StartupBoost定义在 types.go，既可作为VerticalPodAutoscalerSpec.startupBoost（Pod 级），也可作为ContainerResourcePolicy.startupBoost（容器级，覆盖 Pod 级）。其下cpu字段为GenericStartupBoost，结构如下：

GenericStartupBoost带有两条 CEL 校验规则（见 types.go 注解）：type == "Factor"时必须存在factor且禁止存在quantity，反之亦然；未识别到的 type 值不会施加任何加速。StartupBoostType枚举：Factor表示对资源施加倍数，Quantity表示施加固定量（见 types.go）。

Pod 级配置示例（所有容器在就绪后 10 秒内 CPU 放大 3 倍）：

apiVersion: "autoscaling.k8s.io/v1" kind: VerticalPodAutoscaler metadata: name: example-vpa spec: targetRef: apiVersion: "apps/v1" kind: Deployment name: example updatePolicy: updateMode: "Recreate" startupBoost: cpu: type: "Factor" factor: 3 durationSeconds: 10

工作机制（详见 features.md 的“CPU Startup Boost”一节）：

1. Pod 被创建时，VPA Admission Controller 施加 CPU 加速；
2. VPA Updater 监控 Pod，一旦 Pod 变为Ready且超过durationSeconds，便就地（in-place）把 CPU 缩回正常水平；
3. 缩回的“正常水平”是该容器的 VPA 推荐值（若该容器启用了 VPA）或 Pod 模板中的原始 CPU 值。

前置条件：Kubernetes 1.33+ 且开启InPlacePodVerticalScaling特性门控；VPA v1.7.0+ 且开启CPUStartupBoost特性门控（--feature-gates=CPUStartupBoost=true）。

七、Checkpoint 对象：推荐器的“记忆恢复”机制

VerticalPodAutoscalerCheckpoint是 VPA 内部状态的检查点，用于 Recommender 重启后恢复，避免丢失历史观测数据。其 spec 只有vpaObjectName与containerName两个字段（types.go），status 则保存了完整的状态数据：

HistogramCheckpoint用于重建直方图，包含referenceTimestamp（样本参考时间）、bucketWeights（桶索引到桶权重的映射，类型为 object 且XPreserveUnknownFields）、totalWeight（权重分母）三个字段（types.go）。

八、实操：从清单到验证

8.1 一个带完整策略的 VPA 示例

结合 quickstart.md 与 API 语义，一个可直接落地的示例：

kubectl apply -f - <<EOF apiVersion: "autoscaling.k8s.io/v1" kind: VerticalPodAutoscaler metadata: name: hamster-vpa spec: targetRef: apiVersion: "apps/v1" kind: Deployment name: hamster updatePolicy: updateMode: "Recreate" minReplicas: 2 evictAfterOOMSeconds: 300 resourcePolicy: containerPolicies: - containerName: '*' minAllowed: cpu: 100m memory: 50Mi maxAllowed: cpu: 1 memory: 500Mi controlledResources: ["cpu", "memory"] controlledValues: RequestsAndLimits EOF

上述配置的含义：为hamsterDeployment 的所有容器计算 CPU 与内存推荐；推荐下限为 100m/50Mi、上限为 1/500Mi；request 与 limit 同步伸缩；Updater 仅在存活副本不少于 2 个且（对于近期 OOM 的 Pod）OOM 事件已过去 300 秒后才考虑驱逐。

8.2 观察与验证

# 查看 VPA 对象摘要（Mode / CPU / Mem / Provided / MinReplicas / OOMSeconds 等打印列） kubectl get vpa # 查看完整推荐与条件状态 kubectl describe vpa

describe输出中的.status.recommendation.containerRecommendations[].target即为当前推荐值；conditions中的RecommendationProvided、NoPodsMatched、ConfigUnsupported等条件可以帮助快速定位问题（排查流程也可参考 quickstart.md 的 Troubleshooting 一节，例如确认kube-system下 recommender、updater、admission-controller 三个 Pod 均处于 Running、检查组件日志中的^E[0-9]\{4\}错误行、确认verticalpodautoscalersCRD 已创建）。

8.3 快速上手小贴士

• 集群中安装 VPA 后，kubectl apply一个指向 Deployment 的 VPA 清单即可开始观测；推荐通常在几分钟内出现（quickstart 的示例约 5 分钟）；
• 只想要“建议、不动手”，用updateMode: Off做干跑；
• 对无法容忍重启的工作负载，评估 Kubernetes 1.33+ 的InPlacePodVerticalScaling门控后使用InPlaceOrRecreate或InPlace；
• 全局兜底：为预防推荐值超出集群最大节点可分配量导致 Pod 无法调度（Pending），可以给 vpa-recommender 配置--container-recommendation-max-allowed-cpu与--container-recommendation-max-allowed-memory两个容器级全局上限。计算建议值可参考最大节点 allocatable - DaemonSet Pod 资源请求 - 安全裕量，且当 VPA 自身已定义maxAllowed时以 VPA 为准（详见 examples.md）。

九、进一步阅读

• API 参考原文：vertical-pod-autoscaler/docs/api.md
• API 类型 Go 源码：pkg/apis/autoscaling.k8s.io/v1/types.go
• CRD 定义（含各字段 description 与校验）：deploy/vpa-v1-crd-gen.yaml
• 完整功能说明（就地更新、内存人性化显示、CPU/内存取整、启动加速）：vertical-pod-autoscaler/docs/features.md
• 实战示例（limit/request 比例、LimitRange 交互、多推荐器、OOM 提升等）：vertical-pod-autoscaler/docs/examples.md
• 快速上手与故障排查：vertical-pod-autoscaler/docs/quickstart.md

【免费下载链接】autoscalerAutoscaling components for Kubernetes项目地址: https://gitcode.com/GitHub_Trending/au/autoscaler