📚 课程目录第2章 Kustomize 基础

Kustomize资源配额配置与RBAC权限审计 - 第2节

2.1 Kustomize 是什么

Kustomize 是 Kubernetes 生态中原生的配置管理工具，于 2018 年由 Google 开源，随后在 2019 年合并入 kubectl 成为其子命令（kubectl apply -k）。它采用 声明式覆盖（Declarative Overlay） 模式，允许用户在不修改原始 YAML 文件的前提下，通过分层叠加的方式生成环境特定的 Kubernetes 资源清单。

  核心设计理念：Kustomize 不是模板引擎，它直接操作 YAML 结构，通过补丁（Patch）、名称前缀/后缀、标签注入、镜像替换等机制实现配置复用。所有输入和输出都是标准的 Kubernetes YAML，无需学习额外的模板语法。

Kustomize 的工作流程可概括为：Base（基准）→ Overlay（覆盖）→ 渲染输出。Base 目录存放通用的资源定义，Overlay 目录存放针对不同环境（开发、测试、生产）的差异化配置，最终通过 kustomize build 命令合并生成完整的资源清单。

2.2 Kustomize 与 Helm 的对比

Helm 和 Kustomize 是 Kubernetes 配置管理领域最主流的两个工具，但设计哲学截然不同。Helm 采用 模板驱动（Template-Driven） 模式，通过 Go 模板语法和 Values 文件生成配置；Kustomize 则坚持 原生 YAML 覆盖（Native YAML Overlay） 模式。以下从多个维度进行对比：

对比维度	Kustomize	Helm
设计哲学	声明式覆盖，不修改原始 YAML	模板引擎，通过 Values 注入变量
学习曲线	低，只需掌握 YAML 和少量指令	中高，需学习 Go 模板语法和 Chart 结构
配置复用	通过 Base + Overlay 分层复用	通过 Chart 依赖和子 Chart 复用
变量管理	无变量概念，使用补丁和替换	Values.yaml 集中管理变量
版本管理	依赖 Git 版本控制	Chart 版本 + App 版本双版本机制
回滚机制	Git 回滚 + kubectl apply 回退	Helm rollback 内置回滚
与 kubectl 集成	原生集成（kubectl apply -k）	需额外安装 Helm CLI
复杂应用交付	适合简单到中等复杂度	适合复杂应用和生命周期管理
GitOps 适配性	天然适配，纯 YAML 无模板	需配合 Helm Operator 或 Flux

选型建议：如果你的团队追求极简、原生、GitOps 优先，且应用配置复杂度不高，Kustomize 是更轻量的选择。如果需要管理有状态应用、复杂依赖、生命周期钩子或需要 Chart 仓库分发，Helm 更合适。实践中，许多团队将两者结合使用——Helm 管理第三方 Chart，Kustomize 管理自研应用的配置覆盖。

2.3 kustomization.yaml 基础结构

kustomization.yaml 是 Kustomize 的入口配置文件，它告诉 Kustomize 如何构建最终的 Kubernetes 资源清单。一个典型的 kustomization.yaml 文件包含以下核心字段：

2.3.1 最小化 kustomization.yaml 示例

# 最小化 kustomization.yaml
apiVersion: kustomize.config.k8s.io/v1beta1
kind: Kustomization

# 指定要管理的资源文件列表
resources:
  - deployment.yaml
  - service.yaml
  - configmap.yaml

# 为所有资源添加名称前缀
namePrefix: prod-

# 为所有资源添加公共标签
commonLabels:
  app: my-app
  env: production

# 为所有资源添加公共注解
commonAnnotations:
  managed-by: kustomize
  team: platform

2.3.2 核心字段详解

字段	类型	说明	示例
`apiVersion`	string	Kustomize API 版本，固定为 `kustomize.config.k8s.io/v1beta1`	`kustomize.config.k8s.io/v1beta1`
`kind`	string	固定为 `Kustomization`	`Kustomization`
`resources`	[]string	引用的 Kubernetes 资源文件路径列表	`["deployment.yaml", "service.yaml"]`
`namePrefix`	string	为所有资源名称添加前缀，避免环境间冲突	`staging-`
`nameSuffix`	string	为所有资源名称添加后缀	`-v2`
`commonLabels`	map[string]string	为所有资源注入公共标签，同时注入 Selector	`app: my-app`
`commonAnnotations`	map[string]string	为所有资源注入公共注解	`version: 1.0.0`
`patches`	[]Patch	对资源进行局部覆盖或修改（核心能力）	见下方示例
`images`	[]Image	批量替换容器镜像名称和标签	`name: nginx newTag: 1.25`
`configMapGenerator`	[]ConfigMapArgs	从文件或字面量生成 ConfigMap	`name: app-config files: ["config.properties"]`
`secretGenerator`	[]SecretArgs	从文件或字面量生成 Secret	`name: db-secret literals: ["password=123"]`

2.3.3 补丁（Patches）—— Kustomize 的核心能力

补丁是 Kustomize 实现配置覆盖的核心机制，支持两种补丁策略：

Strategic Merge Patch（策略合并补丁）：基于 Kubernetes 原生合并策略，按路径覆盖字段，支持数组合并。
JSON Patch（JSON 补丁）：遵循 RFC 6902 标准，通过 op（操作）、path（路径）、value（值）进行精确修改。

# patches 字段示例：使用 Strategic Merge Patch 修改 Deployment 副本数
patches:
  - target:
      kind: Deployment
      name: my-app
    patch: |-
      - op: replace
        path: /spec/replicas
        value: 5

# 或者使用 patchesStrategicMerge（更简洁的写法）
patchesStrategicMerge:
  - patch |-
    apiVersion: apps/v1
    kind: Deployment
    metadata:
      name: my-app
    spec:
      replicas: 5

2.3.4 完整的 kustomization.yaml 结构

# 完整示例：生产环境 kustomization.yaml
apiVersion: kustomize.config.k8s.io/v1beta1
kind: Kustomization

# 基准配置引用
resources:
  - ../../base

# 环境标识
namePrefix: prod-
commonLabels:
  app: my-app
  env: production
  managed-by: kustomize

# 镜像替换
images:
  - name: my-app-image
    newName: registry.example.com/my-app
    newTag: v1.2.3

# 补丁：调整副本数和资源限制
patches:
  - target:
      kind: Deployment
      name: my-app
    patch: |-
      - op: replace
        path: /spec/replicas
        value: 5
      - op: replace
        path: /spec/template/spec/containers/0/resources/limits/cpu
        value: "2"
      - op: replace
        path: /spec/template/spec/containers/0/resources/limits/memory
        value: "4Gi"

# 生成 ConfigMap
configMapGenerator:
  - name: app-config
    files:
      - configs/prod.properties
    literals:
      - LOG_LEVEL=info
      - CACHE_TTL=3600

# 生成 Secret
secretGenerator:
  - name: db-secret
    literals:
      - DB_PASSWORD=prod-secret-password
    type: Opaque

2.3.5 目录结构最佳实践

在实际项目中，推荐按以下目录结构组织 Kustomize 配置：

project-root/
├── base/                          # 基准配置目录
│   ├── kustomization.yaml         # 基准 kustomization
│   ├── deployment.yaml            # 通用 Deployment
│   ├── service.yaml               # 通用 Service
│   └── configmap.yaml             # 通用 ConfigMap
├── overlays/                      # 覆盖配置目录
│   ├── development/               # 开发环境
│   │   ├── kustomization.yaml     # 引用 ../../base
│   │   ├── patch-replicas.yaml    # 副本数补丁
│   │   └── configmap-dev.yaml     # 开发环境 ConfigMap
│   ├── staging/                   # 预发布环境
│   │   ├── kustomization.yaml
│   │   ├── patch-resources.yaml
│   │   └── configmap-staging.yaml
│   └── production/                # 生产环境
│       ├── kustomization.yaml
│       ├── patch-hpa.yaml
│       ├── patch-ingress.yaml
│       └── configmap-prod.yaml
└── README.md

常见陷阱：

不要在 kustomization.yaml 中直接嵌入大量 YAML 内容，应通过 resources 字段引用外部文件。
注意 commonLabels 会自动注入到 Selector 中，可能导致 Service 选择器与 Deployment 标签不匹配，需提前规划标签策略。
避免在 Base 层使用 namePrefix，该字段应仅在 Overlay 层使用，否则会导致 Base 层资源名称被污染。
补丁顺序：多个补丁按声明顺序依次应用，后声明的补丁会覆盖先声明的补丁。

2.4 本章小结

Kustomize 通过 Base + Overlay 的分层设计，实现了 Kubernetes 配置的声明式复用与差异化覆盖。与 Helm 的模板驱动模式相比，Kustomize 更贴近原生 YAML 生态，学习成本更低，特别适合 GitOps 工作流。掌握 kustomization.yaml 的核心字段（resources、namePrefix、commonLabels、patches、images、configMapGenerator）是使用 Kustomize 的基础，而补丁机制则是实现精细化配置覆盖的关键能力。