HelmとKustomize|環境ごとのマニフェスト管理

HelmとKustomize|環境ごとのマニフェスト管理

Kubernetes で同じアプリを開発環境と本番環境に出そうとすると、ほとんど同じなのに数か所だけ違う YAML が、環境の数だけ増えていきます。

違うのは Pod の数、コンテナイメージのタグ、ログの出し方、名前空間といった、ほんの一部です。

この「少しだけ違う」を扱う代表的な道具が Helm と Kustomize で、どちらもマニフェスト(Kubernetes のリソースを定義した YAML)を環境ごとに組み立てるために使われます。

2 つは目的が似ていても差分の持ち方がまったく違うので、そこが分かると使い分けにも説明がつきます。

Kubernetes そのものの仕組みは、次の記事で整理しています。

コンテナとKubernetes入門|DevOpsの土台

環境ごとにYAMLを複製すると差分が見えなくなる

いちばん素朴なやり方は、dev 用と prod 用のフォルダを作り、YAML を丸ごとコピーして書き換える方法です。

最初は分かりやすいのですが、共通の部分を直すたびに、すべてのコピーへ同じ修正を入れることになります。

1 か所でも直し忘れると、環境ごとの違いが意図した違いなのか、直し忘れなのかを区別できなくなります。

そこで、共通の部分を 1 か所に置き、環境ごとの違いだけを別に書いて組み立てる、という発想が生まれました。

Helm と Kustomize は、この「違いだけを書く」をそれぞれ別の方法で実現しています。

Helmは穴あきのテンプレートに値を流し込む

Helm は公式ドキュメントで「Kubernetes のパッケージマネージャー」と位置づけられていて、CNCF では 2020 年 5 月に Graduated の段階へ上がったプロジェクトです。

公式ドキュメントは、Helm の仕組みを chart・repository・release の 3 つで説明しています。

用語意味
chartアプリを動かすのに必要なリソース定義をひとまとめにしたパッケージ
repositorychart を集めて共有する置き場
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 公式ドキュメント)

Values Files(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 つの違いを、公式ドキュメントの説明をもとに表にまとめました。

観点HelmKustomize
差分の持ち方テンプレートの穴に値を入れる普通の YAML にパッチを重ねる
元の YAMLテンプレートなので、そのままでは適用できないそのまま適用できる
共有のしかたchart を repository で配るローカルやリモートのリポジトリにあるディレクトリを base として参照する
戻し方release の revision を指定して helm rollbackrelease に当たる仕組みは無い
必要なもの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 の考え方そのものは、次の記事で扱っています。

GitOps入門|Gitを「本番の正解」の置き場にする運用

Helm(Argo CD 公式ドキュメント)

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 を確かめることが、環境ごとの差を見落とさないいちばんの近道だと分かりました。

以上です。

コメントを残す

メールアドレスが公開されることはありません。 ※ が付いている欄は必須項目です

CAPTCHA