kubectl diff 是什么
diff 用来在执行 apply 之前回答“这次会改什么”：它把本地文件用服务端试运行（server-side dry-run）提交给 API Server，再把返回结果与集群中现存对象比较，输出类似 UNIX diff 的差异行。它不写入任何数据，适合放在发布流程里当人工审查或自动化卡点。需要 API Server 支持试运行，集群过旧时只能退化成人工比对。
基本信息
| 语法 | kubectl diff -f 文件.yaml ｜ kubectl diff -k 目录 |
|---|---|
| 适用平台 | kubectl 1.13 起提供；试运行需 API Server 支持 |
| 输出 | 以 +/- 行给出差异，按对象分段，段首是资源类型与名称 |
| 退出码 | 0 表示无差异，1 表示有差异，大于 1 表示命令或连接出错 |
| 外部工具 | 环境变量 KUBECTL_EXTERNAL_DIFF 可换成 colordiff 等，便于并排阅读 |
| 权限 | 需要目标资源的 get 与 patch 权限（试运行同样走鉴权） |
典型使用场景
- 上线前确认这次发布到底动了哪些字段
- CI 里把差异作为审查输出，附在合并请求里
- 排查“配置改了但集群没变”的原因，确认对象是否被别的控制器改回
- 迁移目录结构或多环境时对比渲染结果与集群现状
- 核对 Kustomize 渲染后的最终结果是否符合预期
使用示例
使用示例
kubectl diff -f deploy.yaml # 预览单个文件的变更
kubectl diff -f k8s/prod/ # 目录批量预览
kubectl diff -k overlays/prod/ # Kustomize 渲染后再比
KUBECTL_EXTERNAL_DIFF='diff -u' kubectl diff -f deploy.yaml # 换外部 diff 工具
echo "exit=$?" # 1 表示存在差异，不是失败
kubectl diff -f deploy.yaml | head -60 # 差异很长时先看前几十行退出码读法
| 退出码 | 含义 | 使用方式 |
|---|---|---|
| 0 | 文件与集群一致 | 可跳过 apply，或继续走幂等流程 |
| 1 | 存在差异 | 视为“有变更待发布”，不应判为失败 |
| 大于 1 | 命令、连接或鉴权出错 | 这才是真正的错误，应中断流水线 |
| 试运行被拒 | 集群不支持 dry-run 或权限不足 | 看错误信息，必要时改用 get -o yaml 人工比对 |
差异里会混进 API Server 补的默认值与控制器写入的 status、managedFields：阅读时聚焦 spec 与 metadata 上的实质变更。
diff 只做比较，不做校验之外的写入：确认无误后仍需自己执行 apply，它不会替你发布。