Kustomizeとは？base・overlaysの仕組みとHelmとの違い・導入判断を実装者目線で解説

Kustomizeは、Kubernetesのマニフェスト（YAML）をテンプレート化せず、宣言的に上書き（オーバーレイ）して環境差分を管理する構成管理ツールです。開発・ステージング・本番でほぼ同じ定義を使いながら、レプリカ数やイメージタグ、ConfigMapの値だけを差し替えたい——こうした要求に対し、元のYAMLを一切書き換えずに「差分ファイル」を重ねて解決します。kubectlに組み込まれており、追加バイナリなしで kubectl apply -k として使い始められる導入障壁の低さも特徴と言えます。

本稿は、これからKustomizeの採用を検討する実装者・技術選定者に向けて、base/overlaysの仕組みとkustomization.yamlの役割、ジェネレータやパッチといった主要機能、そしてHelmとの違いやGitOpsとの連携までを整理します。さらに、受託開発・インフラ構築の現場で「どういうチームがKustomizeを選ぶべきか、逆に見送るべき場面はどこか」を条件付きで言い切ります。

まとめ：Kustomizeの要点を先に押さえる

• テンプレートレスの上書き方式：Kustomizeは変数やテンプレート言語を持たず、素のKubernetes YAMLをbaseとして、環境別のoverlaysで差分だけを重ねる。元YAMLはそのまま kubectl に通る有効なマニフェストのまま保てる。
• kubectl組み込みで導入が軽い：kubectl apply -k ./overlays/prod のように追加ツールなしで使える。最新機能を追う場合は単体バイナリ（5系）を別途入れる選択もある。
• Helmとは設計思想が異なる：Helmはテンプレート＋値注入でパッケージを配布する仕組み、Kustomizeは既存YAMLへのパッチ適用。再配布パッケージが要るならHelm、自社アプリの環境差分整理ならKustomizeが噛み合う。
• GitOpsと相性が良い：ArgoCDやFlux（CD）はKustomizeをネイティブに解釈するため、Gitリポジトリの差分がそのまま環境反映の宣言になる。
• 採用判断の分岐点：管理対象がKubernetes限定で、テンプレートの動的分岐まではいらないなら第一候補。複雑な条件分岐やチャート配布が要件ならHelm、あるいは両者の併用を検討する。

Kustomizeが解決する課題：Kubernetesマニフェストの環境差分

Kubernetesにアプリをデプロイすると、DeploymentやService、ConfigMap、Ingressといった複数のマニフェストが必要になります。ここで避けにくいのが、環境ごとにほぼ同じだが少しだけ違うYAMLが増殖する問題です。本番はレプリカ3・リソース上限高め、開発はレプリカ1・デバッグ用の環境変数あり——といった差分を、YAMLを丸ごと複製して管理すると、共通部分の修正が全環境に波及したときに更新漏れが起きます。

この課題に対する古典的な回避策はスクリプトによる文字列置換でしたが、YAMLの構造を無視した置換は壊れやすく、レビューもしにくいものでした。Kustomizeは、共通定義（base）と環境差分（overlays）を明示的に分離し、Kubernetesが理解する構造レベルで差分を合成することで、この増殖と更新漏れを整理します。マニフェストそのものを構成管理の対象として扱う考え方は、構成管理とは？CMDB・IaC・ソフトウェア構成管理の違いと運用体制の作り方で整理した「あるべき状態を宣言し、差分を管理する」思想の、Kubernetes領域への具体化と捉えると理解しやすいはずです。

baseとoverlaysによる2層構造とディレクトリ構成の考え方

Kustomizeの中核は、base（土台）とoverlays（重ね合わせ）の2層構造です。baseには全環境共通のマニフェストと、それらを束ねる kustomization.yaml を置きます。overlaysには環境ごと（例：dev／staging／prod）のフォルダを作り、それぞれの kustomization.yaml でbaseを参照しつつ、その環境だけの差分を宣言します。

典型的なディレクトリは次のようになります。base側で共通のDeployment・Serviceを定義し、prodのoverlayではレプリカ数を上げるパッチだけを足す、という構成です。

myapp/
  base/
    deployment.yaml
    service.yaml
    kustomization.yaml      # resources: に上2つを列挙
  overlays/
    dev/
      kustomization.yaml    # ../../base を参照＋dev差分
    prod/
      kustomization.yaml    # ../../base を参照＋prod差分
      replica-patch.yaml    # レプリカ数を上書きするパッチ

デプロイ時は環境フォルダを指すだけです。kubectl apply -k overlays/prod とすれば、baseとprodの差分が合成された最終マニフェストが適用されます。合成結果を適用前に確認したいときは kubectl kustomize overlays/prod で標準出力にレンダリングできるため、CIでの差分レビューにも向きます。

kustomization.yamlで押さえておく主要フィールド一覧

Kustomizeの挙動はすべて kustomization.yaml の宣言で決まります。実装で頻出するフィールドを、役割ごとに押さえておきます。

• resources：合成の対象にするマニフェスト（またはbaseディレクトリ）を列挙する。overlaysでは ../../base のように相対参照する。
• patches（旧patchesStrategicMerge / patchesJson6902）：既存リソースの一部フィールドだけを上書きする差分。5系では patches に一本化され、対象リソースを target で絞り込める。
• namePrefix / nameSuffix：生成する全リソース名に接頭辞・接尾辞を付与する。環境名を機械的に付けて衝突を避ける用途に向く。
• commonLabels / labels：全リソースへ共通ラベルを一括付与する。セレクタとの整合も自動で取られる。
• images：コンテナイメージ名やタグを一括で差し替える。prodだけ特定タグに固定する、といった制御を宣言的に書ける。
• namespace：合成対象を特定のNamespaceにまとめて配置する。

これらはいずれも元のマニフェストを書き換えず、合成時に適用される点が肝心です。baseは常にレビュー済みの「正」であり続け、環境差分はoverlays側の宣言に閉じ込められます。

ジェネレータ：ConfigMapとSecretを定義から生成する

Kustomizeの実用性を押し上げているのが、configMapGeneratorとsecretGeneratorです。プロパティファイルやリテラル値からConfigMap／Secretを生成でき、生成物には内容のハッシュが付いた名前（例：app-config-abc123）が自動で付与されます。

このハッシュ付与が効くのは、設定変更時のローリング更新です。ConfigMapの中身が変わればハッシュが変わり、参照側のDeploymentも新しい名前を指すよう自動で書き換えられるため、Podが確実に再作成されます。ConfigMapを同名のまま更新するとPodが古い値を掴んだまま——という取りこぼしを、仕組みで防げるわけです。generatorOptions でハッシュ付与を無効化することもできますが、更新を確実に反映させたい設定では既定のハッシュ挙動を残すのが無難です。

transformerとcomponents：再利用の単位を広げる

namePrefixやcommonLabels、imagesといった一括変換は、内部的にはKustomizeのtransformer（変換器）が担っています。標準の変換器で足りない場合はカスタム変換器を差し込む拡張点もありますが、多くの現場では標準機能で十分です。

もう一段進んだ再利用の単位がcomponentsです。「監視を有効化する」「特定のサイドカーを足す」といった機能単位のオン／オフを部品化し、必要なoverlayからだけ読み込めます。dev／stagingには入れず、prodだけに監視コンポーネントを足す、といった構成を、overlayごとの差分としてではなく再利用可能な部品として表現できるため、環境が増えても宣言が肥大化しにくくなります。

KustomizeとHelmの違いと選定の判断基準を整理する

Kubernetesのマニフェストをまとめるツールとしてよく比較されるのがHelmです。両者は目的が重なる場面もありますが、設計思想は明確に異なります。Helm自体の仕組みはHelmとは？チャート・リポジトリ・リリースの基本とhelm repo addなど主要コマンド解説で詳説していますが、選定の勘所を対比で整理します。

判断の軸はシンプルです。第三者へ再配布するパッケージや、値による動的な条件分岐が要件ならHelmが噛み合うでしょう。逆に、自社が管理するアプリの、環境ごとの差分を素のYAMLのまま整理したいならKustomizeが向くはずです。両者は排他ではなく、Helmでチャートを展開した結果にKustomizeでパッチを当てる併用（helm template の出力をbaseにする、あるいはHelmチャートをKustomizeから参照する）も現場では珍しくありません。テンプレートの読みにくさを避けたいチームがまずKustomizeから入る、という選び方は理にかなっています。

GitOpsとの連携：ArgoCD・FluxにおけるKustomizeの位置づけ

Kustomizeの価値が際立つのがGitOps運用です。ArgoCDやFluxといったCDツールは、Kustomizeをネイティブに解釈します。overlaysディレクトリを指定しておけば、Gitリポジトリ上のkustomization.yamlの変更がそのまま「あるべき状態」の宣言となり、CDツールがクラスタとの差分を検知して同期します。

つまり、環境差分の管理（Kustomize）と、その差分をクラスタへ届ける仕組み（GitOps）が、YAMLを共通言語として自然につながるわけです。ArgoCDでの継続的デリバリーの組み立て方はArgoCDとは？GitOpsによるKubernetes継続的デリバリーの仕組みと導入判断を実装者目線で解説で、Gitに依存しない新しい配信方式はGitless GitOpsとは？OCIレジストリ中心のGitOps新方式を仕組み・導入まで解説で扱っています。KustomizeはこれらCDパイプラインの「入力」を宣言的に整える役割を担います。

【独自章】受託・自社開発でKustomizeを採用すべき条件と見送る場面

ツールの機能は公式ドキュメントで確認できます。ここでは、受託開発・インフラ構築の現場でチームがKustomizeを入れるべきか否かを、条件付きで言い切ります。

Kustomizeの採用を積極的に推せるプロジェクトの前提条件

• 管理対象がKubernetesに閉じている：KustomizeはKubernetesマニフェスト専用の道具。クラスタ内の構成差分を整理する用途なら、追加ツールなしで始められる利点がそのまま効く。
• テンプレートの動的分岐までは不要：環境ごとの差分がレプリカ数・イメージタグ・設定値・ラベルといった「値の差し替え」に収まるなら、テンプレート言語を持ち込むより宣言的なパッチのほうが読みやすくレビューしやすい。
• GitOpsを前提に運用する：ArgoCD／Fluxと組む予定があるなら、Kustomizeネイティブ対応の恩恵で配線が減る。
• YAMLの可読性を保ちたい：baseが常に有効なマニフェストとして残るため、Kustomizeを知らないメンバーでも kubectl kustomize の出力を読めば挙動を追える。属人化を抑えたいチームに向く。

Kustomizeを見送る・Helmとの併用を検討すべき場面

• 第三者へのパッケージ再配布が要件：バージョン付きで配布し、利用側が値を注入して使う形が必要ならHelmが噛み合う。無理にKustomizeへ寄せると配布・依存管理が手薄になる。
• 複雑な条件分岐・ループが避けられない：生成物が入力値によって大きく形を変えるなら、テンプレートを持つHelmのほうが素直に書ける。パッチの重ね掛けで表現し切ろうとすると、かえって追いにくくなる。
• 差分が数値・タグに収まらず構造ごと変わる：環境間で構成そのものが別物なら、overlaysで差分を吸収する前提が崩れる。この場合は環境ごとに独立管理するか、Helm併用を検討する。
• Kubernetes以外の構成管理も一元化したい：サーバーやネットワークまで含めた構成管理は、IaCとは？Infrastructure as Codeの仕組み・メリットと導入判断を解説で扱うIaCツールの領分。KustomizeはKubernetes内の差分管理に役割を絞るのが健全。

過剰投資を避ける観点では、小規模で環境が1〜2種類しかない段階から重厚なテンプレート機構を入れる必要はありません。まずKustomizeのbase/overlaysで差分を整理し、配布要件やテンプレート要件が現実に立ち上がった時点でHelm併用へ広げる——という段階的な進め方が、運用コストと表現力のバランスを取りやすい選択です。前提となるKubernetesそのものの仕組みはKubernetes（クバネティス）とは？仕組み・Dockerとの違い・読み方をわかりやすく解説で確認できます。

KubernetesクラスタやCDパイプラインの設計・構築を含めたインフラ整備を外部と組んで進めたい場合は、一創のインフラ構築（AWS・Google Cloud・Azure）で、環境差分の管理方針からGitOps運用体制まで一体で相談できます。

Kustomize導入時の注意点とバージョン差の考え方と固定方針

Kustomizeは kubectl に組み込まれていますが、kubectl同梱版と単体バイナリ版でバージョンが異なる点に注意します。kubectlに含まれるKustomizeは、そのkubectlのリリース時点のバージョンに固定されるため、単体バイナリの最新（5系）で使える機能が同梱版では未対応、という食い違いが起こり得ます。CIやローカルで最新機能を使うなら、単体バイナリのバージョンをチームで揃えるのが安全です。

Kustomizeは本稿執筆時点で5系（v5系）が提供されており、patchesStrategicMerge などの旧フィールドは patches へ統合が進んでいます。導入時は使用するバージョンを固定し、kustomization.yaml のスキーマ（apiVersion）を明示しておくと、将来のバージョン差による挙動変化を追いやすくなります。版番号や対応状況は公式リポジトリの一次情報で都度確認してください。

よくある質問

Kustomizeを使うのに追加インストールは必要ですか？

基本的には不要です。kubectl apply -k や kubectl kustomize でkubectl組み込みのKustomizeを使えます。ただし同梱版はkubectlのバージョンに追随するため、単体バイナリの最新機能を使いたい場合は別途バイナリを導入します。

KustomizeとHelmはどちらかを選ばないといけませんか？

いいえ、併用できます。自社アプリの環境差分整理はKustomize、OSSミドルの配布・受け入れはHelm、と役割で使い分ける現場は多く、Helmの展開結果にKustomizeでパッチを当てる構成も可能です。再配布や動的分岐の要件があるかどうかが選定の分かれ目です。

base・overlaysは必ず分けないといけませんか？

単一環境なら単一のkustomization.yamlだけでも動きますが、複数環境の差分管理こそがKustomizeの主眼です。環境が増える見込みがあるなら、最初からbaseとoverlaysに分けておくと後の破綻を防げます。

ConfigMapを更新してもPodが再起動しないのはなぜですか？

configMapGeneratorを使うと生成物に内容ハッシュが付き、設定変更時に参照側の名前も変わってPodが再作成されます。手書きのConfigMapを同名更新している場合は再起動が走らないため、ジェネレータ経由に切り替えると取りこぼしを防げます。

Kustomizeはテンプレート変数を使えますか？

Kustomizeは設計上テンプレート言語を持たず、変数展開ではなく宣言的なパッチで差分を表現します。動的な条件分岐やループが必要な場合は、テンプレートを持つHelmの併用を検討してください。

関連記事

• Kubernetes（クバネティス）とは？仕組み・Dockerとの違い・読み方をわかりやすく解説
• Helmとは？チャート・リポジトリ・リリースの基本とhelm repo addなど主要コマンド解説
• ArgoCDとは？GitOpsによるKubernetes継続的デリバリーの仕組みと導入判断を実装者目線で解説
• Gitless GitOpsとは？OCIレジストリ中心のGitOps新方式を仕組み・導入まで解説
• 構成管理とは？CMDB・IaC・ソフトウェア構成管理の違いと運用体制の作り方
• IaCとは？Infrastructure as Codeの仕組み・メリットと導入判断を解説