3. HPA API 版本演进：autoscaling/v1、autoscaling/v2beta2、autoscaling/v2 特性对比与迁移指南

Kubernetes 的 HorizontalPodAutoscaler（HPA）API 经历了从 v1 到 v2beta2，再到稳定版 v2 的演进。每个版本在支持的指标类型、数据结构、以及扩展能力上都有显著差异。理解这些差异是进行弹性伸缩运营任务编排与参数配置的基础。

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

HPA 的 API 演进主要围绕“指标扩展性”展开。v1 仅支持 CPU 利用率，v2beta2 引入了自定义指标和外部指标，而 v2 则对 v2beta2 的字段进行了标准化和清理，移除了 beta 阶段的冗余字段。

3.2 API 版本特性对比详解

3.2.1 autoscaling/v1：最小化功能集

v1 版本的设计目标是为早期用户提供最基本的 CPU 驱动弹性伸缩能力。其 YAML 结构非常简洁，但功能受限。

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: 75

3.2.2 autoscaling/v2beta2：指标扩展的里程碑

v2beta2 引入了 metrics 数组和 behavior 字段，使得 HPA 可以同时监听多个指标，并支持精细化的扩缩容策略（如禁止缩容、稳定窗口等）。

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: 75
  - type: Pods
    pods:
      metric:
        name: requests_per_second
      target:
        type: AverageValue
        averageValue: 1000
  behavior:
    scaleDown:
      stabilizationWindowSeconds: 300
      policies:
      - type: Percent
        value: 10
        periodSeconds: 60

3.2.3 autoscaling/v2：标准化与稳定性

v2 版本在 v2beta2 的基础上，将 metric 字段下的 target 结构进行了扁平化处理，移除了 beta 阶段的一些冗余包装，使得 API 更加清晰。v2 是当前推荐的稳定版本。

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: 75
  - type: Pods
    pods:
      metric:
        name: requests_per_second
      target:
        type: AverageValue
        averageValue: 1000
  behavior:
    scaleDown:
      stabilizationWindowSeconds: 300
      policies:
      - type: Percent
        value: 10
        periodSeconds: 60

3.3 API 版本迁移指南

从 v1 或 v2beta2 迁移到 v2 是提升弹性伸缩能力的关键步骤。以下是标准迁移流程：

1. 确认集群版本： 确保 Kubernetes 集群版本 >= v1.23，以原生支持 autoscaling/v2。
2. 导出现有 HPA 配置： 使用 kubectl get hpa <name> -o yaml > hpa-current.yaml 导出当前配置。
3. 使用 kubectl convert 进行转换： 这是最推荐的自动化迁移方式。

   kubectl convert -f hpa-current.yaml --output-version autoscaling/v2 -o hpa-v2.yaml

4. 手动校验与调整： 检查转换后的 hpa-v2.yaml 文件，特别是 metrics 和 behavior 字段，确保指标名称和策略符合预期。
5. 应用新版本 HPA： 先删除旧版本 HPA，再创建新版本。

   kubectl delete hpa <name>
   kubectl apply -f hpa-v2.yaml

6. 验证状态： 使用 kubectl describe hpa <name> 查看 Conditions 和 Current Metrics，确认 HPA 正常工作。

3.4 版本演进架构图

下图展示了 HPA API 版本从 v1 到 v2 的演进路径，以及各版本在指标类型和功能上的关键差异。

3.5 迁移避坑指南

3.6 版本选择决策矩阵