2. Kubernetes API版本机制：API组、版本（alpha/beta/stable）、API优先级与废弃策略

2.1 API组（API Group）——资源分类的命名空间

Kubernetes 将所有 API 资源按功能域划分为多个 API 组。API 组是资源路径的第一级逻辑分类，决定了资源属于哪个功能领域。核心组（core group）使用空字符串表示，路径为 /api/v1；命名组（named group）路径为 /apis/<group>/<version>。

2.2 版本等级：alpha → beta → stable

每个 API 组内的资源可以同时存在多个版本，Kubernetes 使用三个等级标识版本的成熟度：

• alpha（α）：默认关闭，包含实验性功能，可能随时移除且不保证向后兼容。版本号如 v1alpha1、v2alpha2。
• beta（β）：默认开启，经过充分测试，功能基本稳定，但可能仍有少量变更。版本号如 v1beta1、v2beta2。
• stable（GA）：正式发布，长期支持，保证向后兼容。版本号如 v1、v2。

2.3 API 优先级与废弃策略

Kubernetes 通过 API 优先级（API Priority） 和 废弃策略（Deprecation Policy） 控制版本的生命周期，确保集群升级时资源对象的平滑迁移。

2.3.1 优先级排序规则

当同一资源存在多个版本时，Kubernetes 按以下优先级选择首选版本（preferred version）：

1. stable > beta > alpha：稳定版优先于测试版，测试版优先于实验版。
2. 版本号数值大优先：例如 v2 优先于 v1，v2beta2 优先于 v2beta1。
3. 同一等级内，数值大的版本优先：v1beta2 优先于 v1beta1。

2.3.2 废弃策略时间线

Kubernetes 官方废弃策略规定：

• beta 版本废弃后：至少再支持 3 个版本（约 9 个月）才会被移除。
• stable 版本废弃后：至少再支持 1 年才会被移除。
• alpha 版本：无废弃期，可随时移除。

2.4 API 版本生命周期 SVG 图

2.5 版本选择与迁移策略

在实际集群运维中，应遵循以下版本选择原则：

• 优先使用 stable 版本：所有生产资源应使用 v1 版本。
• 避免使用 alpha 版本：除非在开发测试环境中验证新功能。
• 关注废弃警告：使用 kubectl get --raw 或 Kyverno 策略检测废弃 API 使用。
• 提前规划迁移：在集群升级前，使用 kubectl convert 或 Kyverno 策略批量转换资源版本。

2.6 常见废弃 API 版本示例

2.7 API 版本检测与 Kyverno 策略集成

Kyverno 可以通过以下方式检测废弃 API 版本：

1. 验证规则（validate）：检查资源 apiVersion 字段是否匹配已废弃版本列表。
2. 变更规则（mutate）：自动将废弃版本资源转换为首选版本。
3. 生成规则（generate）：为使用废弃版本的资源生成迁移报告。

# Kyverno 策略示例：检测废弃的 Ingress 版本
apiVersion: kyverno.io/v1
kind: ClusterPolicy
metadata:
  name: detect-deprecated-ingress
spec:
  validationFailureAction: audit
  rules:
  - name: check-ingress-version
    match:
      resources:
        kinds:
        - Ingress
    validate:
      message: "Ingress 使用废弃版本 {{ request.object.apiVersion }}，请迁移至 networking.k8s.io/v1"
      deny:
        conditions:
          any:
          - key: "{{ request.object.apiVersion }}"
            operator: In
            value:
            - "extensions/v1beta1"
            - "networking.k8s.io/v1beta1"