kustomize

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Kustomize

Customize Kubernetes resources declaratively without templating.

无需模板即可声明式自定义Kubernetes资源。

When to Use This Skill

使用场景

Use this skill when:

Managing Kubernetes configs across environments
Patching existing manifests without modification
Creating configuration variants from bases
Customizing third-party manifests
Preferring declarative over templating approach

在以下场景使用该技能：

跨环境管理Kubernetes配置
无需修改现有清单即可修补资源
基于基础配置创建配置变体
自定义第三方清单
偏好声明式方法而非模板化方法

Prerequisites

前置条件

kubectl 1.14+ (includes kustomize)
Or standalone kustomize CLI
Basic Kubernetes manifest knowledge

kubectl 1.14+（内置kustomize）
或独立的kustomize CLI
具备基础的Kubernetes清单知识

Directory Structure

目录结构

myapp/
├── base/
│   ├── kustomization.yaml
│   ├── deployment.yaml
│   ├── service.yaml
│   └── configmap.yaml
└── overlays/
    ├── development/
    │   ├── kustomization.yaml
    │   └── replica-patch.yaml
    ├── staging/
    │   ├── kustomization.yaml
    │   └── namespace.yaml
    └── production/
        ├── kustomization.yaml
        ├── replica-patch.yaml
        └── resource-patch.yaml

myapp/
├── base/
│   ├── kustomization.yaml
│   ├── deployment.yaml
│   ├── service.yaml
│   └── configmap.yaml
└── overlays/
    ├── development/
    │   ├── kustomization.yaml
    │   └── replica-patch.yaml
    ├── staging/
    │   ├── kustomization.yaml
    │   └── namespace.yaml
    └── production/
        ├── kustomization.yaml
        ├── replica-patch.yaml
        └── resource-patch.yaml

Base Configuration

基础配置

kustomization.yaml

yaml

undefined

yaml

undefined

base/kustomization.yaml

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

resources:

deployment.yaml
service.yaml
configmap.yaml

commonLabels: app: myapp

commonAnnotations: managed-by: kustomize

undefined

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

resources:

deployment.yaml
service.yaml
configmap.yaml

commonLabels: app: myapp

commonAnnotations: managed-by: kustomize

undefined

Base Resources

基础资源

yaml

undefined

yaml

undefined

base/deployment.yaml

apiVersion: apps/v1 kind: Deployment metadata: name: myapp spec: replicas: 1 selector: matchLabels: app: myapp template: metadata: labels: app: myapp spec: containers: - name: myapp image: myapp:latest ports: - containerPort: 8080 resources: requests: memory: "64Mi" cpu: "100m" limits: memory: "128Mi" cpu: "200m"

undefined

undefined

Overlays

覆盖层

Development Overlay

开发环境覆盖层

yaml

undefined

yaml

undefined

overlays/development/kustomization.yaml

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

resources:

../../base

namespace: myapp-dev

namePrefix: dev-

commonLabels: environment: development

images:

name: myapp newTag: dev-latest

undefined

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

resources:

../../base

namespace: myapp-dev

namePrefix: dev-

commonLabels: environment: development

images:

name: myapp newTag: dev-latest

undefined

Production Overlay

生产环境覆盖层

yaml

undefined

yaml

undefined

overlays/production/kustomization.yaml

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

resources:

../../base

namespace: myapp-prod

namePrefix: prod-

commonLabels: environment: production

replicas:

name: myapp count: 5

images:

name: myapp newName: registry.example.com/myapp newTag: v2.0.0

patches:

path: resource-patch.yaml

undefined

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

resources:

../../base

namespace: myapp-prod

namePrefix: prod-

commonLabels: environment: production

replicas:

name: myapp count: 5

images:

name: myapp newName: registry.example.com/myapp newTag: v2.0.0

patches:

path: resource-patch.yaml

undefined

Patching

资源修补

Strategic Merge Patch

策略合并修补

yaml

undefined

yaml

undefined

overlays/production/resource-patch.yaml

apiVersion: apps/v1 kind: Deployment metadata: name: myapp spec: template: spec: containers: - name: myapp resources: requests: memory: "256Mi" cpu: "500m" limits: memory: "512Mi" cpu: "1000m"

undefined

apiVersion: apps/v1 kind: Deployment metadata: name: myapp spec: template: spec: containers: - name: myapp resources: requests: memory: "256Mi" cpu: "500m" limits: memory: "512Mi" cpu: "1000m"

undefined

JSON Patch

JSON修补

yaml

undefined

yaml

undefined

kustomization.yaml

patches:

target: kind: Deployment name: myapp patch: |-
- op: replace path: /spec/replicas value: 5
- op: add path: /spec/template/spec/containers/0/env value:
  - name: LOG_LEVEL value: info

undefined

patches:

target: kind: Deployment name: myapp patch: |-
- op: replace path: /spec/replicas value: 5
- op: add path: /spec/template/spec/containers/0/env value:
  - name: LOG_LEVEL value: info

undefined

Inline Patches

内联修补

yaml

undefined

yaml

undefined

kustomization.yaml

patches:

patch: |- apiVersion: apps/v1 kind: Deployment metadata: name: myapp spec: replicas: 3 target: kind: Deployment name: myapp

undefined

patches:

patch: |- apiVersion: apps/v1 kind: Deployment metadata: name: myapp spec: replicas: 3 target: kind: Deployment name: myapp

undefined

Configuration Generation

配置生成

ConfigMap Generator

ConfigMap生成器

yaml

undefined

yaml

undefined

kustomization.yaml

configMapGenerator:

name: myapp-config literals:
- APP_ENV=production
- LOG_LEVEL=info files:
- config.yaml envs:
- config.env options: disableNameSuffixHash: false

undefined

configMapGenerator:

name: myapp-config literals:
- APP_ENV=production
- LOG_LEVEL=info files:
- config.yaml envs:
- config.env options: disableNameSuffixHash: false

undefined

Secret Generator

Secret生成器

yaml

undefined

yaml

undefined

kustomization.yaml

secretGenerator:

name: myapp-secrets literals:
- api-key=secret123 files:
- tls.crt
- tls.key type: kubernetes.io/tls

undefined

secretGenerator:

name: myapp-secrets literals:
- api-key=secret123 files:
- tls.crt
- tls.key type: kubernetes.io/tls

undefined

Image Transformations

镜像转换

yaml

undefined

yaml

undefined

kustomization.yaml

images:

Change tag

name: myapp newTag: v2.0.0

Change registry

name: myapp newName: registry.example.com/myapp newTag: v2.0.0

Use digest

name: myapp digest: sha256:abc123...

undefined

images:

修改标签

name: myapp newTag: v2.0.0

修改镜像仓库

name: myapp newName: registry.example.com/myapp newTag: v2.0.0

使用镜像摘要

name: myapp digest: sha256:abc123...

undefined

Resource Transformations

资源转换

Name Prefix/Suffix

名称前缀/后缀

yaml

undefined

yaml

undefined

kustomization.yaml

namePrefix: prod- nameSuffix: -v2

undefined

namePrefix: prod- nameSuffix: -v2

undefined

Namespace

命名空间

yaml

undefined

yaml

undefined

kustomization.yaml

namespace: production

undefined

namespace: production

undefined

Labels and Annotations

标签与注解

yaml

undefined

yaml

undefined

kustomization.yaml

commonLabels: app.kubernetes.io/name: myapp app.kubernetes.io/environment: production

commonAnnotations: example.com/owner: team-a

undefined

commonLabels: app.kubernetes.io/name: myapp app.kubernetes.io/environment: production

commonAnnotations: example.com/owner: team-a

undefined

Replicas

副本数

yaml

undefined

yaml

undefined

kustomization.yaml

replicas:

name: myapp count: 5
name: worker count: 3

undefined

replicas:

name: myapp count: 5
name: worker count: 3

undefined

Components

组件

yaml

undefined

yaml

undefined

components/monitoring/kustomization.yaml

apiVersion: kustomize.config.k8s.io/v1alpha1 kind: Component

resources:

servicemonitor.yaml

patches:

patch: |- apiVersion: apps/v1 kind: Deployment metadata: name: myapp spec: template: metadata: annotations: prometheus.io/scrape: "true" prometheus.io/port: "8080"


```yaml

apiVersion: kustomize.config.k8s.io/v1alpha1 kind: Component

resources:

servicemonitor.yaml

patches:

patch: |- apiVersion: apps/v1 kind: Deployment metadata: name: myapp spec: template: metadata: annotations: prometheus.io/scrape: "true" prometheus.io/port: "8080"


```yaml

overlays/production/kustomization.yaml

components:

../../components/monitoring

undefined

components:

../../components/monitoring

undefined

Remote Resources

远程资源

yaml

undefined

yaml

undefined

kustomization.yaml

resources:

Remote Git repository

https://github.com/org/manifests//base?ref=v1.0.0

Remote URL

https://raw.githubusercontent.com/org/repo/main/deployment.yaml

undefined

resources:

远程Git仓库

https://github.com/org/manifests//base?ref=v1.0.0

远程URL

https://raw.githubusercontent.com/org/repo/main/deployment.yaml

undefined

Commands

命令

bash

undefined

bash

undefined

Build and view output

构建并查看输出

kubectl kustomize overlays/production

Apply to cluster

应用到集群

kubectl apply -k overlays/production

Delete resources

删除资源

kubectl delete -k overlays/production

View diff

查看差异

kubectl diff -k overlays/production

Build with standalone kustomize

使用独立kustomize构建

kustomize build overlays/production

Build and apply

构建并应用

kustomize build overlays/production | kubectl apply -f -

undefined

kustomize build overlays/production | kubectl apply -f -

undefined

Helm Chart Integration

Helm Chart集成

yaml

undefined

yaml

undefined

kustomization.yaml

helmCharts:

name: prometheus repo: https://prometheus-community.github.io/helm-charts version: 25.0.0 releaseName: prometheus namespace: monitoring valuesFile: values.yaml includeCRDs: true

undefined

helmCharts:

name: prometheus repo: https://prometheus-community.github.io/helm-charts version: 25.0.0 releaseName: prometheus namespace: monitoring valuesFile: values.yaml includeCRDs: true

undefined

Variable Substitution

变量替换

yaml

undefined

yaml

undefined

kustomization.yaml

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

resources:

deployment.yaml

replacements:

source: kind: ConfigMap name: myapp-config fieldPath: data.APP_VERSION targets:
- select: kind: Deployment name: myapp fieldPaths:
  - spec.template.spec.containers.[name=myapp].image options: delimiter: ':' index: 1

undefined

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

resources:

deployment.yaml

replacements:

source: kind: ConfigMap name: myapp-config fieldPath: data.APP_VERSION targets:
- select: kind: Deployment name: myapp fieldPaths:
  - spec.template.spec.containers.[name=myapp].image options: delimiter: ':' index: 1

undefined

Common Issues

常见问题

Issue: Name Hash Conflicts

问题：名称哈希冲突

Problem: Resources not updating when ConfigMap changes Solution: Enable name suffix hash (default) or use replacement

问题：ConfigMap变更后资源未更新 解决方案：启用名称后缀哈希（默认开启）或使用替换功能

Issue: Patch Not Applying

问题：修补未生效

Problem: Strategic merge patch doesn't work Solution: Verify resource names match, use JSON patch for complex changes

问题：策略合并修补不起作用 解决方案：验证资源名称匹配，针对复杂变更使用JSON修补

Issue: Remote Resource Fails

问题：远程资源获取失败

Problem: Cannot fetch remote resources Solution: Check URL, verify ref/tag exists, ensure network access

问题：无法获取远程资源 解决方案：检查URL，验证引用/标签存在，确保网络可访问

Issue: Label Selector Mismatch

问题：标签选择器不匹配

Problem: commonLabels breaks selectors Solution: Use includeSelectors: false or exclude specific resources

yaml

commonLabels:
  app: myapp
configurations:
  - labelExclusions.yaml

问题：commonLabels破坏选择器 解决方案：使用includeSelectors: false或排除特定资源

yaml

commonLabels:
  app: myapp
configurations:
  - labelExclusions.yaml

Best Practices

最佳实践

Keep base manifests environment-agnostic
Use overlays for environment-specific config
Prefer strategic merge patches for simple changes
Use components for optional features
Pin remote resource versions
Enable ConfigMap/Secret hash suffixes
Document overlay structure in README
Test builds before applying

保持基础清单与环境无关
使用覆盖层处理环境特定配置
简单变更优先使用策略合并修补
使用组件实现可选功能
固定远程资源版本
启用ConfigMap/Secret哈希后缀
在README中记录覆盖层结构
应用前测试构建结果