Kubernetes で同じアプリを開発環境と本番環境に出そうとすると、ほとんど同じなのに数か所だけ違う YAML が、環境の数だけ増えていきます。
違うのは Pod の数、コンテナイメージのタグ、ログの出し方、名前空間といった、ほんの一部です。
この「少しだけ違う」を扱う代表的な道具が Helm と Kustomize で、どちらもマニフェスト(Kubernetes のリソースを定義した YAML)を環境ごとに組み立てるために使われます。
2 つは目的が似ていても差分の持ち方がまったく違うので、そこが分かると使い分けにも説明がつきます。
Kubernetes そのものの仕組みは、次の記事で整理しています。
環境ごとにYAMLを複製すると差分が見えなくなる
いちばん素朴なやり方は、dev 用と prod 用のフォルダを作り、YAML を丸ごとコピーして書き換える方法です。
最初は分かりやすいのですが、共通の部分を直すたびに、すべてのコピーへ同じ修正を入れることになります。
1 か所でも直し忘れると、環境ごとの違いが意図した違いなのか、直し忘れなのかを区別できなくなります。
そこで、共通の部分を 1 か所に置き、環境ごとの違いだけを別に書いて組み立てる、という発想が生まれました。
Helm と Kustomize は、この「違いだけを書く」をそれぞれ別の方法で実現しています。
Helmは穴あきのテンプレートに値を流し込む
Helm は公式ドキュメントで「Kubernetes のパッケージマネージャー」と位置づけられていて、CNCF では 2020 年 5 月に Graduated の段階へ上がったプロジェクトです。
公式ドキュメントは、Helm の仕組みを chart・repository・release の 3 つで説明しています。
| 用語 | 意味 |
|---|---|
| chart | アプリを動かすのに必要なリソース定義をひとまとめにしたパッケージ |
| repository | chart を集めて共有する置き場 |
| release | クラスタにインストールされた chart の実体で、同じ chart を 2 回入れれば release も 2 つになる |
chart の中身は、メタ情報を書く Chart.yaml、既定値を書く values.yaml、マニフェストのひな形を置く templates/ が中心です。
templates/ の中の YAML は Go のテンプレート言語で書かれていて、値を入れたい場所に {{ .Values.replicaCount }} のような穴を空けておきます。
次の例は、Docker の alpine/helm イメージ(Helm v4.3.1)で helm template を実行し、出力を確かめた chart からの抜粋です。
# templates/deployment.yaml(抜粋)
spec:
replicas: {{ .Values.replicaCount }}
template:
spec:
containers:
- name: web
image: "{{ .Values.image.repository }}:{{ .Values.image.tag }}"
# 略
# values-prod.yaml(本番だけ変える値)
replicaCount: 3
image:
tag: "1.28"
# 本番の値でマニフェストを描き出して確かめる
helm template web ./web-chart -f values-prod.yaml
chart 側の values.yaml は Pod の数を 1、タグを 1.27 にしてあり、描き出された Deployment は replicas: 3 と nginx:1.28 になりました。
値の優先順位も公式ドキュメントに書かれていて、chart の values.yaml が既定値、-f で渡したファイルがそれを上書きし、--set がさらにその上に来ます。
-f は何度も指定でき、右に書いたファイルほど優先されます。
この順番があるので、共通の値は values.yaml に置き、values-dev.yaml や values-prod.yaml には環境の差だけを書く、という分け方がしやすくなっています。
もう 1 つの特徴は、インストールの結果が release の履歴として残り、helm rollback で前の revision に戻せることです。
なお、Helm はすでに Helm 4 が出ていて、公式ドキュメントは 4.3.1 の版になっています(2026 年 10 月 19 日に参照)。
値の優先順位を説明したページには「まだ Helm 4 向けに更新されていない」という注記が付いているので、Helm 4 で使うときは Helm 4 Overview もあわせて確かめてください。
Introduction to Helm(Helm 公式ドキュメント)
Kustomizeはテンプレートを使わず元のYAMLに上書きを重ねる
Kustomize は、kustomization.yaml というファイルで Kubernetes のオブジェクトを組み立てる単体のツールです。
Kubernetes 1.14 からは kubectl にも組み込まれていて、kubectl kustomize で組み立てた結果を表示し、kubectl apply -k で適用できます。
Helm と違って元の YAML に穴を空けず、そのまま適用できる普通の YAML として置いておけるのが持ち味です。
共通の YAML を置くディレクトリを base、環境ごとの差分を置くディレクトリを overlay と呼びます。
base は overlay の存在を知らないので、1 つの base を複数の overlay から使い回せます。
手元で、base に Deployment を 1 つ置き、prod の overlay で名前空間・イメージのタグ・Pod の数・設定値を変える構成を組んでみました。
確認した環境は、Docker Desktop に同梱されている kubectl v1.36.1(組み込みの Kustomize は v5.8.1)で、クラスタへの適用はせず組み立ての結果だけを見ています。
# overlays/prod/kustomization.yaml
resources:
- ../../base
namespace: prod
images:
- name: nginx
newTag: "1.28"
patches:
- target:
kind: Deployment
name: web
patch: |-
- op: replace
path: /spec/replicas
value: 3
configMapGenerator:
- name: web-config
literals:
- LOG_LEVEL=warn
base の Deployment は replicas: 1 と image: nginx:1.27 で、コンテナは web-config という名前の ConfigMap から環境変数を読む設定にしてあります。
kubectl kustomize overlays/prod の出力から、Deployment の部分を抜き出したものが次です。
metadata:
name: web
namespace: prod
spec:
replicas: 3
# 略
containers:
- envFrom:
- configMapRef:
name: web-config-dfk4bdbtkk
image: nginx:1.28
name: web
名前空間・Pod の数・タグが overlay の指定どおりに変わっていて、base のファイルは 1 文字も書き換えていません。
ConfigMap の名前の後ろに付いた -dfk4bdbtkk は、中身から計算されたハッシュです。
試しに LOG_LEVEL を error に変えて組み立て直すと、名前は web-config-68d5cgcdf4 に変わり、Deployment 側の参照も新しい名前に書き換わりました。
Kubernetes の Deployment は、Pod のテンプレートが変わったときにだけ入れ替え(ロールアウト)を始めます。
設定値を変えると参照する名前が変わり、Pod のテンプレートも変わるので、新しい設定の Pod へ入れ替わる仕組みになっています。
Declarative Management of Kubernetes Objects Using Kustomize(kubernetes.io)
配る側か受け取る側かで考えると選びやすい
2 つの違いを、公式ドキュメントの説明をもとに表にまとめました。
| 観点 | Helm | Kustomize |
|---|---|---|
| 差分の持ち方 | テンプレートの穴に値を入れる | 普通の YAML にパッチを重ねる |
| 元の YAML | テンプレートなので、そのままでは適用できない | そのまま適用できる |
| 共有のしかた | chart を repository で配る | ローカルやリモートのリポジトリにあるディレクトリを base として参照する |
| 戻し方 | release の revision を指定して helm rollback | release に当たる仕組みは無い |
| 必要なもの | helm コマンド | kubectl に同梱(1.14 以降) |
Helm の公式ドキュメントは、chart を apt や Homebrew のパッケージにたとえています。
この設計が向いているのは、多くの人に同じアプリを配り、受け取る側には値だけを変えてもらう用途です。
公開されている chart は、Artifact Hub で探せます。
一方で Kustomize は、自分たちのアプリの YAML を自分たちで持っていて、環境ごとの差を少しだけ足したい用途に合っています。
2 つは組み合わせることもでき、Kustomize には helmCharts という欄で chart を描き出し、その上にパッチを重ねる機能があります。
ただし、この機能を使うには組み立てのコマンドに --enable-helm を付ける必要があり、手元の kubectl kustomize --help でも既定値は false でした。
つまずきやすいところ
ここからは、公式ドキュメントに書かれている注意点を中心に、環境ごとの管理で引っかかりやすいところを 4 つ挙げます。
環境の差を –set に書くとGitに残らない
Helm の公式ドキュメントによると、--set で指定した値は Secret に保存されます。
保存先はクラスタの中なので、リポジトリには残らず、レビューの対象からも外れます。
環境の差は values ファイルに書いて Git で管理しておくと、どの環境に何を入れたのかを後から追いかけやすくなります。
GitOpsのツールではHelmはテンプレートの展開だけに使われる
Argo CD の公式ドキュメントは、Helm を helm template で chart を展開するためだけに使い、アプリのライフサイクルは Argo CD が受け持つと書いています。
Helm のフックは Argo CD のフックに読み替えられますが、意味がまったく同じになる保証ではない、という注意も添えられています。
また、randAlphaNum のように呼ぶたびにランダムな値を作るテンプレートは、比較のたびに値が変わるので、いつまでも OutOfSync(Git とずれている状態)のままになると書かれています。
Argo CD での回避策として案内されているのは、その値を values ファイルなどで明示的に固定する方法です。
GitOps の考え方そのものは、次の記事で扱っています。
Kustomizeのハッシュを外すと設定を変えてもPodが入れ替わらない
ConfigMap の名前に付くハッシュは、generatorOptions の disableNameSuffixHash: true で外せます。
外すと名前が変わらなくなるので、ConfigMap の中身を変えても Deployment の Pod のテンプレートは変わりません。
その結果、ロールアウトが始まらず、Pod は古い設定のまま動き続けます。
ハッシュは見た目が少しうるさいものの、設定の変更を Pod の入れ替えにつなげる役目を持っています。
baseの変更はすべての環境に効く
base は overlay を知らないので、base を直すと dev にも prod にも同時に効きます。
共通部分を 1 か所にまとめた利点の裏返しで、本番だけ変えたつもりの修正が開発環境にも入ってしまうことがあります。
base を直したあとは、overlay ごとに kubectl kustomize を実行し、組み立てた結果の差を見てから適用すると見落としを減らせます。
最後に
Helm は穴あきのテンプレートに値を流し込み、Kustomize は普通の YAML に上書きを重ねる、という差分の持ち方の違いが、使い分けの出発点になります。
配られた chart を使うなら Helm、自分たちの YAML に環境の差を足すなら Kustomize、と考えると選びやすくなります。
私も学んでいる途中ですが、どちらの道具でも、適用する前に組み立てた結果の YAML を確かめることが、環境ごとの差を見落とさないいちばんの近道だと分かりました。
以上です。










コメントを残す