2. Kustomize 核心架构：kustomization.yaml 结构、资源生成器、转换器、校验器的工作流
Kustomize 的核心设计哲学是“模板免维护”——它不引入模板语法，而是通过声明式配置叠加实现资源定制。理解其核心架构，是分析缓存命中性能瓶颈的前提。本章将拆解 kustomization.yaml 的结构，并深入资源生成器、转换器、校验器三阶段工作流。
2.1 kustomization.yaml 结构解析
kustomization.yaml 是 Kustomize 的入口文件，它声明了所有资源来源、定制规则和输出配置。一个典型的文件结构如下：
apiVersion: kustomize.config.k8s.io/v1beta1
kind: Kustomization
# 资源来源
resources:
- deployment.yaml
- service.yaml
- github.com/org/repo//base?ref=v1.0
# 资源生成器
configMapGenerator:
- name: app-config
files:
- config/app.properties
secretGenerator:
- name: db-secret
literals:
- password=supersecret
# 转换器（Transformers）
patches:
- path: patch-replicas.yaml
target:
kind: Deployment
name: web-app
images:
- name: nginx
newTag: 1.25.0
namespace: production
namePrefix: prod-
# 校验器
validators:
- kustomize-validator.yaml
核心字段按功能可分为三类，对应 Kustomize 的三阶段工作流：
| 字段类别 | 典型字段 | 所属阶段 | 缓存影响 |
|---|---|---|---|
| 资源来源 | resources, bases |
资源生成器 | 远程资源拉取是缓存失效主因 |
| 资源生成器 | configMapGenerator, secretGenerator |
资源生成器 | 文件内容哈希决定缓存键 |
| 转换器 | patches, images, namespace, namePrefix |
转换器 | 补丁顺序影响中间产物缓存 |
| 校验器 | validators |
校验器 | 校验失败提前终止，避免无效缓存 |
kustomization.yaml 的字段顺序不影响最终输出，但影响 Kustomize 内部构建图的拓扑排序。缓存系统依赖的是字段内容的哈希值，而非字段排列顺序。
2.2 三阶段工作流总览
Kustomize 将资源构建过程划分为三个严格顺序的阶段，每个阶段都有独立的缓存域：
- 资源生成器（Resource Generator）：加载所有原始资源，包括本地 YAML、远程 Git 仓库、ConfigMap/Secret 生成器。
- 转换器（Transformer）：对已生成的资源列表应用补丁、镜像替换、名称前缀、命名空间等定制规则。
- 校验器（Validator）：对最终输出进行结构校验和策略检查，确保资源符合集群要求。
下图展示了三阶段工作流及其数据传递关系：
2.3 资源生成器：缓存的第一道防线
资源生成器是 Kustomize 构建的起点，也是缓存命中率最高的阶段。它负责将 resources 字段中声明的所有来源转换为内存中的资源对象列表。
生成器内部处理流程：
- 本地文件加载：读取
resources中指定的本地 YAML 文件，计算文件内容的 SHA256 哈希作为缓存键。 - 远程资源拉取：对 Git 仓库引用（如
github.com/org/repo//base?ref=v1.0），Kustomize 执行git clone或稀疏检出，缓存键包含仓库 URL + 分支/标签 + 路径。 - ConfigMap/Secret 生成：对
configMapGenerator和secretGenerator，Kustomize 读取文件内容或字面量，生成哈希缓存键。
ref（标签/提交哈希）。始终使用固定标签而非 main 分支，可大幅提升缓存命中率。
2.4 转换器：补丁顺序与中间产物缓存
转换器阶段接收生成器输出的原始资源列表，按 kustomization.yaml 中声明的顺序依次应用转换规则。转换器分为两类：
| 转换器类型 | 示例字段 | 执行顺序 | 缓存粒度 |
|---|---|---|---|
| 内置转换器 | namespace, namePrefix, nameSuffix, commonLabels, commonAnnotations |
最先执行，固定顺序 | 按字段值哈希缓存 |
| 补丁转换器 | patches, patchesStrategicMerge, patchesJson6902 |
按 patches 列表顺序执行 |
按补丁文件内容 + 目标选择器哈希缓存 |
| 镜像转换器 | images |
在补丁之后执行 | 按镜像名称 + 新旧标签哈希缓存 |
| 变量替换转换器 | vars |
最后执行 | 按变量定义哈希缓存 |
转换器阶段的缓存设计有一个重要特性：中间产物缓存。Kustomize 会在每个转换器应用后保存当前资源列表的哈希快照。如果后续构建中某个转换器的输入未变，则跳过该转换器及其之后的所有转换器，直接复用缓存。
patches 列表中有 10 个补丁，第 3 个补丁发生变化，则第 4-10 个补丁的缓存全部失效。建议将高频变动的补丁放在列表末尾，以最大化中间产物缓存命中率。
2.5 校验器：最终输出的质量门禁
校验器是 Kustomize 构建的最后一环，对转换器输出的最终资源列表进行验证。Kustomize 内置了基本的 Kubernetes 资源结构校验，同时支持通过 validators 字段引入自定义校验逻辑。
校验器的工作机制：
- 内置结构校验：检查资源是否包含必需的字段（如
apiVersion,kind,metadata.name），字段值类型是否正确。 - 自定义校验器：通过
validators字段引用独立的 Kustomize 校验文件，这些文件可以定义更复杂的策略规则（如强制要求所有 Deployment 设置资源限制）。 - 缓存行为：校验器阶段的缓存键基于最终输出资源的完整哈希。如果校验通过，该哈希被缓存；下次构建时，如果生成器和转换器阶段的输出哈希与缓存一致，则直接跳过校验器。
2.6 三阶段缓存依赖关系
理解三个阶段之间的缓存依赖关系，是性能优化的基础。下图展示了缓存键的传递与失效传播路径：
2.7 架构总结与性能启示
Kustomize 的三阶段架构设计，本质上是一种增量构建模型。每个阶段都尽可能复用前序计算结果，减少重复计算。从缓存命中性能角度看，以下架构特征值得关注：
- 阶段隔离性：每个阶段有独立缓存域，上游变更不会导致下游全部重算（中间产物缓存机制）。
- 哈希驱动：所有缓存键基于内容哈希，而非时间戳或文件路径，确保缓存一致性。
- 顺序敏感性：转换器阶段的补丁顺序直接影响中间产物缓存的粒度，是性能优化的主要切入点。
- 远程依赖风险：资源生成器中的远程 Git 拉取是缓存失效的最大风险点，建议使用固定标签并启用本地缓存代理。