1. 课程导论与故障排查全景
在多集群架构成为企业级 Kubernetes 基础设施标配的今天，Kustomize 凭借其纯声明式、无模板、原生集成的特性，已成为管理多环境（开发、预发、生产）与多集群配置差异的事实标准。然而，当 Kustomize 与 准入策略（Admission Policy） 结合时，配置的叠加、覆盖与策略校验之间常常产生隐蔽的冲突，导致资源被拒绝、策略误判或集群状态不一致。
本章作为课程的开篇，旨在建立 Kustomize 在多集群环境中的角色认知，并给出 准入策略故障排查的总体方法论，为后续各章节的深入排查打下结构化基础。
1.1 Kustomize 在多集群环境中的核心角色
Kustomize 通过 kustomization.yaml 定义资源的 基准（Base） 与 覆盖（Overlay），实现配置的继承与差异化。在多集群场景下，其角色可归纳为以下三个维度：
| 角色维度 | 说明 | 典型场景 |
|---|---|---|
| 配置抽象层 | 将集群间公共配置抽取为 Base，集群特有配置作为 Overlay | 生产集群启用 HPA，开发集群不启用 |
| 策略注入点 | 通过 patches 或 transformers 注入准入策略所需的标签、注解或 Sidecar |
为所有工作负载注入 istio-injection: enabled 注解 |
| 资源生成器 | 结合 secretGenerator / configMapGenerator 生成策略依赖的配置数据 |
为 OPA/Gatekeeper 策略生成动态约束模板 |
关键认知： Kustomize 本身不执行准入策略校验，但它生成的最终 YAML 是准入 Webhook 的输入。因此，故障根因往往不在 Kustomize 语法错误，而在 渲染后的资源与策略预期之间的语义偏差。
1.2 准入策略故障的典型分类
基于大量生产案例，我们将 Kustomize 多集群场景下的准入策略故障归纳为以下四类：
- 配置覆盖冲突：Overlay 中的字段修改导致策略所依赖的标签/注解被意外覆盖或删除。
- 资源生成不一致：不同集群的
configMapGenerator生成内容不同，导致策略校验结果不一致。 - 策略模板与渲染结果不匹配：Kustomize 的变量替换（如
$(VAR)）未按预期展开，导致策略模板无法匹配实际资源。 - 多集群策略差异化遗漏：某个集群未应用特定的策略 Overlay，导致该集群绕过安全校验。
排查原则： 始终先确认
kustomize build 的输出是否符合预期，再检查准入策略本身。80% 的故障源于 Kustomize 渲染结果与策略假设之间的差异。
1.3 故障排查总体方法论
本课程采用 四阶段排查法，覆盖从问题发现到根因定位的完整链路：
- 阶段一：现象确认与范围界定 —— 确定故障集群、受影响资源、策略名称及错误信息。
- 阶段二：Kustomize 渲染审计 —— 使用
kustomize build --output对比不同集群的渲染结果，定位配置差异点。 - 阶段三：策略规则逆向验证 —— 将渲染后的资源手动输入策略引擎（如 OPA/kyverno）进行离线测试。
- 阶段四：多集群差异根因分析 —— 检查 Overlay 层级、变量替换、Generator 配置等 Kustomize 特有机制。
下图展示了这一排查流程的全景：
1.4 课程核心工具链
本课程将围绕以下工具链展开故障排查实战：
| 工具/组件 | 在排查中的角色 | 关键命令/接口 |
|---|---|---|
| kustomize | 渲染最终 YAML，提供配置差异对比基础 | kustomize build <overlay> |
| kubectl diff | 对比集群当前状态与 Kustomize 渲染结果 | kubectl diff -f rendered.yaml |
| OPA / Gatekeeper | 执行准入策略校验，返回拒绝原因 | kubectl get constrainttemplates |
| Kyverno | 策略引擎，支持集群策略与资源策略 | kubectl get clusterpolicy |
| kubectl-assert | 离线验证资源是否符合策略规则 | kubectl assert check -f resource.yaml |
常见误区： 不要直接在生产集群上修改准入策略来适配 Kustomize 输出。正确的做法是调整 Kustomize 的 Overlay 配置，使其生成符合策略预期的资源。策略是“契约”，Kustomize 是“配置生成器”，后者应适配前者。
1.5 本章小结
通过本章，您已建立以下核心认知：
- Kustomize 在多集群环境中是 配置抽象层 与 策略注入点，其渲染结果是准入策略的输入。
- 故障主要分为 配置覆盖冲突、资源生成不一致、策略模板不匹配 和 策略差异化遗漏 四类。
- 排查方法论遵循 四阶段递进：现象确认 → 渲染审计 → 策略验证 → 根因分析。
- 核心工具链包括 kustomize、kubectl diff、OPA/Gatekeeper、Kyverno 等。