19-Kustomize

Kustomize 是 Kubernetes 原生的配置管理工具，从 K8s 1.14 开始内置于 kubectl。与 Helm 的"模板化 + 参数化"不同，Kustomize 采用"基础 + 叠加（Base + Overlay）"模型——不引入模板语法，直接操作原始 YAML。本章覆盖 Kustomize 的分层设计、Patch 策略、多环境管理，以及与 Helm 的适用场景对比。

Base + Overlay 模型#

Kustomize 的核心思想：一份 base 配置 + N 份 overlay 覆盖差异，最终渲染出不同环境的 YAML。

标准目录结构#

text
k8s/
├── base/                          # 通用基础配置
│   ├── kustomization.yaml
│   ├── deployment.yaml
│   ├── service.yaml
│   └── hpa.yaml
├── components/                    # 可复用组件
│   ├── istio-sidecar/
│   │   └── kustomization.yaml
│   └── monitoring/
│       └── kustomization.yaml
└── overlays/                      # 环境级覆盖
    ├── qa/
    │   ├── kustomization.yaml
    │   └── patches/
    ├── staging/
    │   └── kustomization.yaml
    └── prod/
        ├── kustomization.yaml
        └── patches/

base/kustomization.yaml#

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

resources:
  - deployment.yaml
  - service.yaml
  - hpa.yaml

commonLabels:
  app.kubernetes.io/managed-by: kustomize

# 不在 base 里设置 namespace，留给 overlay

overlays/prod/kustomization.yaml#

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

namespace: production

resources:
  - ../../base

components:
  - ../../components/istio-sidecar
  - ../../components/monitoring

images:
  - name: my-service            # 必须完全匹配原始 image 字段
    newName: 123456789.dkr.ecr.us-west-2.amazonaws.com/my-service
    newTag: v1.2.3

patches:
  - path: patches/replicas.yaml
  - path: patches/resources.yaml

configMapGenerator:
  - name: app-config
    envs:
      - config.env

Patch 策略#

Kustomize 支持三种 Patch 方式，适用于不同场景。

Strategic Merge Patch（默认，推荐）#

按 K8s 资源的 merge key 智能合并，适合大多数场景。数组按 name 字段匹配元素：

yaml
# overlays/prod/patches/resources.yaml
apiVersion: apps/v1
kind: Deployment
metadata:
  name: my-service
spec:
  template:
    spec:
      containers:
        - name: app           # 通过 name 字段匹配容器
          resources:
            requests:
              cpu: "500m"
              memory: "512Mi"
            limits:
              cpu: "1000m"
              memory: "1Gi"

JSON Patch（精确操作）#

当需要精确的 add/remove/replace/move 操作时使用：

yaml
patches:
  - target:
      kind: Deployment
      name: my-service
    patch: |-
      - op: replace
        path: /spec/replicas
        value: 3
      - op: add
        path: /spec/template/spec/containers/0/env/-
        value:
          name: LOG_LEVEL
          value: info
      - op: remove
        path: /spec/template/spec/containers/0/resources/limits/cpu

选型指南#

场景	推荐	原因
修改/添加字段	Strategic Merge	更直观，自动合并
删除字段	JSON Patch (`op: remove`)	Strategic Merge 删除语法不直观
修改数组中特定元素	JSON Patch	可按索引精确定位
往数组追加元素	JSON Patch (`op: add`, `path: /-`)	Strategic Merge 可能替换整个数组
批量修改同类资源	Strategic Merge + target selector	简洁

Components 复用#

Components 是可选的 Kustomize 功能块，比 base 更灵活——可以被任意 overlay 按需引入：

yaml
# components/monitoring/kustomization.yaml
apiVersion: kustomize.config.k8s.io/v1alpha1   # 注意 alpha1
kind: Component

patches:
  - target:
      kind: Deployment
    patch: |-
      apiVersion: apps/v1
      kind: Deployment
      metadata:
        name: not-important     # Component 的 target 不需要精确名称
      spec:
        template:
          metadata:
            annotations:
              prometheus.io/scrape: "true"
              prometheus.io/port: "8080"
              prometheus.io/path: "/metrics"

yaml
# overlays/qa/kustomization.yaml
components:
  - ../../components/monitoring
  - ../../components/istio-sidecar

适用场景：Sidecar 注入（Istio、日志采集）、监控注解、资源限制策略、网络策略。

ConfigMap/Secret Generator#

ConfigMap Generator#

yaml
configMapGenerator:
  # 从 env 文件生成
  - name: app-config
    envs:
      - config.env           # KEY=VALUE 格式
  # 从文件生成
  - name: nginx-config
    files:
      - nginx.conf
  # 直接写 literals
  - name: feature-flags
    literals:
      - ENABLE_NEW_UI=true

Hash 后缀机制#

默认 ConfigMap/Secret 名称会追加内容 hash（如 app-config-2f8k9d），好处是内容变更 → 名称变更 → 触发 Pod 滚动更新，避免"改了 ConfigMap 但 Pod 没重启"的问题。

慎用禁用 hash：只在外部引用固定名称时使用 disableNameSuffixHash: true。

多环境配置管理#

用表格思维管理各环境差异，然后映射到 patches：

text
| 配置项       | QA        | Staging   | Prod      |
|-------------|-----------|-----------|-----------|
| replicas    | 1         | 2         | 3-10(HPA) |
| cpu request | 100m      | 250m      | 500m      |
| log level   | debug     | info      | warn      |
| image reg   | ECR       | ECR       | ECR       |

每个 overlay 只放与 base 不同的部分：

yaml
# overlays/qa/kustomization.yaml — 最简
apiVersion: kustomize.config.k8s.io/v1beta1
kind: Kustomization
namespace: qa
resources:
  - ../../base
images:
  - name: my-service
    newName: 123456789.dkr.ecr.us-west-2.amazonaws.com/my-service
    newTag: qa-latest
patches:
  - patch: |-
      apiVersion: apps/v1
      kind: Deployment
      metadata:
        name: my-service
      spec:
        replicas: 1

构建验证#

bash
# 预览最终生成的 YAML（必须在提交前执行）
kustomize build overlays/prod

# 或用 kubectl
kubectl kustomize overlays/prod

# 验证生成的资源是否合法
kustomize build overlays/prod | kubectl apply --dry-run=client -f -

# 对比两个环境的差异
diff <(kustomize build overlays/qa) <(kustomize build overlays/prod)

与 ArgoCD 协同#

ArgoCD 原生支持 Kustomize，典型 Application 配置：

yaml
apiVersion: argoproj.io/v1alpha1
kind: Application
metadata:
  name: my-service-prod
spec:
  source:
    repoURL: https://github.com/org/gitops-repo.git
    targetRevision: main
    path: services/my-service/overlays/prod
  destination:
    server: https://kubernetes.default.svc
    namespace: production
  syncPolicy:
    automated:
      prune: true
      selfHeal: true
    syncOptions:
      - CreateNamespace=true

CI 中更新镜像 tag：

bash
cd gitops-repo/services/my-service/overlays/prod
kustomize edit set image my-service=ecr-repo/my-service:${NEW_TAG}
git add kustomization.yaml
git commit -m "deploy: my-service ${NEW_TAG}"
git push

vs Helm：适用场景#

维度	Kustomize	Helm
学习曲线	低（无模板语法）	中（Go template + Sprig 函数）
表达力	有限（patch + overlay）	强（模板逻辑、条件渲染）
配置复用	base + overlay + component	values + 子 chart
适合场景	内部应用多环境管理	分发给第三方、复杂参数化
生态	K8s 原生内置	庞大 Chart 生态
GitOps 友好	高（纯 YAML，易 diff）	中（渲染后才能 diff）

经验法则：

内部应用、多环境管理 → Kustomize。纯 YAML、易 diff、GitOps 友好。
分发给第三方、需要复杂参数化 → Helm。Chart 生态成熟、values 灵活。
混合方案：Kustomize 可以通过 helmCharts 字段引用 Helm Chart，先用 Helm 部署基础设施（cert-manager、prometheus），再用 Kustomize 管理业务应用。

常见坑#

坑	说明	解决
commonLabels 污染 selector	`commonLabels` 会写入 `spec.selector.matchLabels`，后续改不了	只在初始设计时用，或改用 `labels`（Kustomize 4.5+）
patches 顺序问题	多个 patch 修改同一字段，后面的覆盖前面的	注意 patches 数组顺序
resources 路径错误	相对路径基于 kustomization.yaml 所在目录	用 `../../base` 而非 `base`
数组合并不符预期	Strategic Merge Patch 可能替换整个数组	用 JSON Patch 精确操作数组元素
image 替换不生效	deployment 中 image 名称与 kustomization.yaml 中不匹配	`images.name` 必须完全匹配原始 image 字段

小结#

Kustomize 的 base + overlay 模型简洁直观——无模板语法、纯 YAML、易 diff，特别适合内部应用的多环境管理。Strategic Merge 适合改字段，JSON Patch 适合删字段和精确操作数组。Components 提供了跨 overlay 复用的能力。与 Helm 相比，Kustomize 在 GitOps 场景下更友好（纯 YAML 易 diff），Helm 在分发和复杂参数化场景更强。两者可以混合使用——Helm 管基础设施 Chart，Kustomize 管业务应用。