4、废弃API版本检测工具：kubectl convert、kubectl api-resources、kubectl api-versions的使用
在K8s集群升级前，准确识别当前集群与工作负载中使用的API版本是规避废弃风险的第一步。Kubernetes原生提供了三个核心命令行工具——kubectl convert、kubectl api-resources和kubectl api-versions，分别承担“版本转换”、“资源清单查询”和“版本列表查询”的职责。本节将逐一讲解其功能、使用场景及典型输出。
4.1 工具功能对比
| 工具 | 核心功能 | 典型用途 | 输出格式 |
|---|---|---|---|
kubectl api-versions |
列出集群API Server上所有已注册的API组及版本 | 快速查看集群支持哪些版本，判断废弃版本是否仍存在 | 文本列表（每行一个 group/version） |
kubectl api-resources |
列出所有API资源及其对应的API组、版本、是否名字空间级别 | 查找特定资源当前使用的API版本，识别已废弃的资源 | 表格（含NAME、SHORTNAMES、APIVERSION、NAMESPACED等列） |
kubectl convert |
将本地YAML/JSON资源文件在不同API版本之间转换 | 将旧版资源清单转换为目标版本，验证兼容性 | 标准输出（转换后的YAML/JSON） |
使用建议： 推荐按“先查版本 → 再查资源 → 最后转换文件”的顺序执行检测，形成完整的废弃API排查链路。
4.2 kubectl api-versions：查看集群API版本全景
该命令直接查询API Server的 /apis 和 /api/v1 端点，返回所有已启用的API组及其版本。输出结果可用于快速判断集群中是否仍包含即将废弃的旧版本（如 extensions/v1beta1、apps/v1beta2）。
# 列出所有API版本
kubectl api-versions
# 输出示例（部分）
apps/v1
autoscaling/v1
autoscaling/v2beta1
batch/v1
batch/v1beta1
extensions/v1beta1
networking.k8s.io/v1
networking.k8s.io/v1beta1
rbac.authorization.k8s.io/v1
storage.k8s.io/v1
storage.k8s.io/v1beta1
升级前必查： 如果输出中仍包含
extensions/v1beta1、apps/v1beta2、batch/v1beta1 等版本，说明集群中仍有资源在使用这些即将被移除的API版本，必须优先迁移。
4.3 kubectl api-resources：定位具体资源的API版本
该命令提供更细粒度的信息：不仅列出资源名称，还显示每个资源当前关联的API版本、是否支持名字空间隔离、以及短名称。通过过滤特定API组，可以快速锁定需要迁移的资源类型。
# 列出所有资源及其API版本
kubectl api-resources
# 按API组过滤（例如查看extensions组下的资源）
kubectl api-resources --api-group=extensions
# 输出示例（extensions组）
NAME SHORTNAMES APIVERSION NAMESPACED KIND
ingresses ing extensions/v1beta1 true Ingress
networkpolicies netpol extensions/v1beta1 true NetworkPolicy
podsecuritypolicies psp extensions/v1beta1 false PodSecurityPolicy
从上述输出可以清晰看到，extensions/v1beta1 下的 Ingress、NetworkPolicy、PodSecurityPolicy 均属于废弃API范围，需要迁移到 networking.k8s.io/v1 或 policy/v1beta1 等稳定版本。
4.4 kubectl convert：安全转换资源清单
该工具是迁移过程中的“翻译官”。它读取本地YAML/JSON文件，将其转换为目标API版本，并输出到标准输出。转换过程中会进行字段兼容性检查，如果旧版本中的某些字段在新版本中不再支持，会给出警告或错误提示。
# 将旧版Deployment从extensions/v1beta1转换为apps/v1
kubectl convert -f old-deploy.yaml --output-version apps/v1
# 将Ingress从extensions/v1beta1转换为networking.k8s.io/v1
kubectl convert -f old-ingress.yaml --output-version networking.k8s.io/v1
# 转换后直接应用（先预览再apply）
kubectl convert -f old-deploy.yaml --output-version apps/v1 | kubectl apply -f -
最佳实践： 转换前先备份原始文件；转换后务必对比新旧字段差异，特别是
apiVersion、kind 以及结构发生变化的字段（如Ingress的 spec.rules.http.paths.backend.serviceName 变为 service.name）。
4.5 三工具协同工作流
下图展示了在集群升级前，如何串联使用这三个工具完成废弃API的检测与迁移准备：
4.6 实战排查命令速查表
| 场景 | 命令 | 预期输出/作用 |
|---|---|---|
| 查看所有API版本 | kubectl api-versions |
列出所有group/version，快速发现废弃版本 |
| 查看extensions组资源 | kubectl api-resources --api-group=extensions |
显示该组下所有资源及其版本 |
| 查看所有名字空间级别资源 | kubectl api-resources --namespaced=true |
过滤出需要逐个检查的工作负载资源 |
| 转换单个文件 | kubectl convert -f file.yaml --output-version <target> |
输出转换后的YAML，验证兼容性 |
| 批量转换目录 | kubectl convert -f ./manifests/ --output-version apps/v1 |
批量处理多个资源清单 |
| 转换并直接应用 | kubectl convert -f file.yaml --output-version apps/v1 | kubectl apply -f - |
一步完成转换与部署（建议先预览） |
重要提醒：
kubectl convert 是一个客户端插件，从K8s 1.21开始已从kubectl主二进制中移除，需要单独安装 kubectl-convert 插件。如果集群版本较新，请使用 kubectl krew install convert 安装，或直接使用 kubectl apply --server-side 配合 --validate=false 进行服务端转换。
4.7 常见问题与避坑
- api-versions 输出为空或不全： 检查API Server是否正常运行，以及RBAC权限是否允许
get操作APIService资源。 - api-resources 显示版本与预期不符： 某些资源可能同时存在于多个API组中（如Ingress同时存在于
extensions/v1beta1和networking.k8s.io/v1），需确认实际使用的版本。 - convert 转换后字段丢失： 旧版中的某些字段（如
extensions/v1beta1的spec.backend.serviceName）在新版中已重命名或重构，转换工具不会自动填充，需要手动调整。 - 批量转换时忽略错误： 使用
--allow-missing-template-keys或--validate=false可能导致转换结果不完整，建议逐个文件验证。