kustomization.yaml・とは？初心者にもわかる Kubernetes の設定ファイル入門共起語・同意語・対義語も併せて解説！

この記事を書いた人

高岡智則

年齢：33歳性別：男性職業：Webディレクター（兼ライティング・SNS運用担当）居住地：東京都杉並区・永福町の1LDKマンション出身地：神奈川県川崎市身長：176cm 体系：細身〜普通（最近ちょっとお腹が気になる）血液型：A型誕生日：1992年11月20日最終学歴：明治大学・情報コミュニケーション学部卒通勤：京王井の頭線で渋谷まで（通勤20分）家族構成：一人暮らし、実家には両親と2歳下の妹恋愛事情：独身。彼女は2年いない（本人は「忙しいだけ」と言い張る）

はじめに

kustomization.yaml は Kubernetes の設定をまとめてカスタマイズするためのファイルです。Kubernetes の現場では複数の YAML ファイルを組み合わせてアプリをデプロイしますが環境ごとに微妙に変わる部分がよくあります。そんなときに役立つのが kustomize でありその設定を指示するのが kustomization.yaml です。

このファイルを使うと同じアプリのマニフェストを環境別に重複を減らして管理できます。たとえば開発と本番でリソースの名前やラベルを変えたい場合に強力な仕組みを提供します。

kustomize とは何か

kustomize は kubectl などに組み込まれた機能の一つで YAML のマニフェストを組み合わせて最終的な Kubernetes マニフェストを作る仕組みです。kustomization.yaml がこの組み立て方を指示する役割を果たします。

実務では名前空間の変更や画像のリネームひとつを共通の設定から適用することが多くありそれを可能にするのが kustomize の特徴です。

基本の構成とよく使われるフィールド

kustomization.yaml では複数のフィールドを組み合わせて動作を決めます。最も基本的なものには resources の指定や共通ラベルの設定があります。

フィールド	説明
resources	適用する元の YAML ファイルのリスト
namePrefix	全リソースの名前の先頭につく文字列
nameSuffix	全リソースの名前の末尾につく文字列
commonLabels	全リソースに共通で適用されるラベル
commonAnnotations	全リソースに共通で適用される注釈
patchesStrategicMerge	構造的に変更を適用するパッチ
patchesJson6902	Json6902 形式のパッチを適用する設定
configMapGenerator	ConfigMap を自動生成する設定
secretGenerator	Secret を自動生成する設定
images	イメージの置換や更新を行う設定

ポイント kustomization.yaml は最終的なマニフェストを生成する前提となる指示書です。ここを工夫するだけで環境ごとの微調整が格段に楽になります。

使い方の流れ

まずは環境ごとに分けた YAML ファイルを準備します。次に kustomization.yaml を作成し resources にそのファイル名を列挙します。名前の前後に Prefix や Suffix を設定して識別を容易にします。最後に kubectl で -k オプションを使って適用します。例えば kubectl apply -k というコマンドで現在のディレクトリにある設定を適用します。

Overlay の考え方を使うと開発用と本番用の違いを別々のディレクトリで管理できます。共通の設定は上位のベースに置き変更点だけを差し込む形で運用するのが基本です。

実践上の注意点とよくある誤解

よくある誤解としては kustomize は単なるテンプレート機能だと思われがちですが実際にはリソースの再配置や共通設定の適用を強力にサポートします。もう一つの注意点はパッチの適用順序と適用対象の整合性です。複数のパッチを同時に適用すると思わぬ衝突が起きることがあるため順序と適用範囲を丁寧に管理しましょう。

実用的な簡易例

下記は簡易な構成の例を表にしたものです。実際のファイルは YAML 形式で作成しますがここではイメージとして説明します。resources にはデプロイ用とサービス用の YAML ファイルを列挙します。namePrefix で全体の名前を揃えます。configMapGenerator で設定値を自動的に作成する方法も紹介します。

設定例	説明
resources	デプロイとサービスの YAML ファイルを列挙
namePrefix	作成される全リソースの頭に付く文字列
configMapGenerator	設定値を ConfigMap として自動生成する
commonLabels	共通ラベルをすべてのリソースに適用

おわりに

kustomization.yaml は Kubernetes の運用を楽にする強力なツールです。最初は基本的なフィールドの使い方を覚え、徐々にパッチの活用や複数環境の管理へと広げていくのが良いでしょう。

kustomization.yamlの同意語

kustomization.yaml: Kustomize の設定を記述する YAML ファイル。リソースのベース、パッチ、変形などを定義する正式なファイル名です。
Kustomize 用設定ファイル: Kustomize でリソースをカスタマイズするための設定を YAML 形式で記述したファイル
Kustomize 設定ファイル: Kustomize の設定を YAML 形式でまとめたファイル
カスタマイズ設定ファイル: リソースのカスタマイズを定義した YAML ファイル
KUSTOMIZATION.YAML: 大文字表記の別形。基本的には kustomization.yaml と同一ファイルを指すがケース違いとして扱われることがある
YAML 形式の設定ファイル: Kustomize の設定を YAML 形式で保存したファイル
Kustomize 定義ファイル: Kustomize によるリソースの定義を集約したファイル
Kustomize 用 YAML ファイル: Kustomize の設定・パッチを YAML で記述したファイル
Kustomize 設定 YAML: Kustomize の設定を YAML 形式で表現したファイル
カスタマイズ YAML ファイル: リソースのカスタマイズ設定を YAML 形式で記述したファイル

kustomization.yamlの対義語・反対語

デフォルト設定ファイル: kustomization.yamlが提供するカスタマイズ機能を使わず、デフォルトの設定だけを含むファイルの意味です。
静的設定ファイル: 変更やパッチ、オーバーレイを使わず、固定の設定を記述したファイルの意味です。
非カスタマイズファイル: カスタマイズ（拡張・変更）を含まない、基本リソースのみを定義したファイルの意味です。
オーバーレイなし設定: Kustomizeのオーバーレイ機能を使わず、元のリソースにそのまま適用される設定の意味です。
直接適用ファイル: kustomizeを介さず、kubectl applyなどで直接適用する前提の設定ファイルの意味です。
カスタマイズ不要ファイル: 追加のパッチや変形を含まない、環境を問わず使えるファイルの意味です。
原状維持設定ファイル: 現状の状態を維持するための設定を記述したファイルの意味です。
デフォルトマニフェスト: 特定の環境依存の変更を排除した、デフォルトのKubernetesマニフェストの意味です。

kustomization.yamlの共起語

Kustomize: Kubernetes のリソースを宣言的に組み合わせてカスタマイズするツール。
kubectl: Kubernetes の公式 CLI。kustomize の処理を組み込んで実行できる。
resources: kustomization.yaml で参照する元ネタのリソースファイルやリソース群のリスト。
overlays: 環境ごとに異なる設定を分けて管理するディレクトリ構成（例: overlays/dev, overlays/prod）。
bases: 古い表現で、他の kustomization.yaml を参照する方法。現在は主に resources で代用。
patchesStrategicMerge: 戦略的マージパッチを適用する設定。複数リソースに同時適用可能。
patchesJson6902: JSON Patch 6902 形式のパッチを適用する設定。
namePrefix: 全リソース名の先頭に付ける接頭辞。
nameSuffix: 全リソース名の末尾に付ける接尾辞。
commonLabels: すべてのリソースに共通して付与するラベルのマッピング。
commonAnnotations: すべてのリソースに共通して付与するアノテーションのマッピング。
namespace: デフォルトのネームスペースを設定するためのオプション。
images: 対象コンテナのイメージ名とタグを置換・更新する設定。
configMapGenerator: ConfigMap を自動生成する設定。name、literals、files などを指定。
secretGenerator: Secret を自動生成する設定。name、literals、files を指定。
generatorOptions: ConfigMap/Secret の生成時の追加オプション。
apiVersion: Kubernetes API のバージョンを示す。kustomize 側の内部仕様にも影響。
kind: このファイルが Kustomization であることを示す識別子。
vars: リソース間で値を参照する変数定義。objref/fieldref で参照先を指定。
newName: images セクションで新しい名前へ置換する場合の指定。
newTag: images セクションで新しいタグを指定して更新する場合の指定。
literals: ConfigMap/Secret Generator で直接キー=value を列挙する形式。
files: ConfigMap/Secret Generator でファイルの内容を取り込む形式。
disableNameSuffixHash: generatorOptions の設定。リソース名のハッシュ付き接尾辞を付けないようにする。
yaml: kustomization.yaml は YAML 形式で記述する設定ファイル。

kustomization.yamlの関連用語

kustomize: Kubernetes マニフェストを環境別に安全にカスタマイズするツール。 overlays や patches などの仕組みで共通設定を再利用できる。
kustomization.yaml: Kustomize の設定ファイル。resources、patches、configMapGenerator などを宣言して、最終的なマニフェストを生成する。
apiVersion: kustomize.config.k8s.io/v1beta1 など、Kustomize の設定 API バージョンを示す値。
kind: Kustomization を表す Kubernetes の kind。kustomization.yaml 内で必須の要素。
resources: カスタマイズ対象となるリソースファイルのリスト。Deployment、Service などの YAML を列挙する。
bases: 過去の Kustomize で使われたベース参照。現在は主に resources で置換されるが後方互換のため残っている。
overlays: 環境別（dev/stage/prod など）ごとに設定を分けるディレクトリ構造。共通の base を上書きする形で管理する。
patchesStrategicMerge: 戦略的マージパッチを使って既存リソースの特定フィールドを上書きする。複数ファイルを指定可能。
patchesJson6902: JSON Patch (RFC 6902) 形式のパッチを適用する。対象リソースを細かく変更できる。
patches: パッチの集合を指す古い表現や、patchesStrategicMerge / patchesJson6902 の総称として使われることがある。
commonLabels: 全リソースに自動で付与する共通ラベルの定義。ラベルでのフィルタリングを容易にする。
commonAnnotations: 全リソースに自動で付与する共通注釈。監視や追跡に役立つ情報を一括付与できる。
namePrefix: リソース名の前方に共通のプレフィックスを追加して名前衝突を回避する。
nameSuffix: リソース名の末尾に共通のサフィックスを追加して識別性を高める。
namespace: 全リソースのデフォルトネームスペースを設定。名前空間を統一して管理を簡略化する。
images: イメージ名・タグの一括置換・更新。複数のリソースに跨るイメージ変更を一元管理できる。
configMapGenerator: ConfigMap を自動生成する設定。literals、files などを使って中身を取り込む。
secretGenerator: Secret を自動生成する設定。literals、files などを使って中身を取り込む。
literals: configMapGenerator / secretGenerator で key=value のリストとして定義する値。
files: configMapGenerator / secretGenerator でファイルの内容を取り込む指定。
generatorOptions: ConfigMap/Secret の生成に関する追加オプションの集合。
disableNameSuffixHash: 生成されるリソース名の末尾ハッシュを無効化して安定した名前にする設定。
transformers: リソース全体に対して追加の変換を適用する transformer ファイルの集合。
vars: 他のリソースの値を参照して、動的に値を代入する変数機能。テンプレート的な活用が可能。
objref: vars の元になるオブジェクトの参照情報。kind/ name / apiVersion などを含む。
fieldref: objref の対象フィールドを参照する情報。fieldPath で具体的なパスを指定する。
crds: CustomResourceDefinition の取り扱い設定。CRD の読み込み順や適用に関わる設定を指定する。