4. HPA API 版本演进：autoscaling/v1 vs v2 vs v2beta2

Kubernetes HPA 的 API 版本经历了从 autoscaling/v1 到 v2beta2，再到稳定的 autoscaling/v2 的演进过程。每个版本在支持的指标类型、扩缩容策略、行为控制能力上都有显著差异。理解这些差异是进行 HPA 调优的前提，也是从旧集群迁移到新集群的必修课。

4.1 版本演进路线图

HPA API 的演进本质上是 Kubernetes 对弹性伸缩能力从“单一 CPU 指标”到“多维度、自定义、行为可编程”的扩展过程。下图展示了三个核心版本的能力层级关系：

4.2 核心特性对比表

下表从指标类型、聚合方式、行为控制、稳定性状态四个维度，对三个主要版本进行横向对比：

特性维度	autoscaling/v1	autoscaling/v2beta2	autoscaling/v2
引入版本	K8s 1.0	K8s 1.12	K8s 1.23（稳定）
指标类型	仅 CPU 利用率	CPU / 内存 / 自定义 / 外部	同 v2beta2
指标聚合方式	AverageUtilization（固定）	AverageUtilization / AverageValue / Value	同 v2beta2
多指标支持	不支持	支持（取最大值）	支持（取最大值）
扩缩容行为控制	无	支持（behavior 字段）	支持（behavior 字段，稳定）
稳定状态	GA（稳定）	Beta	GA（稳定）
推荐生产使用	不推荐（能力不足）	可接受（但建议迁移至 v2）	强烈推荐

4.3 关键差异详解

4.3.1 指标类型与聚合方式

v1 的局限： 只能定义 targetCPUUtilizationPercentage，且聚合方式固定为 Pod 平均利用率。无法感知内存压力、无法接入 Prometheus 等自定义指标。

v2/v2beta2 的扩展： 引入 metrics 数组，每个指标可以指定三种聚合方式：

• AverageUtilization：Pod 平均利用率百分比（适用于 CPU / 内存）。
• AverageValue：Pod 平均值（如 QPS、请求延迟）。
• Value：集群级值（如全局队列长度），不按 Pod 平均。

4.3.2 扩缩容行为控制（behavior 字段）

这是 v2beta2 引入、v2 稳定的核心调优能力。v1 完全不具备此能力。behavior 字段允许分别控制扩容和缩容的速率与策略：

behavior:
  scaleUp:
    stabilizationWindowSeconds: 60      # 扩容稳定窗口（默认 0）
    policies:
    - type: Pods
      value: 4                          # 每分钟最多扩容 4 个 Pod
      periodSeconds: 60
    selectPolicy: Max                   # 取所有策略中的最大值
  scaleDown:
    stabilizationWindowSeconds: 300     # 缩容稳定窗口（默认 300 秒）
    policies:
    - type: Percent
      value: 10                         # 每分钟最多缩容 10% 的 Pod
      periodSeconds: 60
    selectPolicy: Min                   # 取所有策略中的最小值

4.4 迁移策略与步骤

从 v1 迁移到 v2（或从 v2beta2 迁移到 v2）需要遵循以下步骤，确保业务不中断：

1. 确认集群版本：K8s 1.23+ 才支持稳定的 v2 API。低于此版本请先升级集群。
2. 导出当前 HPA 配置：使用 kubectl get hpa <name> -o yaml 获取当前配置。
3. 转换 API 版本：将 apiVersion 从 autoscaling/v1 改为 autoscaling/v2，并重构 metrics 结构。
4. 添加行为控制（可选）：根据业务需求添加 behavior 字段，避免缩容过快或扩容过慢。
5. 灰度验证：先在非关键命名空间或低流量时段应用新 HPA，观察扩缩容行为是否符合预期。
6. 逐步替换：确认无误后，批量替换所有 v1 HPA 为 v2。

4.5 版本迁移对照示例

以下展示同一个 HPA 在 v1 和 v2 下的 YAML 差异：

v1 写法（仅 CPU）：

apiVersion: autoscaling/v1
kind: HorizontalPodAutoscaler
metadata:
  name: web-app-hpa
spec:
  scaleTargetRef:
    apiVersion: apps/v1
    kind: Deployment
    name: web-app
  minReplicas: 2
  maxReplicas: 10
  targetCPUUtilizationPercentage: 80

v2 写法（CPU + 内存 + 行为控制）：

apiVersion: autoscaling/v2
kind: HorizontalPodAutoscaler
metadata:
  name: web-app-hpa
spec:
  scaleTargetRef:
    apiVersion: apps/v1
    kind: Deployment
    name: web-app
  minReplicas: 2
  maxReplicas: 10
  metrics:
  - type: Resource
    resource:
      name: cpu
      target:
        type: Utilization
        averageUtilization: 80
  - type: Resource
    resource:
      name: memory
      target:
        type: AverageValue
        averageValue: 500Mi
  behavior:
    scaleDown:
      stabilizationWindowSeconds: 300
      policies:
      - type: Percent
        value: 10
        periodSeconds: 60
    scaleUp:
      stabilizationWindowSeconds: 0
      policies:
      - type: Pods
        value: 5
        periodSeconds: 60

4.6 版本选择建议

场景	推荐 API 版本	理由
新集群（K8s 1.23+）	autoscaling/v2	稳定、功能完整、社区推荐
仅需 CPU 扩缩容的遗留系统	autoscaling/v2（迁移）	v1 已过时，迁移成本低，未来兼容性好
使用自定义指标（Prometheus）	autoscaling/v2	v1 不支持自定义指标
需要精细控制扩缩容速率	autoscaling/v2	behavior 字段仅在 v2/v2beta2 中可用
K8s 1.22 及以下集群	autoscaling/v2beta2	v2 稳定版不可用，v2beta2 是次优选择