Kustomizeの使い方｜base・overlay・patchの書き方

Kustomize は、Kubernetes の YAML を「共通部分（base）」と「環境ごとの差分（overlay）」に分けて書き、kustomize build で1つの YAML に組み立てるツールです。 テンプレート言語は使わず、元の YAML に「上書き」を重ねる方式です。kubectl にも組み込まれていて、kubectl apply -k で適用できます。

app/
├── base/
│   ├── kustomization.yaml
│   ├── deployment.yaml
│   └── service.yaml
└── overlays/
    ├── dev/
    │   └── kustomization.yaml
    └── prod/
        ├── kustomization.yaml
        └── resources-patch.yaml

kustomize build overlays/prod          # 組み立てた YAML を表示（クラスタには触らない）
kubectl kustomize overlays/prod        # kubectl 組み込み版で同じことをする
kubectl apply -k overlays/prod         # 組み立てて適用

よく使う書き方の早見表です（この記事で、それぞれ build の出力を確かめました）。

確認環境：kustomize v5.8.3（GitHub リリースの linux_amd64 バイナリ）、Linux。この記事の YAML はすべて kustomize build を実行して、出力をそのまま載せています。フィールドの仕様は Kustomize の公式リファレンス（kubectl.docs.kubernetes.io）で確かめました（確認日 2026年10月13日）。

インストールと kubectl 組み込み版の違い

Kustomize には、単体のバイナリと、kubectl に組み込まれたものがあります。

# Linux（amd64）。版は GitHub のリリース一覧で確かめる
curl -sSL -o kustomize.tgz \
  "https://github.com/kubernetes-sigs/kustomize/releases/download/kustomize%2Fv5.8.3/kustomize_v5.8.3_linux_amd64.tar.gz"
tar xzf kustomize.tgz
./kustomize version
# v5.8.3

kubectl に組み込まれた版は kubectl version --client の Kustomize Version で見られます。CI で build 結果を比べるときは、手元と CI で同じ版を使うと出力の違いが出にくくなります。

base を作る

base には、どの環境でも共通の YAML を置きます。

# base/deployment.yaml
apiVersion: apps/v1
kind: Deployment
metadata:
  name: web
spec:
  replicas: 1
  selector:
    matchLabels:
      app: web
  template:
    metadata:
      labels:
        app: web
    spec:
      containers:
        - name: web
          image: nginx:1.27
          ports:
            - containerPort: 80
          envFrom:
            - configMapRef:
                name: web-config
          resources:
            requests:
              cpu: 100m
              memory: 128Mi

# base/service.yaml
apiVersion: v1
kind: Service
metadata:
  name: web
spec:
  selector:
    app: web
  ports:
    - port: 80
      targetPort: 80

# base/kustomization.yaml
apiVersion: kustomize.config.k8s.io/v1beta1
kind: Kustomization
resources:
  - deployment.yaml
  - service.yaml
labels:
  - pairs:
      app.kubernetes.io/name: web
    includeSelectors: false
    includeTemplates: true
configMapGenerator:
  - name: web-config
    literals:
      - LOG_LEVEL=info
      - FEATURE_X=false

kustomize build base の出力です（Deployment の後半は省略）。

apiVersion: v1
data:
  FEATURE_X: "false"
  LOG_LEVEL: info
kind: ConfigMap
metadata:
  labels:
    app.kubernetes.io/name: web
  name: web-config-8tbtckf5t2
---
apiVersion: v1
kind: Service
metadata:
  labels:
    app.kubernetes.io/name: web
  name: web
spec:
  ports:
  - port: 80
    targetPort: 80
  selector:
    app: web
---
apiVersion: apps/v1
kind: Deployment
metadata:
  labels:
    app.kubernetes.io/name: web
  name: web
spec:
  replicas: 1
  selector:
    matchLabels:
      app: web
  template:
    metadata:
      labels:
        app: web
        app.kubernetes.io/name: web
    spec:
      containers:
      - envFrom:
        - configMapRef:
            name: web-config-8tbtckf5t2

ここで分かることが3つあります。

• ConfigMap の名前に -8tbtckf5t2 が付き、Deployment の configMapRef も自動で書き換わりました。 中身から作るハッシュ（後述）です。
• labels の includeSelectors: false で、Service の selector と Deployment の matchLabels は変わっていません。 includeTemplates: true で、Pod のテンプレートのラベルには付きました。
• 出力は ConfigMap → Service → Deployment の順に並び替えられています。

overlay を作る（prod）

overlay は resources で base を読み込み、差分だけを書きます。

# overlays/prod/kustomization.yaml
apiVersion: kustomize.config.k8s.io/v1beta1
kind: Kustomization
namespace: prod
namePrefix: prod-
resources:
  - ../../base
images:
  - name: nginx
    newName: registry.example.com/web/nginx
    newTag: 1.27.3
replicas:
  - name: web
    count: 3
configMapGenerator:
  - name: web-config
    behavior: merge
    literals:
      - LOG_LEVEL=warn
patches:
  - path: resources-patch.yaml
  - target:
      kind: Deployment
      name: web
    patch: |-
      - op: add
        path: /spec/template/spec/containers/0/env
        value:
          - name: TZ
            value: Asia/Tokyo

# overlays/prod/resources-patch.yaml（strategic merge patch）
apiVersion: apps/v1
kind: Deployment
metadata:
  name: web
spec:
  template:
    spec:
      containers:
        - name: web
          resources:
            requests:
              cpu: 500m
              memory: 512Mi
            limits:
              memory: 512Mi

kustomize build overlays/prod の Deployment と ConfigMap です。

apiVersion: v1
data:
  FEATURE_X: "false"
  LOG_LEVEL: warn
kind: ConfigMap
metadata:
  labels:
    app.kubernetes.io/name: web
  name: prod-web-config-g954k2b5ht
  namespace: prod
---
apiVersion: apps/v1
kind: Deployment
metadata:
  labels:
    app.kubernetes.io/name: web
  name: prod-web
  namespace: prod
spec:
  replicas: 3
  selector:
    matchLabels:
      app: web
  template:
    metadata:
      labels:
        app: web
        app.kubernetes.io/name: web
    spec:
      containers:
      - env:
        - name: TZ
          value: Asia/Tokyo
        envFrom:
        - configMapRef:
            name: prod-web-config-g954k2b5ht
        image: registry.example.com/web/nginx:1.27.3
        name: web
        ports:
        - containerPort: 80
        resources:
          limits:
            memory: 512Mi
          requests:
            cpu: 500m
            memory: 512Mi

patches の name: web は、namePrefix を付ける前の名前（base の名前）で書きます。 出力の名前は prod-web ですが、web と書いて当たりました。

dev の overlay も同じ形で作り、違いを比べられます。

# overlays/dev/kustomization.yaml
apiVersion: kustomize.config.k8s.io/v1beta1
kind: Kustomization
namespace: dev
namePrefix: dev-
resources:
  - ../../base
configMapGenerator:
  - name: web-config
    behavior: merge
    literals:
      - LOG_LEVEL=debug
      - FEATURE_X=true

diff <(kustomize build overlays/dev) <(kustomize build overlays/prod)

patches の書き方：strategic merge と JSON6902

patches には2つの形式があります。昔の patchesStrategicMerge・patchesJson6902 は、どちらも patches 1つにまとまりました。

ファイルで書く（path）か、その場で書く（patch: |-）かは、どちらの形式でも選べます。

target の指定項目

labelSelector は、Pod テンプレートのラベルではなく、リソース自身の metadata.labels で判定されます。 base の Deployment は metadata.labels に app: web を持っていないため、labelSelector: app=web の patch はどれにも当たらず、エラーも出ないまま何も変わりませんでした。 当たったかどうかは build の出力で確かめます。

strategic merge でできること

patches:
  # コンテナを追加（名前が違うので追加になる）
  - patch: |-
      apiVersion: apps/v1
      kind: Deployment
      metadata:
        name: web
      spec:
        template:
          spec:
            containers:
              - name: log-agent
                image: busybox:1.37
                args: ["sh", "-c", "tail -F /var/log/app.log"]
  # リソースごと消す
  - patch: |-
      $patch: delete
      apiVersion: v1
      kind: Service
      metadata:
        name: web

build すると、Service が消え、containers は log-agent が先頭、web が2番目になりました。このあとに /spec/template/spec/containers/0/... の JSON6902 patch を書くと、log-agent を指してしまいます。 実際、containers/0/resources を消す patch は次のエラーになりました。

Error: error in remove for path: '/spec/template/spec/containers/0/resources': Unable to remove nonexistent key: resources: missing value

コンテナが複数あるときは、番号で指す JSON6902 より、name で突き合わせる strategic merge のほうが崩れにくくなります。

JSON6902 の op 一覧

configMapGenerator と secretGenerator

Generator は、ファイルや値から ConfigMap・Secret を作り、名前の後ろに中身のハッシュを付けます。 中身を変えると名前が変わり、それを参照する Deployment の Pod テンプレートも変わるので、ConfigMap を変えただけで Pod が入れ替わります。

configMapGenerator:
  - name: web-config
    envs:
      - app.env               # KEY=VALUE の行をそのまま data に
  - name: nginx-conf
    files:
      - default.conf=nginx.conf   # キー名=ファイル名
    options:
      disableNameSuffixHash: true  # ハッシュを付けない
secretGenerator:
  - name: db-secret
    literals:
      - password=s3cr3t
    type: Opaque

build の結果です。

app.env の DB_PORT を 5433 に変えて build し直すと、名前が web-config-h828979gh6 に変わり、Deployment の参照も同じ名前になりました。 disableNameSuffixHash: true にした ConfigMap は、中身を変えても Pod は入れ替わりません。

overlay で base の ConfigMap を変えるときは behavior を指定します。

secretGenerator の値は base64 にされるだけで、暗号化はされません。Git に平文のパスワードを置かないよう、本番の値は外部のシークレット管理（External Secrets、Sealed Secrets など）と組み合わせる方法がよく使われます。

images：タグ・レジストリ・ダイジェスト

images:
  - name: nginx                              # 元の YAML のイメージ名
    newName: registry.example.com/web/nginx  # レジストリやリポジトリを変える
    newTag: 1.27.3                           # タグを変える

images:
  - name: nginx
    digest: sha256:0000…0000   # ダイジェストで固定（タグの代わり）

digest を指定すると、出力は image: nginx@sha256:0000…0000 の形になりました。CI では kustomize edit set image でタグを書き換える使い方がよくあります。

cd overlays/prod
kustomize edit set image nginx=registry.example.com/web/nginx:1.27.4

labels と commonLabels（非推奨）

commonLabels は非推奨で、labels に置き換わりました。 v5.8.3 で commonLabels を使うと、build の先頭に次の警告が出ました。

# Warning: 'commonLabels' is deprecated. Please use 'labels' instead. Run 'kustomize edit fix' to update your Kustomization automatically.

Deployment の spec.selector は、作ったあとに変えられません。 commonLabels や includeSelectors: true で、すでに動いている Deployment にラベルを足すと、selector が変わって適用に失敗します。あとから足すラベルは includeSelectors: false にします。

kustomize edit add label も、何も付けないと commonLabels に書き込みました。--without-selector を付けると labels に書き込まれました。

kustomize edit add label env:staging --without-selector
# labels:
# - pairs:
#     env: staging

非推奨フィールドを一括で直す：kustomize edit fix

commonLabels・patchesStrategicMerge を使った kustomization.yaml で kustomize edit fix を実行すると、次のように書き換わりました。

Fixed fields:
  patchesJson6902 -> patches
  patchesStrategicMerge -> patches
  commonLabels -> labels

To convert vars -> replacements, run the command `kustomize edit fix --vars`

# 変換後
labels:
- includeSelectors: true
  pairs:
    team: shop
patches:
- path: p.yaml

commonLabels は includeSelectors: true の labels に変換され、selector に付く動きはそのままでした。bases も非推奨で、使うと # Warning: 'bases' is deprecated. Please use 'resources' instead. が出ました。

components：機能を部品にして複数の overlay で使う

Component は、複数の overlay で「付けたり外したり」したい設定をまとめる仕組みです。 監視用のアノテーションを部品にした例です。

# components/monitoring/kustomization.yaml
apiVersion: kustomize.config.k8s.io/v1alpha1
kind: Component
patches:
  - target:
      kind: Deployment
    patch: |-
      - op: add
        path: /spec/template/metadata/annotations
        value:
          prometheus.io/scrape: "true"
          prometheus.io/port: "9113"

# overlays/staging/kustomization.yaml
resources:
  - ../../base
components:
  - ../../components/monitoring

build すると、Deployment の Pod テンプレートに prometheus.io/scrape: "true" と prometheus.io/port: "9113" が付きました。kind: Component の apiVersion は v1alpha1 です。overlay（kind: Kustomization）との違いは、読み込んだ overlay の中で、overlay 自身の resources を対象に patch などを適用する点です。overlay ごとに components に書くかどうかで、機能を付け外しできます。

kustomize edit：kustomization.yaml をコマンドで書き換える

よく出るエラーと原因

どれも kustomize build の段階で出るエラーです。 クラスタに適用する前に、CI で全 overlay を build しておくと、マージ前に見つけられます。

# CI の例：全 overlay を build して、失敗したら止める
for d in overlays/*/; do
  echo "== $d"
  kustomize build "$d" > /dev/null || exit 1
done

Helm との違い

Helm の書き方は、関連記事「Helm入門｜チャートの作り方とコマンド一覧」で扱っています。

よくある質問

Q. kubectl apply -k と kustomize build | kubectl apply -f - は同じですか。 A. どちらも組み立てた YAML を適用します。違いは使われる Kustomize の版で、-k は kubectl に組み込まれた版、パイプは単体のバイナリの版です。新しいフィールドを使うときは、単体のバイナリの版で build してから渡すと、版の違いを避けられます。

Q. overlay から base 以外のディレクトリのファイルを読みたいです。 A. 既定では、kustomization.yaml のあるディレクトリより外のファイルを直接は読めません（--load-restrictor の既定は LoadRestrictionsRootOnly）。外のディレクトリは、そのディレクトリに kustomization.yaml を置いて resources で読み込みます。--load-restrictor LoadRestrictionsNone で外せますが、ヘルプには「kustomization の移動のしやすさが失われる」とあります。

Q. 値を別のリソースにコピーしたい（Service 名を環境変数に入れるなど）。 A. replacements を使います。以前の vars は非推奨で、kustomize edit fix --vars で変換できます。

Q. Git に置いた overlay を自動でクラスタに反映したいです。 A. Argo CD は、Application の source.path に kustomization.yaml があるディレクトリを指定すると、Kustomize として組み立てて同期します。関連記事「Argo CD入門｜Applicationの書き方と同期の仕組み」で扱っています。

Q. Kubernetes の YAML の書き方から確認したいです。 A. Deployment・Service などの基本は、関連記事「Kubernetes入門｜主要リソースとYAMLの書き方、kubectl早見表」で扱っています。

まとめ

• base に共通の YAML、overlay に差分。kustomize build で出力を確かめてから適用する
• images・replicas・namespace・namePrefix は専用のフィールドで書ける
• patches の name は base の名前で書く。JSON6902 は target が必須、番号の指定はずれに注意
• configMapGenerator は中身のハッシュを名前に付け、変えると Pod が入れ替わる
• commonLabels は非推奨で selector まで変える。labels を使い、kustomize edit fix で一括変換できる

参考・出典

確認日はいずれも 2026年10月13日です。

• Kustomize リファレンス「kustomization」（フィールド一覧）：https://kubectl.docs.kubernetes.io/references/kustomize/kustomization/
• Kustomize リファレンス「patches」：https://kubectl.docs.kubernetes.io/references/kustomize/kustomization/patches/
• Kustomize リファレンス「labels」：https://kubectl.docs.kubernetes.io/references/kustomize/kustomization/labels/
• Kustomize リファレンス「configMapGenerator」：https://kubectl.docs.kubernetes.io/references/kustomize/kustomization/configmapgenerator/
• Kustomize リファレンス「components」：https://kubectl.docs.kubernetes.io/references/kustomize/kustomization/components/
• kubernetes-sigs/kustomize（README・リリース v5.8.3）：https://github.com/kubernetes-sigs/kustomize
• Kubernetes ドキュメント「Declarative Management of Kubernetes Objects Using Kustomize」：https://kubernetes.io/docs/tasks/manage-kubernetes-objects/kustomization/

株式会社RJC ― SI事業・SES事業・AI駆動開発。RJCは一緒に成長を楽しめる会社です。