📚 课程目录第3章 kustomization.yaml变更导致缓存失效

常见故障场景一：本地文件修改后缓存未刷新

在 Kustomize 工作流中，最频繁遇到的缓存失效问题就是“本地修改了 kustomization.yaml 或资源文件，但重新构建时仍然输出旧内容”。这种现象通常不是 Kustomize 本身的 Bug，而是构建环境、文件系统或缓存机制共同作用的结果。本节将系统分析该场景的根因、排查路径与修复方案。

1. 故障现象与影响范围

现象	典型表现	影响范围
修改后输出不变	编辑 kustomization.yaml 中的 resources 列表，`kustomize build` 仍输出旧资源	本地开发、CI 流水线
新增文件不生效	在 base 目录添加新的 Deployment YAML，构建后未包含该资源	多环境 overlay 继承
patches 未应用	修改 patchesStrategicMerge 中的补丁文件，构建后补丁未生效	配置覆盖、环境差异化
vars 引用失效	更新 vars 中引用的 ConfigMap 数据，构建后仍使用旧值	参数化配置、模板渲染

快速自检：执行 kustomize build --reorder none . 并对比输出内容的 metadata.generation 或 resourceVersion（如果存在），可以快速判断缓存是否参与构建。

2. 根因分析：缓存命中与失效机制

Kustomize 在 4.x 版本中引入了基于文件内容的哈希缓存机制。当执行 kustomize build 时，构建器会为每个输入文件计算 SHA256 哈希，并与缓存目录中的记录比对。如果哈希匹配，则直接返回缓存结果；否则重新加载并解析文件。

本地文件修改后缓存未刷新的常见根因包括：

文件系统时间戳精度不足：某些文件系统（如 FAT32、旧版 NFS）的时间戳精度仅为 2 秒，快速连续修改可能被缓存系统认为“文件未变化”。
符号链接与硬链接：通过符号链接引用的文件，Kustomize 可能缓存了链接目标路径的旧内容，而实际修改的是链接源文件。
缓存目录权限或锁定：缓存文件被其他进程锁定，或当前用户无写入权限，导致新哈希无法写入缓存。
构建工具链的中间缓存：如果通过 kubectl kustomize 或 Argo CD 等工具间接调用 Kustomize，这些工具可能维护了独立的缓存层。
Kustomize 版本差异：v3.x 与 v4.x 的缓存策略不同，v3.x 默认不启用文件哈希缓存，而 v4.x 默认启用。

3. 故障排查步骤

当怀疑本地文件修改后缓存未刷新时，按以下步骤逐层排查：

确认文件修改时间：使用 stat <file> 查看文件的 Modify 时间戳，确认修改是否被文件系统正确记录。
清除 Kustomize 缓存：执行 rm -rf ~/.kustomize/cache 或 kustomize clean（v4.5+），强制清除所有缓存。
使用 --no-cache 标志：Kustomize v4.5+ 支持 kustomize build --no-cache .，跳过缓存直接构建。
检查符号链接解析：使用 readlink -f <file> 确认 Kustomize 实际读取的文件路径。
验证缓存目录权限：检查 ~/.kustomize/cache 目录的读写权限，确保当前用户可写入。
对比构建日志：启用详细日志 kustomize build --v=5 .，观察缓存命中/未命中的日志输出。

注意：在 CI/CD 环境中，每次构建通常运行在独立的容器或 VM 中，缓存目录默认不存在，因此缓存问题较少出现。但若使用持久化缓存卷（如 Jenkins 的 workspace 缓存），则可能复现本地问题。

4. 修复方案与最佳实践

方案	适用场景	操作命令/配置
全局禁用缓存	开发环境、频繁修改	`export KUSTOMIZE_CACHE=none` 或 `kustomize build --no-cache .`
定期清理缓存	CI 流水线、共享环境	在构建脚本中添加 `rm -rf ~/.kustomize/cache`
使用文件监听	本地开发、热重载	配合 `watchexec` 或 `entr` 自动触发构建
避免符号链接	所有场景	使用 `cp -L` 复制链接指向的实际文件
升级 Kustomize 版本	v4.4 及以下	升级到 v4.5+ 以获得更可靠的缓存失效逻辑

5. 案例演示：从修改到验证

以下是一个完整的本地修改后缓存未刷新的排查与修复案例：

# 1. 初始状态：构建输出正常
$ kustomize build . | grep -c "kind: Deployment"
3

# 2. 修改 base/deployment.yaml，增加一个 Deployment
$ echo "---" >> base/deployment.yaml
$ cat >> base/deployment.yaml <<EOF
apiVersion: apps/v1
kind: Deployment
metadata:
  name: new-app
spec:
  replicas: 1
  selector:
    matchLabels:
      app: new-app
  template:
    metadata:
      labels:
        app: new-app
    spec:
      containers:
      - name: app
        image: nginx:latest
EOF

# 3. 再次构建，输出仍为 3 个 Deployment（缓存命中旧内容）
$ kustomize build . | grep -c "kind: Deployment"
3

# 4. 检查文件时间戳
$ stat base/deployment.yaml | grep Modify
Modify: 2025-03-21 14:35:02.123456789 +0800

# 5. 清除缓存并重新构建
$ rm -rf ~/.kustomize/cache
$ kustomize build . | grep -c "kind: Deployment"
4

# 6. 验证成功：新 Deployment 已包含在输出中
$ kustomize build . | grep "name: new-app"
  name: new-app

  关键结论：本地文件修改后缓存未刷新，90% 的情况可以通过清除缓存目录或使用 --no-cache 标志快速解决。如果问题持续，应检查文件系统类型、符号链接和构建工具链的中间缓存层。

6. 预防性配置建议

为避免该场景反复出现，建议在开发环境和 CI 配置中采用以下策略：

开发环境：在 shell 配置文件（.bashrc / .zshrc）中设置 alias kbuild='kustomize build --no-cache .'，默认跳过缓存。
CI 环境：在每个构建步骤前显式执行 kustomize clean 或删除缓存目录，确保构建环境干净。
版本锁定：在 kustomization.yaml 中通过 apiVersion: kustomize.config.k8s.io/v1beta1 锁定 Kustomize 版本行为，避免跨版本缓存策略差异。
文件组织：避免在 overlay 中直接引用 base 目录外的符号链接，所有资源文件应位于同一 Git 仓库内。