4、API废弃策略与生命周期：Kubernetes官方废弃策略、GA与Beta版本的废弃时间线

在多租户集群升级工程中，API版本的废弃与迁移是风险最高的环节之一。Kubernetes官方为每个API资源定义了明确的生命周期阶段，从Alpha到Beta再到GA（General Availability），每个阶段都有对应的废弃时间窗口和迁移要求。理解这套策略，是制定集群升级计划的前提。

4.1 Kubernetes API生命周期的三个阶段

每个Kubernetes API资源（如Deployment、Pod、Ingress）在引入时都会经历以下阶段：

4.2 官方废弃策略与时间线

Kubernetes社区遵循KEP-1698（Kubernetes Enhancement Proposal）定义的废弃策略。核心规则如下：

• Beta API废弃：从标记为废弃的版本开始，该API仍可正常使用至少3个Kubernetes小版本（例如从v1.21到v1.24）。在此期间，集群会发出警告日志和事件。
• GA API废弃：GA版本一旦废弃，必须保留至少12个月或3个小版本（取较长者）。
• 移除通知：在API被实际移除前，Kubernetes会在对应版本的CHANGELOG、Deprecation Policy页面以及kube-apiserver的启动日志中明确告知。
• 多版本共存：在废弃窗口期内，旧的API版本和新的API版本可以同时服务于同一个资源。例如，networking.k8s.io/v1beta1 和 networking.k8s.io/v1 可以共存，直到旧版本被移除。

4.3 GA与Beta版本的废弃时间线对比

以下是一个典型的废弃时间线示例，以Ingress资源为例：

4.4 废弃API的检测与审计

在多租户集群中，检测哪些租户正在使用即将废弃的API版本是迁移的第一步。以下是几种常用方法：

• kube-apiserver 审计日志：通过启用审计策略（Audit Policy），记录所有使用废弃API版本的请求。审计日志中包含 requestReceivedTimestamp、user、resource 和 version 字段。
• kubectl 命令：使用 kubectl get --raw /metrics | grep apiserver_requested_deprecated_apis 获取当前集群中废弃API的请求计数。
• 准入控制器：部署自定义的 ValidatingAdmissionWebhook，在创建或更新资源时检查其API版本，如果使用了即将在下一个版本中移除的API，则拒绝请求并返回警告。

# 列出所有使用 networking.k8s.io/v1beta1 的 Ingress 资源
kubectl get ingress --all-namespaces -o json | \
  jq '.items[] | select(.apiVersion == "networking.k8s.io/v1beta1") | {namespace: .metadata.namespace, name: .metadata.name}'

4.5 多租户场景下的废弃策略适配

对于多租户集群，建议在Kubernetes官方废弃策略基础上，增加以下内部策略：