Kustomize 现代化使用教程与最佳实践
为什么选择 Kustomize?
Kustomize 是 Kubernetes 原生的配置管理工具(自 k8s 1.14 起内置于 kubectl)。与 Helm 的模板引擎(Template)不同,Kustomize 采用 Overlay(叠加) 的机制。
无模板(Template-free):不需要学习复杂的模板语法(如 Go Template),直接操作原生的 YAML。
声明式(Declarative):所有的修改都通过 YAML 文件声明,非常适合 GitOps 工作流。
基础与覆盖(Base & Overlay):维护一份基础配置(Base),通过补丁(Overlay)派生出开发、测试、生产等不同环境。
核心概念与目录结构
一个符合现代最佳实践的 Kustomize 项目结构如下:
1 | ~/my-project |
基础层(Base)配置
我们在 base 目录中定义所有环境共用的资源。
准备资源文件
base/app/deployment.yaml
1 | apiVersion: apps/v1 |
base/app/service.yaml
1 | apiVersion: v1 |
编写 Base 的 kustomization.yaml
注意:在旧版本中常使用 commonLabels,但在新版本中推荐使用更灵活的 labels 字段。
base/app/kustomization.yaml
1 | apiVersion: kustomize.config.k8s.io/v1beta1 |
覆盖层(Overlay)与多环境管理
在 overlays 目录中,我们引用 base 并进行环境特定的修改。
开发环境 (Dev)
Dev 环境通常需要:添加后缀、修改副本数、开启调试变量。
注意:旧版本使用 bases 引用上层目录,新版本(v2.1.0+)已废弃 bases,统一使用 resources 引用目录。
overlays/dev/app/kustomization.yaml
1 | apiVersion: kustomize.config.k8s.io/v1beta1 |
overlays/dev/app/patch-replicas.yaml
1 | apiVersion: apps/v1 |
生产环境 (Prod)
Prod 环境通常需要:资源限制(CPU/Mem)、更高的副本数、ConfigMap/Secret 管理。
overlays/prod/app/config.properties
1 | xxx=xxx |
overlays/prod/app/secret.env
1 | xxx=xxx |
overlays/prod/app/kustomization.yaml
1 | apiVersion: kustomize.config.k8s.io/v1beta1 |
常用命令与工作流
kubectl kustomize (功能单一)
kubectl 仅集成了 Kustomize 的 Build(构建) 功能。它没有复杂的子命令,基本只用于将 Kustomize 配置文件转换成标准的 Kubernetes YAML。
| 指令 | 说明 |
|---|---|
kubectl kustomize <dir> | 核心指令:读取指定目录的 kustomization.yaml 并输出渲染后的资源到终端。 |
kubectl apply -k <dir> | 常用扩展:直接构建并应用到集群(这是最常用的方式)。 |
kubectl delete -k <dir> | 根据 Kustomize 配置批量删除集群中的资源。 |
kubectl diff -k <dir> | 对比本地 Kustomize 渲染结果与集群运行中资源的差异。 |
kustomize (独立 CLI,功能丰富)
独立版工具将功能划分为几个大类,支持对配置文件进行增删改查。
核心构建 (Build)
kustomize build <dir>: 最基础指令,等同于kubectl kustomize <dir>。支持更多参数(如--enable-alpha-plugins)。
编辑指令 (Edit) - kubectl 不支持
这是独立版最强大的地方,允许你通过命令行直接修改 kustomization.yaml 文件。
kustomize edit add resource <file>: 向配置中添加资源文件。kustomize edit set image <name=newimage:tag>: 修改镜像名称或版本。kustomize edit set namespace <name>: 修改全局命名空间。kustomize edit add configmap <name> --from-file=<path>: 快速添加 ConfigMap 生成器。kustomize edit set label <key:value>: 批量添加标签。
初始化与创建 (Create/Completion)
kustomize create: 在当前目录自动创建一个初始化的kustomization.yaml。kustomize completion: 生成 Bash/Zsh 的命令行自动补全脚本。
查看与格式化 (Fn/Inspect)
kustomize fn: 运行 KRM 函数(高级特性,用于处理资源树)。
核心指令映射表
如果习惯了 kubectl,想转到 kustomize 独立工具,可以参考这个映射:
| 目标操作 | kubectl 命令 | kustomize 独立命令 |
|---|---|---|
| 查看渲染结果 | kubectl kustomize ./overlays/dev | kustomize build ./overlays/dev |
| 修改镜像版本 | 手动改 YAML | kustomize edit set image myapp=v2.0 |
| 添加新文件 | 手动改 YAML | kustomize edit add resource service.yaml |
| 初始化目录 | 手动创建文件 | kustomize create --autodetect |
总结
Kustomize 的核心哲学是复用与叠加。通过上述结构:
Base 保持了应用最纯净的定义。
Overlays 明确地管理了环境差异。
kubectl apply -k 简化了部署流程。
这种方式完全符合 GitOps 的理念:将环境差异代码化,每一次变更都可追踪、可回滚。
参考:
