mcpField
K
kustomize

kustomize

github.com/bagelhole云与 DevOps1.2k372 次安装23 周前更新
代码仓库

关于 kustomize

kustomize 技能介绍如何以声明式方式定制 Kubernetes 资源，无需模板。适合管理多环境配置、修改现有清单及组合第三方清单。

主要功能

  1. 01通过 base 和 overlay 管理环境配置
  2. 02使用合并补丁或 JSON 补丁
  3. 03生成 ConfigMap 和 Secret
  4. 04调整镜像、命名空间和副本数
  5. 05组合组件与远程资源

适用场景

  1. 01为开发和生产环境维护不同配置
  2. 02在不改动基础清单时应用补丁
  3. 03从配置文件生成 ConfigMap 或 Secret

安装

复制下面的命令，在终端中运行。

$npx skills add https://github.com/bagelhole/devops-security-agent-skills --skill kustomize

安装后在 Claude Code 中输入/kustomize确认已加载。

详细介绍

Kustomize

以声明式方式自定义 Kubernetes 资源，无需使用模板。

何时使用此技能

在以下情况下使用此技能：

  • 跨环境管理 Kubernetes 配置
  • 在不修改现有清单的情况下对其进行补丁
  • 基于基础配置创建配置变体
  • 自定义第三方清单
  • 倾向于使用声明式方法而非模板

前提条件

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

目录结构

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

基础配置

kustomization.yaml
# 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
基础资源
# 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"

覆盖配置

开发环境覆盖配置
# 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
生产环境覆盖配置
# 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

补丁

Strategic Merge 补丁
# 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"
JSON 补丁
# 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
内联补丁
# kustomization.yaml
patches:
  - patch: |-
      apiVersion: apps/v1
      kind: Deployment
      metadata:
        name: myapp
      spec:
        replicas: 3
    target:
      kind: Deployment
      name: myapp

配置生成

ConfigMap 生成器
# kustomization.yaml
configMapGenerator:
  - name: myapp-config
    literals:
      - APP_ENV=production
      - LOG_LEVEL=info
    files:
      - config.yaml
    envs:
      - config.env
    options:
      disableNameSuffixHash: false
Secret 生成器
# kustomization.yaml
secretGenerator:
  - name: myapp-secrets
    literals:
      - api-key=secret123
    files:
      - tls.crt
      - tls.key
    type: kubernetes.io/tls

镜像转换

# 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...

资源转换

名称前缀/后缀
# kustomization.yaml
namePrefix: prod-
nameSuffix: -v2
命名空间
# kustomization.yaml
namespace: production
标签和注解
# kustomization.yaml
commonLabels:
  app.kubernetes.io/name: myapp
  app.kubernetes.io/environment: production

commonAnnotations:
  example.com/owner: team-a
副本数
# kustomization.yaml
replicas:
  - name: myapp
    count: 5
  - name: worker
    count: 3

组件

# 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"

# overlays/production/kustomization.yaml
components:
  - ../../components/monitoring

远程资源

# 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

命令

# 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 build overlays/production

# Build and apply
kustomize build overlays/production | kubectl apply -f -

Helm Chart 集成

# 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

变量替换

# 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

常见问题

问题：名称哈希冲突

问题：ConfigMap 发生更改时资源未更新 解决方案：启用名称后缀哈希（默认行为），或使用替换

问题：补丁未应用

问题：Strategic Merge 补丁不起作用 解决方案：确认资源名称匹配；复杂更改请使用 JSON 补丁

问题：远程资源获取失败

问题：无法获取远程资源 解决方案：检查 URL，确认 ref/tag 存在，并确保网络可访问

问题：标签选择器不匹配

问题：commonLabels 导致选择器失效 解决方案：使用 includeSelectors: false，或排除特定资源

commonLabels:
  app: myapp
configurations:
  - labelExclusions.yaml

最佳实践

  • 让基础清单不依赖特定环境
  • 使用覆盖配置处理特定环境的配置
  • 简单更改优先使用 Strategic Merge 补丁
  • 使用组件实现可选功能
  • 固定远程资源版本
  • 启用 ConfigMap/Secret 哈希后缀
  • 在 README 中记录覆盖配置的目录结构
  • 应用前测试构建结果

相关技能

评论

支持 Markdown