4. kubectl convert 工具：将旧版 Deployment YAML 转换为新版
在 Kubernetes 集群升级过程中，API 版本的废弃与迁移是最常见的兼容性问题。手动修改 YAML 文件不仅效率低下，而且容易引入格式错误或语义偏差。kubectl convert 是 Kubernetes 官方提供的命令行工具，能够自动将旧版 API 资源的 YAML 转换为目标版本，是集群升级前批量适配 Deployment 配置的首选方案。
4.1 工具安装与版本匹配
kubectl convert 作为 kubectl 的插件分发，需要单独安装。安装时需注意：插件版本必须与目标集群的 Kubernetes 版本一致，否则可能产生不兼容的转换结果。
| 安装方式 | 命令 / 步骤 | 适用场景 |
|---|---|---|
| Krew 插件管理器 | kubectl krew install convert |
推荐方式，自动匹配 kubectl 版本 |
| 手动下载二进制 | 从 GitHub release 下载对应平台文件，放入 PATH | 离线环境或定制安装路径 |
| 包管理器 | apt-get install kubectl-convert（部分发行版） |
系统级统一管理 |
版本校验：安装后执行
kubectl convert --version，确认输出中的版本号与目标集群 kubectl version 的 Server Version 一致。版本不匹配时，转换可能遗漏字段或生成无效配置。
4.2 核心转换命令与参数
kubectl convert 的基本语法如下：
kubectl convert -f <旧版YAML文件> --output-version <目标API版本>常用参数说明：
-f：指定输入文件，支持单个文件、目录或 URL。--output-version：指定转换后的目标 API 版本，例如apps/v1。-o：输出格式，常用yaml或json，默认与输入格式一致。--local：仅使用本地 schema 进行转换，不连接集群 API Server。
典型转换示例：将
extensions/v1beta1 的 Deployment 转换为 apps/v1。
kubectl convert -f deploy-legacy.yaml --output-version apps/v1 -o yaml > deploy-new.yaml4.3 转换流程与内部机制
下图展示了 kubectl convert 从读取旧版 YAML 到输出新版配置的完整处理链路：
4.4 关键转换规则与字段变更
从 extensions/v1beta1 或 apps/v1beta2 转换到 apps/v1 时，kubectl convert 会自动处理以下核心变更：
| 旧版字段 | 新版字段 | 转换行为 |
|---|---|---|
spec.selector（可选） |
spec.selector（必填） |
若旧版未设置，自动从 spec.template.metadata.labels 继承 |
spec.rollbackTo |
已移除 | 转换时直接删除该字段，需手动配置回滚策略 |
spec.progressDeadlineSeconds |
保持不变 | 旧版未设置时，默认注入 600 秒 |
spec.revisionHistoryLimit |
保持不变 | 旧版未设置时，默认注入 10 |
apiVersion |
apps/v1 |
自动替换 Group 和 Version |
4.5 批量转换与目录处理
当需要转换整个 Helm Chart 或 GitOps 仓库中的多个 YAML 文件时，kubectl convert 支持目录递归处理：
# 转换当前目录下所有 YAML 文件
kubectl convert -f ./deployments/ --output-version apps/v1 -o yaml --recursive
# 仅转换 Deployment 资源，忽略其他 Kind
kubectl convert -f ./manifests/ --output-version apps/v1 -o yaml | grep -A 50 "kind: Deployment"
重要提醒：批量转换后务必进行差异对比（
diff），确认转换结果符合预期。自动注入的默认值（如 progressDeadlineSeconds）可能改变原有行为，建议在测试环境验证后再应用到生产集群。
4.6 转换后的验证步骤
完成转换后，建议按以下清单逐项验证：
- 语法校验：
kubectl apply --validate=true --dry-run=client -f deploy-new.yaml - 字段完整性：对比新旧 YAML，确认
spec.selector、spec.template等关键字段已正确迁移。 - 集群模拟：在非生产集群执行
kubectl apply -f deploy-new.yaml，观察 Pod 是否正常启动。 - 回滚测试：验证
kubectl rollout undo在新版 API 下仍能正常工作。
最佳实践：将
kubectl convert 集成到 CI/CD 管道的预检查阶段，在每次集群升级前自动扫描仓库中的旧版 YAML 并生成转换报告，确保所有 Deployment 配置与目标集群版本兼容。