📚 课程目录第1章 Kustomize缓存机制概述

1. Kustomize 缓存机制概述

Kustomize 的缓存机制是提升大规模 Kubernetes 资源配置渲染效率的核心组件。当用户执行 kustomize build 或 kubectl apply -k 时，Kustomize 会从远程仓库、本地文件系统或 OCI 镜像中拉取 kustomization 依赖的 base 和 overlay 资源。缓存机制将这些拉取结果暂存到本地磁盘，避免重复的网络传输和文件解压操作，从而显著缩短后续构建的耗时。

  核心价值：缓存命中时，Kustomize 构建速度可提升 5~10 倍；缓存失效或未命中时，每次构建都会重新拉取远程资源，导致构建时间从秒级退化到分钟级。

1.1 缓存的作用

作用维度	具体说明	影响面
加速远程资源拉取	缓存 Git 仓库、HTTP(S) URL、OCI 镜像中的 kustomization 目录，避免重复 clone 或 pull	CI/CD 流水线、多环境部署
减少网络开销	本地缓存命中后不再发起网络请求，降低带宽消耗和外部依赖故障风险	离线环境、内网受限环境
保证构建确定性	缓存基于资源内容的哈希值索引，相同内容复用同一缓存条目，避免版本漂移	审计追溯、环境一致性
支持增量更新	仅重新拉取发生变更的远程资源，未变更部分直接命中缓存	大规模 monorepo、微服务多 overlay

1.2 缓存存储位置

Kustomize 的缓存目录遵循 XDG Base Directory 规范，默认位置因操作系统而异。用户可通过环境变量 KUSTOMIZE_CACHE_DIR 或 kustomization 中的 buildMetadata 字段自定义路径。

操作系统	默认缓存路径	环境变量覆盖
Linux	`~/.cache/kustomize/`	`KUSTOMIZE_CACHE_DIR`
macOS	`~/Library/Caches/kustomize/`	`KUSTOMIZE_CACHE_DIR`
Windows	`%LOCALAPPDATA%\kustomize\cache\`	`KUSTOMIZE_CACHE_DIR`

缓存目录内部结构按资源来源类型组织：

~/.cache/kustomize/
├── git/                          # Git 仓库缓存
│   ├── github.com_example_app.git/
│   │   ├── main/                 # 分支名
│   │   │   └── abc123def456/     # commit hash
│   │   └── v1.2.3/               # tag 名
│   └── ...
├── http/                         # HTTP(S) URL 缓存
│   └── raw.githubusercontent.com_example_manifest.yaml/
├── oci/                          # OCI 镜像缓存
│   └── registry.example.com_kustomize_base_v1.0.0/
└── tmp/                          # 临时解压目录

运维建议：在 CI/CD 环境中，建议将 KUSTOMIZE_CACHE_DIR 指向持久化卷（如 Jenkins workspace 或 GitLab runner 的缓存卷），避免每次构建都从零开始拉取远程资源。

1.3 缓存生命周期

Kustomize 缓存的生命周期由三个关键阶段构成：创建、命中/失效、清理。理解每个阶段的触发条件，是排查缓存问题的前提。

1.4 缓存生命周期关键参数

参数/行为	默认值	说明	影响范围
缓存 TTL	无固定 TTL（基于内容哈希）	只要缓存目录存在且内容哈希匹配，缓存一直有效；仅当远程资源哈希变化时失效	所有远程资源
Git 引用缓存	5 分钟（ref cache）	Git 分支/标签到 commit hash 的映射缓存，过期后重新 fetch 远程引用	Git 仓库资源
OCI 镜像层缓存	由容器运行时管理	Kustomize 仅缓存 manifest 和 config layer，blob 层由 containerd/Docker 管理	OCI 镜像资源
临时解压目录	构建完成后立即清理	远程 tar.gz/zip 解压到 tmp 目录，构建结束后删除	压缩包资源

常见误区：很多用户认为 Kustomize 缓存有固定 TTL（如 24 小时），实际上 Kustomize 的缓存失效主要依赖内容哈希比对，而非时间过期。只有当 Git 引用缓存（ref cache）有 5 分钟 TTL 时，才可能出现“分支指向新 commit 但缓存未更新”的情况。这是后续章节重点排查的场景之一。

1.5 缓存命中与失效的判定逻辑

Kustomize 在构建时按以下顺序判定缓存状态：

计算资源标识符：根据远程 URL、Git 仓库 + commit hash、OCI 镜像 digest 生成唯一缓存键。
检查本地缓存目录：查找 KUSTOMIZE_CACHE_DIR 下是否存在对应键的缓存条目。
校验内容完整性：读取缓存条目的元数据文件（如 .kustomize_cache_meta），比对期望的哈希值与实际缓存内容的哈希值。
判定结果：
- 缓存存在且哈希匹配 → 命中，直接读取缓存文件。
- 缓存不存在或哈希不匹配 → 失效，重新拉取远程资源并写入缓存。
- 缓存元数据损坏 → 失效，删除损坏条目后重新拉取。

调试命令：使用 kustomize build --stack-trace 可以输出详细的缓存操作日志，包括缓存键计算、命中/失效决策、缓存写入路径等，是排查缓存问题的第一手工具。