kubectl diff指定目录无差异输出但指定单文件正常的排查方法

按以下顺序逐步排查即可定位根本原因：

• 开启详细日志追踪执行全流程：执行 kubectl diff -f k8s-test/ -v=6，查看日志中实际枚举、加载的文件列表，确认是否存在文件跳过、路径识别错误、格式过滤的提示。如果日志中没有出现k8s-test/deployment.yaml的加载记录，问题就出在目录扫描、文件识别阶段。
• 校验目录扫描的资源加载结果：执行 kubectl apply -f k8s-test/ --dry-run=client -o yaml，查看命令最终输出的所有资源清单。如果输出中完全没有预期的Deployment资源，说明目录扫描逻辑没有加载到该文件，优先排查两个高频触发场景：

  1. 自动kustomize逻辑接管：检查k8s-test/目录下是否存在kustomization.yaml、kustomization.yml、Kustomization三类文件的任意一个。只要目录下存在这类文件，kubectl会自动将该目录识别为kustomize项目，不再直接读取目录下零散的yaml配置，仅加载kustomization.yaml的resources字段中声明的资源。可执行kubectl kustomize k8s-test/验证输出的资源列表，如果列表中没有对应的Deployment，说明kustomization配置未引用deployment.yaml，这是该场景下最常见的根因。
  2. 未开启递归目录扫描：kubectl默认以目录为输入源时，只会读取目录根层级的直接文件，不会自动遍历子目录。如果deployment.yaml实际存放在k8s-test的子目录下，不加-R参数时扫描不会读取到该文件，可执行kubectl diff -f k8s-test/ -R开启递归扫描验证。

• 排查特殊文件属性问题：如果日志显示已经加载deployment.yaml但仍无输出，检查两类文件属性问题：
  • 确认deployment.yaml是否为软链接文件，1.20之前的旧版本kubectl扫描目录时会默认跳过软链接类型的配置文件，但直接指定软链接文件路径时可以正常读取。
  • 确认目录下yaml文件的读权限，检查是否存在SELinux、ACL等权限规则导致目录遍历时无法读取文件内容，直接指定路径时可正常读取的异常情况。
• 版本兼容性校验：执行kubectl version查看客户端版本，1.18之前的旧版本存在多个目录扫描相关的已知bug，升级客户端到稳定版后重试即可。

内容的提问来源于stack exchange，提问作者Ivan Aracki