2. Kustomize 基础概念：kustomization.yaml、resources、patches、configMapGenerator、secretGenerator

Kustomize 是 Kubernetes 生态中原生的配置管理工具，它通过声明式的方式对 YAML 资源进行继承、覆盖和生成，避免了模板化方案（如 Helm 的 Go Template）带来的复杂语法和调试困难。其核心思想是“以原生的 YAML 为基准，通过叠加层（overlay）实现环境差异”。本章将深入剖析 Kustomize 的五大核心概念，为后续的多环境配置与蓝绿发布参数调优打下坚实基础。

2.1 kustomization.yaml：配置的入口与心脏

kustomization.yaml 是 Kustomize 工作的唯一入口文件。Kustomize 不会直接读取目录下的所有 YAML，而是通过该文件声明需要处理哪些资源、应用哪些补丁、生成哪些 ConfigMap 或 Secret。一个典型的 kustomization.yaml 结构如下：

apiVersion: kustomize.config.k8s.io/v1beta1
kind: Kustomization

# 声明基础资源
resources:
  - deployment.yaml
  - service.yaml

# 声明补丁
patches:
  - path: patch_replicas.yaml
    target:
      kind: Deployment
      name: my-app

# 声明 ConfigMap 生成
configMapGenerator:
  - name: app-config
    literals:
      - APP_ENV=production
      - LOG_LEVEL=info

# 声明 Secret 生成
secretGenerator:
  - name: db-credentials
    literals:
      - DB_PASSWORD=supersecret
关键认知：Kustomize 不修改原始 YAML 文件，而是通过 kustomization.yaml 构建一个“叠加后的最终资源集”。原始文件始终保持干净，便于版本管理和审计。

2.2 resources：声明式资源清单

resources 字段用于列出所有需要纳入 Kustomize 管理的 Kubernetes 资源文件。这些文件可以是 Deployment、Service、Ingress、Namespace 等任何原生资源。Kustomize 会按照声明顺序读取并合并它们。

资源类型 常见文件 说明
工作负载 deployment.yaml, statefulset.yaml 定义 Pod 的副本数、镜像、资源限制等
网络 service.yaml, ingress.yaml 定义服务暴露方式与流量路由规则
配置 configmap.yaml, secret.yaml 定义应用运行时所需的配置与敏感数据
权限 rbac.yaml, serviceaccount.yaml 定义服务账户与角色绑定

最佳实践：将基础资源放在 base/ 目录下，环境特定的资源放在 overlays/ 目录下。例如：

project/
├── base/
│   ├── kustomization.yaml
│   ├── deployment.yaml
│   └── service.yaml
└── overlays/
    ├── production/
    │   ├── kustomization.yaml
    │   └── patch_replicas.yaml
    └── staging/
        ├── kustomization.yaml
        └── patch_env.yaml

2.3 patches：精准覆盖与增量修改

patches 是 Kustomize 实现环境差异化的核心机制。它允许你针对特定资源（如 Deployment 的 replicas、Service 的 type）进行局部修改，而无需复制整个 YAML 文件。Kustomize 支持两种补丁策略：Strategic Merge Patch 和 JSON Patch。

2.3.1 Strategic Merge Patch（推荐）

这是 Kustomize 的默认补丁方式，基于 Kubernetes 原生的合并策略。它通过 patches 字段指定目标资源，然后使用标准的 YAML 片段进行覆盖。

# overlays/production/patch_replicas.yaml
apiVersion: apps/v1
kind: Deployment
metadata:
  name: my-app
spec:
  replicas: 5

# overlays/production/kustomization.yaml
apiVersion: kustomize.config.k8s.io/v1beta1
kind: Kustomization
resources:
  - ../../base
patches:
  - path: patch_replicas.yaml
    target:
      kind: Deployment
      name: my-app

2.3.2 JSON Patch（精确控制）

当需要更精细的操作（如替换、添加、删除数组中的某个元素）时，可以使用 JSON Patch 语法。它通过 patchesJson6902 字段声明。

# overlays/production/kustomization.yaml
patchesJson6902:
  - target:
      version: v1
      kind: Deployment
      name: my-app
    patch:
      - op: replace
        path: /spec/replicas
        value: 5
      - op: add
        path: /spec/template/spec/containers/0/env/-
        value:
          name: ENV
          value: production
避坑提示：Strategic Merge Patch 对数组的处理是“替换整个数组”，而 JSON Patch 可以精确操作数组中的某个元素。当需要修改容器环境变量、端口列表等数组字段时，优先考虑 JSON Patch 或使用 patchesStrategicMerge 配合 $patch: delete 指令。

2.4 configMapGenerator：声明式 ConfigMap 生成

configMapGenerator 允许你从字面量、文件或环境文件声明式地生成 ConfigMap，而无需手动编写 ConfigMap YAML。Kustomize 会自动为生成的 ConfigMap 添加哈希后缀，当内容变化时触发 Pod 滚动更新。

数据来源 语法示例 适用场景
字面量 literals: [KEY=VALUE] 简单的环境变量，如 APP_ENV=production
文件 files: [path/to/file] 配置文件（如 nginx.conf、application.yml）
环境文件 envs: [path/to/.env] 从 .env 文件批量导入键值对 
# 从字面量生成
configMapGenerator:
  - name: app-config
    literals:
      - APP_ENV=production
      - LOG_LEVEL=info

# 从文件生成
configMapGenerator:
  - name: nginx-config
    files:
      - nginx.conf

# 从环境文件生成
configMapGenerator:
  - name: db-config
    envs:
      - .env.db
滚动更新机制：当 ConfigMap 内容变化时，Kustomize 会生成新的哈希后缀（如 app-config-7h4f8k2m），并自动更新引用该 ConfigMap 的 Deployment 的卷挂载或环境变量引用，触发 Pod 滚动更新。这是 Kustomize 相比手动管理 ConfigMap 的核心优势。

2.5 secretGenerator：安全声明式 Secret 生成

secretGenerator 与 configMapGenerator 类似，但专门用于处理敏感数据。它同样支持字面量、文件和环境文件三种来源，并且 Kustomize 会自动对 Secret 数据进行 Base64 编码。

# 从字面量生成 Secret
secretGenerator:
  - name: db-credentials
    literals:
      - DB_USER=admin
      - DB_PASSWORD=supersecret

# 从文件生成 Secret（文件内容会被 Base64 编码）
secretGenerator:
  - name: tls-cert
    files:
      - tls.crt
      - tls.key

# 从环境文件生成 Secret
secretGenerator:
  - name: s
    envs:
      - .env.api
安全注意事项：虽然 Kustomize 会自动编码 Secret 数据，但 literals 和 envs 中的明文密码仍会出现在 kustomization.yaml 中。生产环境中应避免将明文密码提交到 Git 仓库，建议使用外部密钥管理服务（如 Vault、AWS Secrets Manager）或通过 CI/CD 管道注入。

2.6 核心概念关系图

下图展示了 Kustomize 五大核心概念之间的协作关系：

Kustomize 核心概念关系图 Kustomize 核心概念关系图 kustomization.yaml resources patches configMapGenerator secretGenerator 最终资源集 声明基础资源 增量覆盖 生成 ConfigMap 生成 Secret 合并输出

2.7 核心概念对比总结

概念 核心作用 数据来源 是否触发滚动更新 典型使用场景
kustomization.yaml 配置入口，声明所有操作 手动编写 — 所有 Kustomize 项目的根文件
resources 声明基础资源文件 YAML 文件路径 否 定义 Deployment、Service 等核心资源
patches 对已有资源进行局部覆盖 YAML 片段或 JSON Patch 是（如果修改了 Pod 模板） 环境差异化（如副本数、镜像标签）
configMapGenerator 声明式生成 ConfigMap 字面量、文件、环境文件 是（哈希后缀变化） 应用配置、日志级别、环境变量
secretGenerator 声明式生成 Secret 字面量、文件、环境文件 是（哈希后缀变化） 数据库密码、、TLS 证书

2.8 实战案例：组合使用五大概念

以下是一个完整的 kustomization.yaml 示例，展示了如何组合使用所有核心概念来管理一个微服务应用：

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

resources:
  - deployment.yaml
  - service.yaml
  - ingress.yaml

configMapGenerator:
  - name: app-config
    literals:
      - APP_ENV=base
      - LOG_LEVEL=debug

secretGenerator:
  - name: db-credentials
    literals:
      - DB_USER=dev_user
      - DB_PASSWORD=dev_pass

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

resources:
  - ../../base

patches:
  - path: patch_replicas.yaml
    target:
      kind: Deployment
      name: my-app
  - path: patch_env.yaml
    target:
      kind: Deployment
      name: my-app

configMapGenerator:
  - name: app-config
    behavior: merge
    literals:
      - APP_ENV=production
      - LOG_LEVEL=info

secretGenerator:
  - name: db-credentials
    behavior: replace
    literals:
      - DB_USER=prod_admin
      - DB_PASSWORD=prod_secret_2024
关键技巧：使用 behavior: merge 可以合并 ConfigMap 的键值对（新增或覆盖），而 behavior: replace 则会完全替换整个 Secret。在蓝绿发布场景中，通常使用 merge 来覆盖环境特定的配置，保持基础配置不变。
← 上一章 📖 返回目录 下一章 →