3. HPA API 版本演进：autoscaling/v1、v2beta2、v2 的区别与选择

HorizontalPodAutoscaler（HPA）的 API 版本经历了从 autoscaling/v1 到 v2beta2，再到稳定的 autoscaling/v2 的演进过程。每个版本在功能维度、字段结构和弹性策略上都有显著差异。理解这些差异，是进行参数移植适配的前提。

3.1 版本演进路线与核心差异

下表从功能覆盖、指标类型、行为控制三个维度对比三个主要 API 版本：

3.2 API 字段详解：metrics、behavior、scaleTargetRef

以 autoscaling/v2 为例，HPA 的核心字段结构如下。理解这三个字段是参数移植的基础。

apiVersion: autoscaling/v2
kind: HorizontalPodAutoscaler
metadata:
  name: sample-hpa
spec:
  scaleTargetRef:        # 目标工作负载引用
    apiVersion: apps/v1
    kind: Deployment
    name: web-server
  minReplicas: 2
  maxReplicas: 10
  metrics:               # 弹性指标数组
  - type: Resource
    resource:
      name: cpu
      target:
        type: Utilization
        averageUtilization: 70
  - type: Pods
    pods:
      metric:
        name: requests_per_second
      target:
        type: AverageValue
        averageValue: 1000m
  behavior:              # 弹性行为策略
    scaleDown:
      stabilizationWindowSeconds: 300
      policies:
      - type: Percent
        value: 10
        periodSeconds: 60
    scaleUp:
      stabilizationWindowSeconds: 0
      policies:
      - type: Pods
        value: 4
        periodSeconds: 60
      - type: Percent
        value: 100
        periodSeconds: 60
      selectPolicy: Max

3.2.1 scaleTargetRef —— 弹性目标绑定

scaleTargetRef 指定 HPA 要控制哪个工作负载的副本数。它必须指向支持 /scale 子资源的对象，如 Deployment、StatefulSet、ReplicaSet。

• apiVersion：目标资源的 API 版本，通常为 apps/v1。
• kind：资源类型，常见为 Deployment 或 StatefulSet。
• name：目标资源的名称，必须与集群中实际资源名称一致。

3.2.2 metrics —— 多维弹性指标

metrics 是一个数组，允许同时配置多个指标。HPA 控制器会计算每个指标的建议副本数，并取最大值作为最终目标副本数。v2 支持四种指标类型：

metrics:
- type: Resource
  resource:
    name: cpu
    target:
      type: Utilization
      averageUtilization: 80

3.2.3 behavior —— 弹性行为策略

behavior 字段是 v2beta2 引入、v2 稳定的核心增强。它允许精细控制扩缩容的速率、窗口和策略选择，避免弹性抖动。

behavior 包含两个子策略组：

• scaleDown：缩容策略，控制副本减少的行为。
• scaleUp：扩容策略，控制副本增加的行为。

每个策略组包含以下关键字段：

3.3 版本演进与参数映射关系（SVG 架构图）

下图展示了从 v1 到 v2 的字段演进路径，以及核心参数的映射关系：

3.4 版本选择决策流程

在实际项目中，选择哪个 API 版本取决于集群版本和功能需求。以下决策流程可帮助快速判断：

1. 检查集群版本：kubectl version --short 查看 Server Version。
2. 若 ≥ v1.23：直接使用 autoscaling/v2，获得完整指标支持和稳定的 behavior 策略。
3. 若 v1.12 – v1.22：使用 autoscaling/v2beta2，但需注意未来升级时迁移到 v2。
4. 若 < v1.12：只能使用 autoscaling/v1，仅支持 CPU 指标，建议优先升级集群。
5. 功能需求检查：如果需要自定义指标、外部指标或 behavior 策略，必须使用 v2beta2 或 v2。