📚 课程目录第2章 Kustomize安装与基础结构

2. Kustomize 安装与基础结构

Kustomize 自 Kubernetes 1.14 起以 kubectl kustomize 子命令形式内置，也可作为独立 CLI 安装。理解其安装方式与核心文件结构是掌握后续覆盖（overlay）与基础（base）概念的前提。

2.1 安装方式

安装方式	命令 / 步骤	适用场景
kubectl 内置	`kubectl kustomize <目录>`	K8s 1.14+ 集群环境，无需额外安装
独立二进制	`curl -s "https://raw.githubusercontent.com/kubernetes-sigs/kustomize/master/hack/install_kustomize.sh" \| bash`	CI/CD 流水线、本地开发、离线环境
Go 安装	`go install sigs.k8s.io/kustomize/kustomize/v5@latest`	Go 开发者，需要最新特性
Homebrew (macOS)	`brew install kustomize`	macOS 开发者快速安装

版本确认：安装后执行 kustomize version 或 kubectl kustomize --help 验证。推荐使用 v4.5+ 版本以支持所有覆盖与补丁特性。

2.2 kustomization.yaml 文件结构

kustomization.yaml 是 Kustomize 的声明式配置文件，位于每个 Kustomize 目录的根路径。它定义了资源来源、补丁、配置映射、名称前缀/后缀等行为。

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

# 资源列表：可以是本地文件路径或 URL
resources:
  - deployment.yaml
  - service.yaml
  - namespace.yaml

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

# 名称后缀：为所有资源名称添加统一后缀
nameSuffix: -v1

# 公共标签：注入到所有资源的 metadata.labels
commonLabels:
  app: my-app
  env: production

# 公共注解：注入到所有资源的 metadata.annotations
commonAnnotations:
  managed-by: kustomize
  team: platform

# 配置映射生成器
configMapGenerator:
  - name: app-config
    files:
      - config/app.properties

# 补丁：对已有资源进行局部修改
patches:
  - path: increase-replicas.yaml
    target:
      kind: Deployment
      name: my-app

  关键字段速查：
  resources — 声明要管理的原始 YAML 文件列表
patches — 定义对资源的覆盖修改（strategic merge 或 JSON patch）
namePrefix / nameSuffix — 避免多环境资源名称冲突
commonLabels / commonAnnotations — 统一标签与注解管理
configMapGenerator / secretGenerator — 从文件或字面量生成 ConfigMap/Secret

2.3 Overlays 与 Bases 概念

Kustomize 通过 base（基础） 和 overlay（覆盖） 两层结构实现环境差异化配置。base 定义通用资源，overlay 通过引用 base 并叠加补丁、替换镜像、调整副本数等方式生成最终环境清单。

2.4 典型目录布局

生产实践中推荐以下目录结构，将 base 与多个 overlay 清晰分离：

project-root/
├── base/                          # 基础层
│   ├── kustomization.yaml
│   ├── deployment.yaml
│   ├── service.yaml
│   └── configmap.yaml
├── overlays/                      # 覆盖层
│   ├── dev/                       # 开发环境
│   │   ├── kustomization.yaml
│   │   └── patches/
│   │       └── replicas-patch.yaml
│   ├── staging/                   # 预发布环境
│   │   ├── kustomization.yaml
│   │   └── patches/
│   │       ├── replicas-patch.yaml
│   │       └── image-patch.yaml
│   └── prod/                      # 生产环境
│       ├── kustomization.yaml
│       └── patches/
│           ├── replicas-patch.yaml
│           ├── image-patch.yaml
│           └── hpa-patch.yaml

常见误区：

不要在 base 中写入环境特定值（如副本数、镜像标签），这些应放在 overlay 的补丁中。
避免在 overlay 中重复定义 base 已有的完整资源，应使用 patches 进行增量修改。
多个 overlay 共享同一 base 时，base 的变更会自动传播到所有环境，确保一致性。

2.5 验证与渲染

使用以下命令验证 overlay 是否正确引用 base 并生成期望的 YAML：

# 查看渲染后的完整 YAML（不实际 apply）
kustomize build overlays/prod/

# 或使用 kubectl 内置命令
kubectl kustomize overlays/prod/

# 将渲染结果输出到文件，便于审查
kustomize build overlays/prod/ > rendered-prod.yaml

调试技巧：使用 kustomize build --reorder none 可以禁用资源排序，便于对比 base 与 overlay 的差异。结合 diff 命令可快速定位补丁效果。