📚 课程目录第3章多集群环境下的Kustomize配置策略

3. 多集群环境下的 Kustomize 配置策略：如何通过 Kustomize 管理 dev/staging/prod 等不同集群的差异化配置

在多集群架构中，每个环境（dev、staging、prod）通常运行在独立的 Kubernetes 集群上，且具有不同的资源规格、副本数、命名空间、镜像标签以及准入策略。Kustomize 通过 overlay 模式天然支持这种场景：将公共基准（base）与各环境差异（overlay）分离，避免重复维护 YAML。

3.1 核心策略：Base + Overlay 分层模型

Kustomize 的多集群管理遵循“基准统一、环境叠加”的原则。每个环境目录下维护一个 kustomization.yaml，通过 resources 引用 base，并通过 patches、namePrefix、namespace 等字段注入差异化配置。

  关键原则：Base 只包含跨环境通用的资源定义（如 Deployment 模板、Service 类型）；所有与环境相关的差异（副本数、镜像版本、资源限制、准入策略）必须放在 overlay 层，严禁在 base 中硬编码环境特定值。

3.2 差异化配置清单与实现方式

下表列出了多集群场景下最常见的差异化配置项及其在 Kustomize 中的推荐实现方式：

配置项	典型差异（dev / staging / prod）	Kustomize 实现方式
副本数	1 / 3 / 5	`patchesStrategicMerge` 修改 `spec.replicas`
镜像标签	v1.0-dev / v1.0-rc / v1.0	`images` 字段或 `patchesJson6902`
命名空间	app-dev / app-staging / app-prod	`namespace` 字段
资源限制	无限制 / 中等 / 严格	`patchesStrategicMerge` 覆盖 `resources`
准入策略	宽松 / 中等 / 严格	overlay 层引入独立的 `ValidatingWebhookConfiguration` 或 `Kyverno ClusterPolicy`
环境变量	LOG_LEVEL: debug / info / warn	`configMapGenerator` + `patches`
Ingress 域名	dev.example.com / staging.example.com / example.com	`patchesStrategicMerge` 修改 `spec.rules.host`

3.3 典型 overlay 配置示例

以下展示一个生产环境 overlay 的 kustomization.yaml 文件，它通过引用 base 并叠加差异来生成最终资源：

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

# 引用基准层
resources:
  - ../../base

# 设置命名空间
namespace: app-prod

# 设置名称前缀，避免跨环境资源冲突
namePrefix: prod-

# 通用标签
commonLabels:
  environment: production
  team: platform

# 镜像覆盖
images:
  - name: my-app
    newName: registry.example.com/my-app
    newTag: v1.0.0

# 补丁：修改副本数和资源限制
patchesStrategicMerge:
  - patch_deployment.yaml
  - patch_hpa.yaml

# 补丁：修改 Ingress 域名
patchesJson6902:
  - target:
      group: networking.k8s.io
      version: v1
      kind: Ingress
      name: my-ingress
    patch: |-
      - op: replace
        path: /spec/rules/0/host
        value: "app.example.com"

# 生成 ConfigMap（环境特定配置）
configMapGenerator:
  - name: app-config
    literals:
      - LOG_LEVEL=warn
      - DB_POOL_SIZE=20

最佳实践：对于准入策略的差异化，建议在 overlay 层通过 resources 字段直接引入环境特定的 ValidatingWebhookConfiguration 或 Kyverno ClusterPolicy 文件，而不是在 base 中定义后通过补丁修改。这样可以保持策略文件的完整性和可读性。

3.4 多集群部署流程与故障预防

使用 Kustomize 管理多集群配置时，推荐遵循以下部署流程，以提前发现准入策略冲突：

本地验证：在每个 overlay 目录下执行 kustomize build，检查输出 YAML 是否符合预期。
Dry-run 检查：使用 kubectl apply --dry-run=server -k overlays/prod/ 在目标集群上进行服务端试运行，触发准入 Webhook 验证。
差异对比：使用 kustomize build overlays/dev/ > dev.yaml && kustomize build overlays/prod/ > prod.yaml && diff dev.yaml prod.yaml 确认环境间差异。
CI/CD 集成：在流水线中增加 kustomize build 步骤，并将输出与基线版本进行 Schema 校验。

常见故障点：当 overlay 层通过 patchesStrategicMerge 修改了 base 中定义的准入策略资源（如 PodDisruptionBudget 或 NetworkPolicy）时，如果补丁格式不正确或字段路径不匹配，Kustomize 会静默跳过补丁，导致实际生效的策略与预期不符。务必在 CI 中增加 kustomize build 输出的结构化对比。

3.5 多集群配置策略总结

策略维度	推荐做法	避免做法
基准管理	base 只包含跨环境通用模板	在 base 中硬编码环境特定值
差异覆盖	优先使用 `patchesStrategicMerge` 和 `images` 字段	大量使用 `patchesJson6902` 导致可读性下降
准入策略	每个 overlay 独立引入策略文件	在 base 中定义策略后通过补丁修改
命名隔离	使用 `namePrefix` 和 `namespace` 避免跨环境冲突	依赖手动修改资源名称
验证流程	CI 中执行 `kustomize build` + dry-run	直接 apply 到集群后再排查

通过上述 Base + Overlay 分层策略，团队可以在保持 YAML 声明式一致性的同时，灵活管理 dev/staging/prod 等不同集群的差异化配置，并有效降低因配置错误导致的准入策略故障。