4. HPA YAML 配置结构详解

HorizontalPodAutoscaler（HPA）是 Kubernetes 实现 Pod 水平自动伸缩的核心 API 资源。其 YAML 清单遵循标准的 Kubernetes 资源结构，由 apiVersion、kind、metadata 和 spec 四个顶层字段组成。其中 spec 字段包含了弹性伸缩的全部运营参数，是运维人员配置的焦点。

4.1 apiVersion 与 kind

这两个字段定义了 HPA 资源的 API 组和资源类型，是 Kubernetes 资源清单的固定入口。

4.2 metadata

metadata 用于标识 HPA 资源实例，包含名称、命名空间、标签和注解等元数据。

• name（必填）：HPA 资源名称，在命名空间内唯一。建议命名规范为 <工作负载名>-hpa，例如 nginx-deployment-hpa。
• namespace（可选）：HPA 所在命名空间，默认值为 default。HPA 必须与目标工作负载位于同一命名空间。
• labels（可选）：用于资源分组和选择，建议添加 app、tier 等标签。
• annotations（可选）：用于存储非标识性元数据，如 autoscaling.alpha.kubernetes.io/behavior 可配置伸缩行为。

metadata:
  name: web-frontend-hpa
  namespace: production
  labels:
    app: web-frontend
    tier: frontend
  annotations:
    autoscaling.alpha.kubernetes.io/behavior: '{"scaleDown":{"stabilizationWindowSeconds":300}}'

4.3 spec 核心配置域

spec 是 HPA 的运营配置核心，包含 scaleTargetRef、minReplicas、maxReplicas 和 metrics 四个关键字段。以下逐一详解。

4.3.1 scaleTargetRef：伸缩目标引用

scaleTargetRef 指定 HPA 要控制哪个工作负载的副本数。它是一个对象引用，包含三个子字段：

4.3.2 minReplicas 与 maxReplicas：伸缩边界

这两个字段定义了副本数的上下限，是弹性伸缩的安全护栏。

• minReplicas（默认值：1）：HPA 允许缩容到的最小副本数。生产环境建议设置为 2 或更高，以保证基础高可用。
• maxReplicas（必填）：HPA 允许扩容到的最大副本数。需根据集群资源容量和业务峰值合理设置，防止无限扩容耗尽集群资源。

4.3.3 metrics：伸缩指标数组

metrics 是一个数组，每个元素定义一个指标及其目标值。HPA 控制器会定期采集这些指标，计算期望副本数，并触发伸缩操作。Kubernetes autoscaling/v2 支持四种指标类型：

以下是一个包含资源指标和 Pod 指标的完整 HPA YAML 示例：

apiVersion: autoscaling/v2
kind: HorizontalPodAutoscaler
metadata:
  name: web-frontend-hpa
  namespace: production
spec:
  scaleTargetRef:
    apiVersion: apps/v1
    kind: Deployment
    name: web-frontend
  minReplicas: 2
  maxReplicas: 10
  metrics:
  - type: Resource
    resource:
      name: cpu
      target:
        type: Utilization
        averageUtilization: 70
  - type: Resource
    resource:
      name: memory
      target:
        type: Utilization
        averageUtilization: 80
  - type: Pods
    pods:
      metric:
        name: http_requests_per_second
      target:
        type: AverageValue
        averageValue: 1000

4.4 完整 YAML 配置清单与字段速查

以下表格汇总了 HPA YAML 所有关键字段及其配置要求，便于运维人员快速查阅和编排：