📚 课程目录第2章 Kustomize基础回顾

Kustomize 基础回顾：核心概念

Kustomize 是 Kubernetes 生态中原生的配置管理工具，它通过声明式的方式对 Kubernetes 资源进行定制和复用，无需模板语言或 Helm Chart。其核心思想是“基准 + 叠加”，即维护一份基准资源，再通过叠加层进行环境差异化定制。本章将系统回顾 Kustomize 的四大核心概念：kustomization.yaml、资源叠加、Patches 以及 ConfigMapGenerator。

  📌 核心要点：Kustomize 不修改原始 YAML，而是通过声明式叠加层生成最终资源，天然适合 GitOps 工作流。

2.1 kustomization.yaml：Kustomize 的入口文件

kustomization.yaml 是 Kustomize 项目的核心配置文件，它定义了资源来源、定制规则和生成器配置。Kustomize 通过读取该文件来构建最终的 Kubernetes 资源清单。

字段	说明	示例
`apiVersion`	Kustomize 配置版本，当前稳定版为 `kustomize.config.k8s.io/v1beta1`	`kustomize.config.k8s.io/v1beta1`
`kind`	固定为 `Kustomization`	`Kustomization`
`resources`	引用的基准资源文件或目录列表	`["deployment.yaml", "service.yaml"]`
`bases`	（旧版）引用其他 Kustomize 目录作为基准	`["../base"]`
`patches`	对资源进行覆盖或合并的补丁列表	`patchesStrategicMerge` / `patchesJson6902`
`configMapGenerator`	从文件或字面值生成 ConfigMap 的声明式配置	`[{"name": "app-config", "files": ["config.properties"]}]`
`secretGenerator`	从文件或字面值生成 Secret 的声明式配置	`[{"name": "db-secret", "literals": ["password=123"]}]`
`namespace`	为所有资源设置目标命名空间	`production`
`namePrefix` / `nameSuffix`	为所有资源名称添加前缀或后缀	`prod-`
`commonLabels` / `commonAnnotations`	为所有资源添加公共标签或注解	`{"env": "prod"}`

💡 最佳实践：始终使用 apiVersion: kustomize.config.k8s.io/v1beta1，它支持所有现代特性，包括 components 和 helmCharts。

2.2 资源叠加：基准与环境的分离

资源叠加是 Kustomize 最核心的设计模式。它通过“基准（base）”和“叠加（overlay）”两层结构，实现资源复用与环境差异化。

基准层（base）：存放通用的、与环境无关的资源定义，如 Deployment、Service、ConfigMap 等。
叠加层（overlay）：针对不同环境（dev、staging、prod）进行定制，通过 kustomization.yaml 引用基准层并应用补丁。

# 目录结构示例
project/
├── base/
│   ├── kustomization.yaml
│   ├── deployment.yaml
│   └── service.yaml
└── overlays/
    ├── dev/
    │   └── kustomization.yaml
    ├── staging/
    │   └── kustomization.yaml
    └── prod/
        └── kustomization.yaml

# base/kustomization.yaml
apiVersion: kustomize.config.k8s.io/v1beta1
kind: Kustomization
resources:
  - deployment.yaml
  - service.yaml

# overlays/prod/kustomization.yaml
apiVersion: kustomize.config.k8s.io/v1beta1
kind: Kustomization
resources:
  - ../../base
patches:
  - path: replica-patch.yaml
namespace: production
namePrefix: prod-

2.3 Patches：精准定制资源

Patches 是 Kustomize 实现资源定制的核心机制，它允许在不修改原始 YAML 文件的前提下，对资源进行覆盖、合并或删除操作。Kustomize 支持两种补丁策略：Strategic Merge Patch 和 JSON Patch (JSON 6902)。

补丁类型	语法	适用场景	示例
Strategic Merge Patch	部分 YAML 片段，通过 `patchesStrategicMerge` 引用	覆盖或合并字段，支持列表合并策略（如 `$patch: delete`）	修改副本数、添加环境变量
JSON Patch (JSON 6902)	操作数组，通过 `patchesJson6902` 引用	精确的增、删、改操作，适用于复杂路径	删除特定容器、修改镜像标签

# Strategic Merge Patch 示例：修改副本数
# overlays/prod/replica-patch.yaml
apiVersion: apps/v1
kind: Deployment
metadata:
  name: my-app
spec:
  replicas: 5

# JSON Patch 示例：修改镜像标签
# overlays/prod/image-patch.yaml
- op: replace
  path: /spec/template/spec/containers/0/image
  value: my-app:v2.0.0

# overlays/prod/kustomization.yaml 引用补丁
apiVersion: kustomize.config.k8s.io/v1beta1
kind: Kustomization
resources:
  - ../../base
patchesStrategicMerge:
  - replica-patch.yaml
patchesJson6902:
  - target:
      group: apps
      version: v1
      kind: Deployment
      name: my-app
    path: image-patch.yaml

⚠️ 常见陷阱：Strategic Merge Patch 对列表字段的合并行为取决于目标资源的 patchStrategy 注解。如果遇到列表被替换而非合并，请检查目标资源是否支持 merge 策略，或改用 JSON Patch。

2.4 ConfigMapGenerator：声明式生成 ConfigMap

configMapGenerator 是 Kustomize 内置的生成器，它允许从文件、字面值或环境文件声明式地生成 ConfigMap。生成的 ConfigMap 会自动添加内容哈希后缀，当内容变化时触发 Pod 滚动更新。

# 从文件生成 ConfigMap
apiVersion: kustomize.config.k8s.io/v1beta1
kind: Kustomization
configMapGenerator:
  - name: app-config
    files:
      - config.properties
      - app.yml
    literals:
      - APP_ENV=production
      - LOG_LEVEL=info

# 从环境文件生成 ConfigMap
configMapGenerator:
  - name: env-config
    envs:
      - .env.production

# 生成的 ConfigMap 名称示例
# app-config-7c55f5d4b5  (自动添加内容哈希)

2.5 核心概念对比总结

概念	作用	关键字段	典型用例
kustomization.yaml	项目入口，声明资源来源和定制规则	`resources`, `patches`, `namespace`	定义整个 Kustomize 项目的配置
资源叠加	基准与环境的分离，实现复用	`resources` 引用 base	多环境（dev/staging/prod）差异化部署
Patches	对资源进行精准定制	`patchesStrategicMerge`, `patchesJson6902`	修改副本数、镜像版本、环境变量
ConfigMapGenerator	声明式生成 ConfigMap，自动哈希	`configMapGenerator`	管理配置文件，触发滚动更新

  📖 本章小结：Kustomize 通过 kustomization.yaml 作为统一入口，利用资源叠加实现基准与环境的分离，通过 Patches 进行精准定制，借助 ConfigMapGenerator 实现配置的声明式管理和自动滚动更新。这些核心概念构成了 Kustomize 插件扩展与控制平面准入策略联动的基础。