2. Kustomize 核心概念回顾：Overlay、Base、Patch、Kustomization 文件的结构与工作原理

在深入多集群准入策略故障排查之前，必须重新校准 Kustomize 的四个核心概念。绝大多数配置错误、资源覆盖失败、准入校验冲突，都源于对 Base、Overlay、Patch 和 Kustomization 文件 之间关系的理解偏差。本节从结构定义、工作原理到常见误区，逐一拆解。

2.1 四要素关系总览

Kustomize 采用“声明式资源叠加”模型，而非模板渲染。四个要素的协作关系如下：

2.2 Base：不可变的基础资源定义

Base 是 Kustomize 目录树的“根”，包含一组完整的 Kubernetes 资源 YAML 文件。Base 本身可以独立通过 kustomize build 生成有效输出，不依赖任何 Overlay。

2.3 Overlay：环境与集群的差异化层

Overlay 位于 Base 之上，代表特定环境（dev/staging/prod）或特定集群（cluster-a/cluster-b）的配置集合。每个 Overlay 目录包含自己的 kustomization.yaml，通过 bases: 或 resources: 字段引用 Base。

Overlay 的核心职责：

• 引用 Base：声明依赖哪个 Base 目录。
• 应用 Patch：通过 patchesStrategicMerge 或 patchesJson6902 修改 Base 资源。
• 新增资源：添加 Base 中不存在的资源（如 Ingress、HorizontalPodAutoscaler）。
• 修改元数据：通过 namePrefix、nameSuffix、namespace 等字段批量调整资源标识。

2.4 Patch：精准的增量修改指令

Patch 是 Kustomize 实现“声明式叠加”的关键机制。Kustomize 支持两种 Patch 格式：

2.5 Kustomization 文件：编排的声明式入口

kustomization.yaml 是 Kustomize 的“大脑”，它告诉 Kustomize 引擎：资源从哪里来、如何修改、如何输出。一个典型的 kustomization.yaml 结构如下：

# base/kustomization.yaml
apiVersion: kustomize.config.k8s.io/v1beta1
kind: Kustomization

resources:
  - deployment.yaml
  - service.yaml
  - configmap.yaml

---
# overlays/prod/kustomization.yaml
apiVersion: kustomize.config.k8s.io/v1beta1
kind: Kustomization

bases:
  - ../../base

patchesStrategicMerge:
  - patch_replicas.yaml
  - patch_image.yaml

namespace: prod-ns

namePrefix: prod-

configMapGenerator:
  - name: app-config
    literals:
      - ENV=production

关键字段说明：

• resources：直接引用的 YAML 文件或目录。
• bases：引用的 Base 目录（v1beta1 中推荐改用 resources）。
• patchesStrategicMerge / patchesJson6902：Patch 文件列表。
• namespace：为所有资源设置命名空间。
• namePrefix / nameSuffix：批量修改资源名称。
• configMapGenerator / secretGenerator：动态生成 ConfigMap 和 Secret。

2.6 工作原理：kustomize build 的执行流程

当执行 kustomize build overlays/prod 时，Kustomize 引擎按以下步骤工作：

1. 解析入口：读取 overlays/prod/kustomization.yaml。
2. 加载 Base：根据 bases 或 resources 字段，递归加载所有 Base 资源。
3. 应用全局修改：执行 namespace、namePrefix、nameSuffix、commonLabels、commonAnnotations 等全局字段。
4. 应用 Patch：按顺序执行 patchesStrategicMerge 和 patchesJson6902，对目标资源进行增量修改。
5. 生成资源：执行 configMapGenerator、secretGenerator 等生成器。
6. 输出最终 YAML：将所有处理后的资源合并输出到 stdout。

2.7 多集群场景下的特殊考量

在多集群环境中，Overlay 的粒度需要进一步细化：

• 集群级 Overlay：每个集群一个 Overlay 目录（如 overlays/cluster-a/、overlays/cluster-b/），包含该集群特有的 Patch 和资源。
• 环境级 Overlay：在集群 Overlay 之上再叠加环境 Overlay（如 overlays/cluster-a/prod/），形成多层叠加结构。
• 准入策略差异：不同集群可能启用不同的准入控制器（如 OPA/Gatekeeper、Kyverno），Patch 必须与准入策略兼容，否则 kustomize build 虽能通过，但 kubectl apply 会被拒绝。