2. Kustomize 安装与基础配置：安装方式、kubectl 内置集成、初始化项目结构

在开始使用 Kustomize 管理环境差异化镜像配置之前，首先需要正确安装工具并理解其项目结构。Kustomize 提供了多种安装路径，且从 Kubernetes 1.14 开始已原生集成在 kubectl 中。本章将系统讲解三种安装方式、验证方法以及标准项目结构的初始化流程。

2.1 安装方式对比

根据团队工作流和集群版本的不同，可以选择以下三种安装方式之一：

2.2 kubectl 内置集成（默认推荐）

从 Kubernetes 1.14 开始，kustomize 子命令已内置于 kubectl 中。验证方式如下：

# 检查 kubectl 版本（需 ≥ 1.14）
kubectl version --client

# 验证 kustomize 子命令可用
kubectl kustomize --help

# 查看内置 kustomize 版本
kubectl kustomize version

内置集成的核心命令映射关系：

2.3 独立二进制安装（推荐 CI/CD）

适用于需要精确控制版本或使用最新功能的场景。以下为 Linux/macOS 通用安装步骤：

# 下载指定版本（以 v5.4.3 为例）
curl -s "https://raw.githubusercontent.com/kubernetes-sigs/kustomize/master/hack/install_kustomize.sh" | bash -s 5.4.3

# 移动至系统 PATH
sudo mv kustomize /usr/local/bin/

# 验证安装
kustomize version

# 预期输出示例
# {kustomize/v5.4.3 (2024-05-20T15:00:00Z)  ...}

macOS 用户也可通过 Homebrew 安装：

brew install kustomize

2.4 初始化项目结构

Kustomize 项目遵循 base + overlay 的层级模式。以下为推荐的标准目录结构：

my-app/
├── base/                    # 基准配置（环境无关）
│   ├── kustomization.yaml   # 基准 kustomization 文件
│   ├── deployment.yaml      # Deployment 资源
│   ├── service.yaml         # Service 资源
│   └── configmap.yaml       # ConfigMap 资源
├── overlay/                 # 环境差异化配置
│   ├── dev/                 # 开发环境
│   │   ├── kustomization.yaml
│   │   ├── deployment-patch.yaml
│   │   └── configmap-patch.yaml
│   ├── staging/             # 预发布环境
│   │   ├── kustomization.yaml
│   │   └── deployment-patch.yaml
│   └── prod/                # 生产环境
│       ├── kustomization.yaml
│       ├── deployment-patch.yaml
│       └── secrets.yaml
└── README.md

2.5 初始化 kustomization.yaml

在 base/ 目录下创建基准 kustomization.yaml：

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

resources:
  - deployment.yaml
  - service.yaml
  - configmap.yaml

# 公共标签（所有资源自动注入）
commonLabels:
  app: my-app
  managed-by: kustomize

# 公共注解
commonAnnotations:
  version: "1.0.0"
  environment: "base"

在 overlay/dev/ 目录下创建开发环境 kustomization.yaml：

# overlay/dev/kustomization.yaml
apiVersion: kustomize.config.k8s.io/v1beta1
kind: Kustomization

# 引用 base 目录（相对路径）
resources:
  - ../../base

# 环境特定补丁
patches:
  - path: deployment-patch.yaml
    target:
      kind: Deployment
      name: my-app

# 环境特定镜像覆盖
images:
  - name: my-app-image
    newName: registry.dev.example.com/my-app
    newTag: dev-20240520

# 环境特定名称前缀
namePrefix: dev-

# 环境特定命名空间
namespace: dev-ns

2.6 验证项目结构

使用以下命令验证项目结构是否正确：

# 构建 base（验证基准配置）
kubectl kustomize base/

# 构建 dev overlay（验证环境差异化）
kubectl kustomize overlay/dev/

# 直接应用 dev 环境（kubectl 1.21+）
kubectl apply -k overlay/dev/

2.7 常见安装问题排查