📚 课程目录第3章 kustomization.yaml文件详解

3. kustomization.yaml 文件详解：核心字段

kustomization.yaml 是 Kustomize 的声明式配置入口文件，它告诉 Kustomize 如何读取、转换和输出 Kubernetes 资源。本章将深入解析 apiVersion、resources、patches、images 等核心字段的语法、作用与最佳实践。

3.1 apiVersion：声明 Kustomize 版本

apiVersion 字段指定了 kustomization.yaml 文件所遵循的 Kustomize API 版本。不同版本支持的字段和功能有所差异。

apiVersion 值	对应 Kustomize 版本	关键变化
`kustomize.config.k8s.io/v1beta1`	v2.x ~ v3.x	早期版本，支持基础字段，`patches` 使用 `patchesStrategicMerge` 和 `patchesJson6902`。
`kustomize.config.k8s.io/v1`	v4.x +	稳定版本，引入 `patches` 统一字段，废弃旧字段，推荐使用。

推荐做法： 始终使用 kustomize.config.k8s.io/v1，以获得最新的功能支持和向后兼容性。

3.2 resources：声明基础资源

resources 字段用于列出所有需要被 Kustomize 处理的原始 Kubernetes 资源文件（YAML/JSON）。这些文件可以是本地路径，也可以是远程 URL。

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

resources:
  - deployment.yaml
  - service.yaml
  - configmap.yaml
  - ../../base/namespace.yaml
  - https://raw.githubusercontent.com/example/manifests/main/ingress.yaml

本地路径： 支持相对路径（./、../）和路径。
远程 URL： 支持 HTTP/HTTPS 协议的原始 YAML 文件。
目录引用： 可以引用另一个包含 kustomization.yaml 的目录，实现资源组合。

注意： 当引用远程资源时，Kustomize 会在构建时下载并缓存。确保网络可达，且 URL 指向的是原始内容（raw content），而非 GitHub 的页面地址。

3.3 patches：资源补丁与覆盖

patches 字段是 Kustomize 实现环境差异化配置的核心机制。它允许你对 resources 中定义的资源进行局部修改，而无需复制整个 YAML 文件。

在 apiVersion: v1 中，patches 是一个统一的字段，支持两种补丁策略：

补丁策略	patch 类型	适用场景
Strategic Merge Patch	`strategic` 或 `application/strategic-merge-patch+json`	修改现有字段、添加新字段、合并列表（如环境变量、卷挂载）。
JSON Patch (RFC 6902)	`json` 或 `application/json-patch+json`	精确的增、删、改操作，适合替换整个数组或删除特定元素。

3.3.1 Strategic Merge Patch 示例

# kustomization.yaml
patches:
  - target:
      kind: Deployment
      name: my-app
    patch: |-
      apiVersion: apps/v1
      kind: Deployment
      metadata:
        name: my-app
      spec:
        replicas: 5
        template:
          spec:
            containers:
              - name: app
                resources:
                  limits:
                    memory: "1Gi"
                    cpu: "500m"

3.3.2 JSON Patch 示例

# kustomization.yaml
patches:
  - target:
      kind: Service
      name: my-service
    patch: |-
      - op: replace
        path: /spec/type
        value: NodePort
      - op: add
        path: /spec/ports/-
        value:
          name: debug
          port: 9999

  最佳实践： 优先使用 Strategic Merge Patch 进行字段合并和修改；当需要精确删除或替换整个列表时，使用 JSON Patch。

3.4 images：镜像标签与仓库替换

images 字段是 Kustomize 专门为容器镜像管理设计的便捷字段。它允许你批量修改 Deployment、StatefulSet、DaemonSet 等资源中的镜像名称和标签，而无需编写复杂的补丁。

# kustomization.yaml
images:
  - name: my-registry/my-app
    newName: my-registry-staging/my-app
    newTag: v1.2.3
  - name: nginx
    newTag: 1.25.3-alpine
  - name: busybox
    digest: sha256:abc123...

字段	说明	示例
`name`	要匹配的原始镜像名称（不含标签）	`my-registry/my-app`
`newName`	替换后的镜像仓库/名称	`my-registry-staging/my-app`
`newTag`	替换后的镜像标签	`v1.2.3`
`digest`	替换为指定的镜像摘要（优先级高于 `newTag`）	`sha256:abc123...`

提示： images 字段会自动匹配所有资源中 image: 字段的值。如果只指定 newTag，则只更新标签，保留原始仓库地址。这在 overlay 中切换环境镜像版本时非常高效。

3.5 核心字段协作流程

下图展示了 kustomization.yaml 中核心字段如何协同工作，将基础资源转换为环境特定的最终输出。

3.6 其他常用字段一览

除了上述核心字段，kustomization.yaml 还支持以下常用字段，用于更精细的配置管理：

字段	作用	典型用法
`namespace`	为所有资源设置目标命名空间	`namespace: production`
`namePrefix`	为所有资源名称添加前缀	`namePrefix: prod-`
`nameSuffix`	为所有资源名称添加后缀	`nameSuffix: -v2`
`commonLabels`	为所有资源添加公共标签	`commonLabels: { env: production }`
`commonAnnotations`	为所有资源添加公共注解	`commonAnnotations: { managed-by: kustomize }`
`configMapGenerator`	从文件或字面量生成 ConfigMap	`configMapGenerator: [{ name: app-config, literals: [key=value] }]`
`secretGenerator`	从文件或字面量生成 Secret	`secretGenerator: [{ name: db-secret, literals: [password=xxx] }]`

3.7 完整示例：生产环境 overlay

以下是一个生产环境 overlay 的 kustomization.yaml 示例，展示了核心字段的综合运用：

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

resources:
  - ../../base

namespace: production
namePrefix: prod-

commonLabels:
  env: production
  team: platform

patches:
  - target:
      kind: Deployment
      name: web-app
    patch: |-
      - op: replace
        path: /spec/replicas
        value: 10
      - op: add
        path: /spec/template/spec/containers/0/env/-
        value:
          name: LOG_LEVEL
          value: "info"

images:
  - name: my-registry/web-app
    newTag: 2.3.0
  - name: my-registry/worker
    newTag: 1.8.1

  关键点： 通过 resources 引入基础配置，namespace 和 namePrefix 隔离环境，patches 调整副本数和环境变量，images 指定生产环境镜像版本。所有修改都集中在 overlay 中，基础配置保持纯净。