4. Kubernetes 版本升级路径：跨版本升级的API兼容性矩阵

Kubernetes 社区遵循 N-2 支持策略（即仅维护最近三个次要版本），但实际生产集群往往存在多个大版本跨越。跨版本升级时，API 资源的增删改、废弃（Deprecated）与移除（Removed）是导致工作负载中断的首要风险。本节构建跨版本 API 兼容性矩阵，帮助运维人员精准识别升级路径中的依赖断裂点。

4.1 版本跳跃与 API 生命周期阶段

Kubernetes API 版本遵循 Alpha → Beta → Stable → Deprecated → Removed 的生命周期。跨版本升级时，必须检查每个 API 资源在源版本与目标版本之间的状态变化。

4.2 跨版本 API 兼容性矩阵（1.20 → 1.28）

以下矩阵展示从 Kubernetes 1.20 到 1.28 之间，常见 API 资源在每次升级时的状态变化。矩阵行代表 API 资源（含版本），列代表升级目标版本；单元格标记该资源在目标版本中的状态。

4.3 跨版本升级 API 依赖分析流程

在节点池巡检中，针对跨版本升级的 API 依赖分析应遵循以下步骤：

1. 枚举当前集群 API 资源使用清单：
   

   kubectl api-resources --verbs=list --namespaced -o name | sort > current_apis.txt
   kubectl get --raw /openapi/v2 | jq '.paths | keys' > current_api_paths.json

2. 获取目标版本的 API 可用清单：
   

   # 使用 kubectl convert 或模拟集群
   kubectl api-resources --cached --api-version=1.28 -o name | sort > target_apis.txt

3. 对比差异，标记废弃/移除项：
   

   diff current_apis.txt target_apis.txt | grep '^<' | awk '{print $2}' > removed_apis.txt

4. 检查每个废弃/移除 API 的实际使用对象：
   

   for api in $(cat removed_apis.txt); do
     kubectl get $api --all-namespaces -o name 2>/dev/null
   done > affected_resources.txt

5. 生成迁移计划：对每个受影响资源，确定目标版本中的替代 API 版本，并执行 kubectl convert 或手动修改 YAML。

4.4 跨版本升级 API 兼容性决策流程图

下图展示从源版本到目标版本的 API 兼容性检查与迁移决策路径：

4.5 节点池巡检中的 API 兼容性检查清单

在节点池巡检场景中，针对每个节点池的 API 依赖，应逐项检查以下内容：

• 节点池内所有工作负载的 API 版本：通过 kubectl get --all-namespaces -o yaml 导出并解析 apiVersion 字段。
• 废弃 API 使用统计：使用 kubectl get apiservice 查看已注册的 API 服务，结合 kubectl get --raw /apis 获取完整 API 组版本列表。
• 自定义资源定义（CRD）兼容性：检查 CRD 的 spec.versions 中是否包含即将废弃的版本，以及是否已提供 storage: true 的稳定版本。
• Webhook 与 Admission 插件：确认 ValidatingWebhookConfiguration 和 MutatingWebhookConfiguration 引用的 API 版本在目标集群中仍然存在。
• Helm Chart 与 Operator：检查 Helm Chart 的 apiVersion 字段（v1 或 v2），以及 Operator 管理的 CRD 版本是否与目标集群兼容。

#!/bin/bash
# 检查当前集群中所有使用废弃 API 的资源
UPGRADE_TARGET="1.28"
CURRENT_VERSION=$(kubectl version --short | grep Server | awk '{print $3}')

echo "=== 当前版本: $CURRENT_VERSION → 目标版本: $UPGRADE_TARGET ==="

# 获取所有 API 资源及其版本
kubectl api-resources --verbs=list -o name | while read resource; do
  # 检查每个资源是否在目标版本中可用
  if ! kubectl api-resources --cached --api-version=$UPGRADE_TARGET | grep -q "$resource"; then
    echo "⚠️  废弃资源: $resource"
    kubectl get $resource --all-namespaces -o name 2>/dev/null | head -5
  fi
done

4.6 常见跨版本升级阻断场景

4.7 跨版本升级 API 兼容性矩阵可视化

以下 SVG 图展示从 Kubernetes 1.20 到 1.28 的 API 版本演进路径，突出显示每个版本中废弃（黄色）与移除（红色）的 API 资源：

4.8 升级路径推荐策略

基于上述兼容性矩阵，针对不同源版本到目标版本的升级路径，推荐以下策略：