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

Kubernetes 垂直 Pod 自动伸缩VPAAPI 完全指南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包内包含如下对象类型VerticalPodAutoscalerVPA 配置本身即用户创建的 CR 对象VerticalPodAutoscalerListVPA 对象列表VerticalPodAutoscalerCheckpoint与VerticalPodAutoscalerCheckpointListRecommender 内部状态的检查点对象用于推荐器重启后的恢复恢复 CPU/内存使用直方图数据。从 types.go 源码 的 kubebuilder 注解可以看出VPA 对象短名为vpakubectl get vpa可直接使用启用了status子资源kubebuilder:subresource:status提供了若干printcolumn打印列执行kubectl get vpa时可直接看到Mode更新模式、CPU、Mem当前推荐值、Provided推荐是否就绪、Age、MinReplicas、OOMSeconds等摘要信息。VerticalPodAutoscaler对象由标准的TypeMetakind/apiVersion、ObjectMetametadata以及spec、status四部分组成字段类型说明specVerticalPodAutoscalerSpec自动伸缩行为的规范必填statusVerticalPodAutoscalerStatus自动伸缩器的当前运行状态可选二、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-app2.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 startupBoostPod 级启动加速startupBoost指定 Pod 级别的启动加速策略可被容器级策略覆盖详见第六节。三、PodUpdatePolicy 与 UpdateMode五种更新模式的完整语义PodUpdatePolicy定义“何时”把推荐应用到 Pod对应 types.go 定义字段如下字段类型默认值校验规则说明updateModeUpdateModeRecreateEnum: [Off Initial Recreate InPlaceOrRecreate InPlace Auto]控制何时应用变更minReplicasinteger无仅允许正值存活副本的最小数量满足后才允许 Updater 驱逐 Pod还需通过 PDB 等其他检查覆盖全局--min-replicas标志evictionRequirementsEvictionRequirement array无—驱逐前置条件列表所有条件都必须满足才允许驱逐evictAfterOOMSecondsinteger无Minimum: 1发生 OOM 后等待的秒数从启动至今 OOM 时间小于该值的 Pod 将被驱逐UpdateMode的枚举值定义在 types.go结合 helpers.go 的 GetUpdateModesList该函数明确跳过已弃用的Auto可整理如下值含义适用场景 / 备注Off从不改变 Pod 资源但 Recommender 仍在 VPA 对象中写入推荐适合“干跑”dry run观察推荐值Initial仅在 Pod 创建时分配资源生命周期内不再改动适合无法接受重启的负载Recreate创建时分配资源之后可通过删除并重建 Pod 来更新默认模式Auto等价于Recreate已弃用将在未来 API 版本中移除应改用显式模式InPlaceOrRecreate优先尝试就地in-place更新失败则回退到 Recreate需要集群开启InPlacePodVerticalScaling特性门控InPlace只尝试就地更新、绝不驱逐 Pod失败后依赖 Kubelet 自动重试需要 VPA 级InPlace特性门控admission 与 updater Pod 上以及集群级InPlacePodVerticalScaling特性门控3.1 就地更新模式的落地要点从仓库 features.md 的说明可以补充以下细节InPlaceOrRecreate自 VPA v1.4.0alpha→ v1.5.0beta→ v1.6.0ga逐步演进v1.7.0 起移除特性门控更新时机包括“容器请求超出推荐边界”“快速 OOM”“长运行 Pod12h且推荐变化超过 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 中包含两个字段resourcesResourceName 数组条件作用的资源列表若给出多个资源只要至少一个资源满足changeRequirement该条件即成立changeRequirementEvictionChangeRequirement枚举TargetHigherThanRequests新目标高于当前请求即扩容或TargetLowerThanRequests新目标低于当前请求即缩容。配置示例——仅允许 CPU 或内存被“扩容”时才驱逐两者都缩容时禁止驱逐updatePolicy: evictionRequirements: - resources: [cpu, memory] changeRequirement: TargetHigherThanRequests注意这并不完全阻止缩容——Pod 可能因其他原因被重建从而应用新的推荐。可参阅 enhancements/4831-control-eviction-behavior 了解更完整的背景与用法。四、PodResourcePolicy 与 ContainerResourcePolicy推荐计算的“约束层”4.1 PodResourcePolicyPodResourcePolicy 仅有一个字段containerPoliciesContainerResourcePolicy 数组。源码注释强调两条规则每个具名容器至多有一个策略条目可选一个通配条目containerName: *作为没有独立策略的容器的默认策略源码常量DefaultContainerResourcePolicy *定义于 types.go。4.2 ContainerResourcePolicy 全字段该结构定义于 types.go完整字段如下字段类型默认值校验说明containerNamestring——容器名传*表示默认容器策略modeContainerScalingModeAutoEnum: [Auto Off]该容器是否启用自动伸缩minAllowedResourceList无最小值Optional推荐给容器的最小资源量maxAllowedResourceList无最大值Optional推荐给容器的最大资源量controlledResourcesResourceName 数组[cpu, memory]—计算并可能应用的推荐资源类型controlledValuesContainerControlledValuesRequestsAndLimitsEnum: [RequestsAndLimits RequestsOnly]控制 request 还是 requestlimitoomBumpUpRatioQuantity见说明Optional检测到 OOM 时内存的提升比例oomMinBumpUpQuantity见说明Optional检测到 OOM 时内存的最小提升量memoryAggregationIntervalSecondsinteger见说明Minimum: 1单个峰值内存统计区间的长度秒memoryAggregationIntervalCountinteger见说明Minimum: 1构成内存聚合窗口的区间个数窗口总长 两者相乘startupBoostStartupBoost无Optional容器级启动加速策略覆盖 Pod 级策略且优先于本结构其余字段ContainerName与ControlledValues除外4.3 与 LimitRange 的交互行为根据 features.md 的“Limits control”一节设置 limit 时 VPA 会遵循资源策略并维持各容器模板中的 limit/request 比例当 LimitRange 与 VPA 资源策略冲突时VPA 遵循自身策略可能将值设在 LimitRange 之外。具体到 examples.md 的案例保持 limit 与 request 成比例模板 request500m CPU/1GB RAM、limit2GB RAMVPA 推荐 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.2OOM 后内存增加 20%oom-min-bump-up-bytes默认100 * 1024 * 1024100MiB。可以通过 Recommender 的启动参数覆盖全局默认也可以在containerPolicies中以oomBumpUpRatio、oomMinBumpUp按容器定制resourcePolicy: containerPolicies: - containerName: app oomBumpUpRatio: 2.0 oomMinBumpUp: 500Mi推荐器 Deployment 中对应的参数写法为containers: - name: recommender args: - --oom-bump-up-ratio2.0 - --oom-min-bump-up-bytes524288000五、VerticalPodAutoscalerStatus 与推荐结果解读VerticalPodAutoscalerStatus描述自动伸缩器的运行时状态定义于 types.go字段类型说明recommendationRecommendedPodResources最近一次计算出的推荐资源可选conditionsVerticalPodAutoscalerCondition 数组该自动伸缩器缩放目标所需的条件集合及其满足状态patchMergeKeytypeobservedGenerationinteger自动伸缩器观察到的最新 generationMinimum: 05.1 RecommendedPodResources 与 RecommendedContainerResourcesRecommendedPodResources含containerRecommendations数组每个元素为RecommendedContainerResources对应 types.go字段类型说明containerNamestring容器名targetResourceList推荐资源量遵循 ContainerResourcePolicylowerBoundResourceList推荐下限低于该值运行很可能对性能/可用性产生显著影响不保证够用upperBoundResourceList推荐上限超出该值的资源大概率被浪费可能大于应用实际能消费的上限uncappedTargetResourceList仅基于实际用量计算、未受资源策略约束的原始目标仅作状态展示不影响实际资源分配源码注释明确对ContainerScalingMode为Off的容器不产生推荐。5.2 条件类型ConditionsVerticalPodAutoscalerCondition的标准字段包括type、statusTrue/False/Unknown、lastTransitionTime、reason、message、observedGenerationMinimum: 0。已定义的条件类型常量见 types.go条件含义RecommendationProvidedRecommender 是否成功计算出了推荐LowConfidence对部分容器的推荐置信度较低NoPodsMatchedVPA 的标签选择器未匹配到任何 PodFetchingHistoryRecommender 正在加载历史样本ConfigDeprecated该 VPA 配置已弃用将停止支持ConfigUnsupported配置不被支持不会提供推荐例如 targetRef 无法使用六、StartupBoostCPU 启动加速策略StartupBoost定义在 types.go既可作为VerticalPodAutoscalerSpec.startupBoostPod 级也可作为ContainerResourcePolicy.startupBoost容器级覆盖 Pod 级。其下cpu字段为GenericStartupBoost结构如下字段类型必填说明typeStartupBoostType是联合判别字段枚举Factor/Quantityfactorinteger (int32)Factor时必填对资源请求施加的倍数quantityQuantityQuantity时必填加速阶段使用的绝对资源量同时用作 request 与 limitdurationSecondsinteger (int32)否Pod 变为 Ready 后保持加速的时长默认 0GenericStartupBoost带有两条 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”一节Pod 被创建时VPA Admission Controller 施加 CPU 加速VPA Updater 监控 Pod一旦 Pod 变为Ready且超过durationSeconds便就地in-place把 CPU 缩回正常水平缩回的“正常水平”是该容器的 VPA 推荐值若该容器启用了 VPA或 Pod 模板中的原始 CPU 值。前置条件Kubernetes 1.33 且开启InPlacePodVerticalScaling特性门控VPA v1.7.0 且开启CPUStartupBoost特性门控--feature-gatesCPUStartupBoosttrue。七、Checkpoint 对象推荐器的“记忆恢复”机制VerticalPodAutoscalerCheckpoint是 VPA 内部状态的检查点用于 Recommender 重启后恢复避免丢失历史观测数据。其 spec 只有vpaObjectName与containerName两个字段types.gostatus 则保存了完整的状态数据字段类型说明lastUpdateTimeTime状态最近一次刷新时间versionstring存储数据的格式版本cpuHistogramHistogramCheckpointCPU 消耗直方图检查点memoryHistogramHistogramCheckpoint内存消耗直方图检查点firstSampleStart/lastSampleStartTime直方图中第一个/最后一个样本的时间戳totalSamplesCountinteger直方图中的样本总数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/500Mirequest 与 limit 同步伸缩Updater 仅在存活副本不少于 2 个且对于近期 OOM 的 PodOOM 事件已过去 300 秒后才考虑驱逐。8.2 观察与验证# 查看 VPA 对象摘要Mode / CPU / Mem / Provided / MinReplicas / OOMSeconds 等打印列 kubectl get vpa # 查看完整推荐与条件状态 kubectl describe vpadescribe输出中的.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.mdAPI 类型 Go 源码pkg/apis/autoscaling.k8s.io/v1/types.goCRD 定义含各字段 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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考