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

HorizontalPodAutoscaler（HPA）的API版本经历了从v1到v2beta2再到稳定版v2的演进过程。每个版本在表达能力、支持的度量指标类型以及资源抽象层级上都有显著差异。理解这些版本的区别，是正确配置自定义metric触发器的前提。

3.1 版本演进路线图

Kubernetes社区在HPA的API设计上遵循了“先简单、后丰富”的策略。v1仅支持CPU使用率，v2beta2引入了自定义metric和外部metric，v2则在此基础上将beta2的字段结构正式稳定下来。

3.2 核心区别对比

三个版本在API组、度量指标类型、数据结构、资源字段等方面存在本质差异。下表从实际配置角度进行横向对比：

3.3 数据结构差异详解

三个版本在YAML/JSON结构上的差异，直接决定了如何编写自定义metric触发器。

3.3.1 autoscaling/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

v1的局限性非常明显：只能设置一个CPU目标值，无法表达自定义metric、内存、QPS等指标。对于基于自定义metric的弹性伸缩场景，v1完全不适用。

3.3.2 autoscaling/v2beta2 结构（多指标 + 自定义metric）

apiVersion: autoscaling/v2beta2
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: Pods
    pods:
      metric:
        name: requests_per_second
      target:
        type: AverageValue
        averageValue: 1000
  behavior:
    scaleDown:
      stabilizationWindowSeconds: 300

v2beta2引入了 metrics[] 数组，每个元素通过 type 字段区分指标来源：

• Resource：内置资源指标（CPU、内存）
• Pods：Pod级别的自定义metric（每个Pod的指标值，取平均）
• Object：集群对象级别的自定义metric（如Ingress的QPS）
• External：集群外部的metric（如云服务商指标）

3.3.3 autoscaling/v2 结构（GA稳定版）

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: Pods
    pods:
      metric:
        name: requests_per_second
      target:
        type: AverageValue
        averageValue: 1000
  behavior:
    scaleDown:
      stabilizationWindowSeconds: 300

v2与v2beta2的YAML结构完全一致，唯一的区别是API版本号从 v2beta2 改为 v2。这意味着：

• 所有v2beta2的YAML文件只需修改 apiVersion 即可迁移到v2
• v2beta2的字段语义、行为逻辑在v2中保持不变
• v2是GA版本，不会再有破坏性变更

3.4 选择建议

根据不同的集群版本和需求场景，选择策略如下：

3.5 版本迁移注意事项

从v1迁移到v2时，需要注意以下关键变化：

• 字段结构变化：v1的 targetCPUUtilizationPercentage 在v2中变为 metrics[].resource.target.averageUtilization
• 多指标策略：v2支持多个metric，HPA会计算每个metric的期望副本数，最终取最大值作为伸缩结果
• behavior字段：v2的 behavior 字段提供了扩缩容的精细化控制（稳定窗口、速率限制等），v1没有此功能
• API版本转换：Kubernetes API Server会自动在v1和v2之间进行转换，但v1写入的HPA在读取为v2时，会丢失behavior等高级配置

3.6 版本选择决策流程图

3.7 小结

对于本课程的核心主题——基于自定义metric的弹性伸缩触发器开发，autoscaling/v2 是唯一正确的选择。它提供了：

• 完整的自定义metric类型支持（Pods、Object、External）
• GA级别的稳定性保证
• behavior字段用于精细控制扩缩容行为
• 与v2beta2完全兼容的字段结构，迁移成本为零