Kubernetes API 版本演进机制

Kubernetes 的 API 版本演进是 Operator 开发与集群升级适配的核心基础。理解 API 组、版本化路径以及废弃与移除策略，能够帮助开发者在集群升级后快速定位 API 变更，并确保 Operator 的兼容性。

2.1 API 组与版本化路径

Kubernetes API 通过 API 组（API Group） 对资源进行逻辑分类，每个组内的资源可以拥有多个版本。版本化路径遵循 alpha → beta → stable 的演进阶梯，每个阶段代表不同的稳定性与功能成熟度。

2.2 废弃与移除策略

Kubernetes 对 API 版本的废弃与移除有严格的策略，通常遵循 N-3 规则：一个 API 版本在标记为废弃（Deprecated）后，至少会保留 3 个次要版本才会被移除。Operator 开发者需要密切关注每个 Kubernetes 版本的 Deprecated API 清单。

2.3 版本转换与多版本支持

Kubernetes 支持在 API Server 层面进行 版本转换（Version Conversion），允许集群内部同时存储多个版本的资源。Operator 可以通过 Conversion Webhook 实现自定义资源的版本转换，确保新旧版本之间的数据兼容。

2.4 废弃 API 检测与迁移步骤

在集群升级前，Operator 开发者应执行以下步骤检测并处理废弃 API：

1. 扫描集群：使用 kubectl api-resources --cached 列出所有 API 资源，并检查 DEPRECATED 列。
2. 审计 Operator 代码：在 controllers/ 和 api/ 目录中搜索所有硬编码的 API 版本字符串。
3. 更新 CRD 定义：在 CustomResourceDefinition 的 spec.versions 中移除已废弃的版本，并确保 storage 版本为 Stable。
4. 测试转换：在测试集群中部署新版本 Operator，验证 CR 实例的读写与转换是否正常。
5. 灰度升级：在生产集群中逐步替换旧版本 Operator，监控 API 调用错误日志。

import (
    "k8s.io/client-go/discovery"
    "k8s.io/client-go/kubernetes"
)

func checkAPIVersion(clientset kubernetes.Interface, group, version string) bool {
    discoveryClient := clientset.Discovery()
    apiResourceList, err := discoveryClient.ServerResourcesForGroupVersion(group + "/" + version)
    if err != nil {
        return false
    }
    return len(apiResourceList.APIResources) > 0
}

2.5 版本演进对 Operator 的影响总结