Helm入門｜チャートの作り方とコマンド一覧

Helm は、Kubernetes の YAML 一式を「チャート」という部品にまとめ、値（values）を変えて何度でも入れられるようにする道具です。 入れたものは「リリース」として版（リビジョン）が記録され、1つのコマンドで前の版に戻せます。

helm create mychart                                   # チャートの雛形を作る
helm lint mychart                                     # 書き方を検査する
helm template myapp mychart -f values-dev.yaml        # YAML を出力して確かめる（クラスターに入れない）
helm install myapp ./mychart -n web --create-namespace -f values-dev.yaml   # 入れる
helm upgrade myapp ./mychart -n web -f values-dev.yaml --set replicaCount=2 # 更新する
helm history myapp -n web                             # 版の一覧
helm rollback myapp 3 -n web                          # 版 3 に戻す
helm uninstall myapp -n web                           # 消す

確認環境：Helm v4.1.4（Go 1.26.5 でビルドされたもの）、k3s v1.36.5+k3s1（Kubernetes 1.36.5）の1ノードのクラスター、Ubuntu 24.04 で動かしました。OCI レジストリは CNCF Distribution 3.1.2 をローカルで動かしています。Helm 3 との違いと Helm 3 のサポート期限は、Helm の公式ドキュメントとブログで確かめています（確認日 2026年10月13日）。

Helm の用語

flowchart LR
    C["チャート<br/>templates/ + values.yaml"] --> R["helm template / install"]
    V["-f values-dev.yaml<br/>--set key=value"] --> R
    R --> M["描画された YAML"]
    M --> K["Kubernetes API"]
    K --> S["リリースの記録<br/>Secret: sh.helm.release.v1.名前.v版"]

リリースの記録は、リリースと同じ名前空間の Secret に入ります。 手元でも sh.helm.release.v1.myapp.v9 のような Secret が版ごとにでき、ラベルに status=deployed などの状態が入っていました。残す版の数は --history-max で決まり、既定は10です。

インストール

Helm は kubectl と同じ ~/.kube/config（または環境変数 KUBECONFIG）でクラスターにつなぎます。名前空間は -n で指定し、省略すると今のコンテキストの名前空間になります。

チャートを作る：helm create

helm create mychart

mychart
├── .helmignore              # package に入れないファイル
├── Chart.yaml               # チャートの名前・版
├── charts/                  # 依存するチャート（サブチャート）
├── templates/
│   ├── NOTES.txt            # install 後に表示する案内
│   ├── _helpers.tpl         # 共通の部品（名前・ラベル）
│   ├── deployment.yaml
│   ├── hpa.yaml
│   ├── httproute.yaml       # Gateway API
│   ├── ingress.yaml
│   ├── service.yaml
│   ├── serviceaccount.yaml
│   └── tests/
│       └── test-connection.yaml   # helm test で動く Pod
└── values.yaml              # 既定値（161行）

# Chart.yaml（コメントを除いたもの）
apiVersion: v2
name: mychart
description: A Helm chart for Kubernetes
type: application
version: 0.1.0          # チャートの版。中身を変えたら上げる
appVersion: "1.16.0"    # 入れるアプリの版。image.tag を空にするとこれが使われる

自分のアプリ用に直す

雛形の Deployment は nginx を動かす前提で、command も環境変数もありません。値で変えたい所を values.yaml に足し、テンプレートで読むようにします。 手元では、起動コマンドと ConfigMap を足しました。

# templates/deployment.yaml（imagePullPolicy の下に足した部分）
          imagePullPolicy: {{ .Values.image.pullPolicy }}
          {{- with .Values.command }}
          command:
            {{- toYaml . | nindent 12 }}
          {{- end }}
          envFrom:
            - configMapRef:
                name: {{ include "mychart.fullname" . }}

# templates/configmap.yaml（新しく作ったファイル）
apiVersion: v1
kind: ConfigMap
metadata:
  name: {{ include "mychart.fullname" . }}
  labels:
    {{- include "mychart.labels" . | nindent 4 }}
data:
  APP_ENV: {{ .Values.env | default "dev" | quote }}
  LOG_LEVEL: {{ .Values.config.logLevel | upper | quote }}
  FEATURES: {{ join "," .Values.config.featureFlags | quote }}
  RELEASE: {{ printf "%s-%s" .Release.Name .Chart.Version | quote }}
  NAMESPACE: {{ .Release.Namespace | quote }}
  {{- if eq (.Values.env | default "dev") "prod" }}
  CACHE_TTL: "3600"
  {{- else }}
  CACHE_TTL: "0"
  {{- end }}

# values.yaml に足した部分
command: []

config:
  logLevel: info
  featureFlags:
    - search
    - export

{{- と -}} の - は、その側の空白と改行を消します。 nindent 12 は「改行してから12文字字下げ」です。YAML は字下げで構造が決まるので、toYaml の結果は nindent で位置を合わせます。

確かめる：helm lint と helm template

helm lint mychart

==> Linting mychart
[INFO] Chart.yaml: icon is recommended

1 chart(s) linted, 0 chart(s) failed

helm template myapp mychart -s templates/configmap.yaml    # -s で1ファイルだけ出す

---
# Source: mychart/templates/configmap.yaml
apiVersion: v1
kind: ConfigMap
metadata:
  name: myapp-mychart
  labels:
    helm.sh/chart: mychart-0.1.0
    app.kubernetes.io/name: mychart
    app.kubernetes.io/instance: myapp
    app.kubernetes.io/version: "1.16.0"
    app.kubernetes.io/managed-by: Helm
data:
  APP_ENV: "dev"
  LOG_LEVEL: "INFO"
  FEATURES: "search,export"
  RELEASE: "myapp-0.1.0"
  NAMESPACE: "default"
  CACHE_TTL: "0"

--set env=prod --set config.logLevel=warn を付けると、APP_ENV: "prod"、LOG_LEVEL: "WARN"、CACHE_TTL: "3600" に変わりました。

helm template は、クラスターの版を知らないので既定の版で描画します。 手元の Helm 4.1.4 では .Capabilities.KubeVersion.Version が v1.35.0 になり、--kube-version 1.36.5 を付けると v1.36.5 になりました。版で分岐するチャートでは --kube-version を付けて確かめます。

values の上書きの優先順位

-f は後ろに書いたファイルが勝ち、--set 系は -f より強くなります。 手元で、values.yaml（logLevel: info）、values-prod.yaml（env: prod、logLevel: warn）、values-local.yaml（logLevel: debug）を組み合わせた結果です。

--set 系どうしは、書いた順番ではなく種類で強さが決まります。 --set-string を --set より前に書いても --set-string が勝ちました。手元で確かめた強さの順です。

弱い  チャートの values.yaml
 ↓    親チャートの values.yaml（サブチャートのとき）
 ↓    -f / --values（後ろに書いたものほど強い）
 ↓    --set-json
 ↓    --set（同じ種類どうしは後ろが勝つ）
 ↓    --set-string
 ↓    --set-file
強い  --set-literal

--set の書き方

数字だけのタグやバージョンは --set-string で渡します。 公式ドキュメントでは、既定値のキーを消すには null を入れると説明されています（例：livenessProbe.httpGet を消して exec の probe に替える）。

入れる・更新する・戻す

helm install

helm install myapp ./mychart -n web --create-namespace -f values-dev.yaml --wait --timeout 2m

# values-dev.yaml（手元では BusyBox の httpd を動かした）
image:
  repository: rancher/mirrored-library-busybox
  tag: "1.37.0"
command: ["sh", "-c", "mkdir -p /www && echo ok > /www/index.html && exec httpd -f -p 80 -h /www"]

--wait を付けると、Pod が Ready になるまで待ち、--timeout を過ぎると失敗にします。 手元では1回目、ノードが空き容量不足（DiskPressure）で Pod を置けず、2分後に次のエラーで failed になりました。

Error: INSTALLATION FAILED: resource Deployment/web/myapp-mychart not ready. status: InProgress, message: Available: 0/1
context deadline exceeded

failed のリリースは、同じ名前で helm upgrade すると続きから直せます。原因を直して upgrade すると、版 2 で STATUS: deployed になりました。

helm upgrade と helm history

helm upgrade myapp ./mychart -n web -f values-dev.yaml --set replicaCount=2 --wait --timeout 2m
helm history myapp -n web

REVISION  UPDATED                   STATUS      CHART          APP VERSION  DESCRIPTION
1         Tue Oct 13 13:13:03 2026  superseded  mychart-0.1.0  1.16.0       Release "myapp" failed: resource Deployment/web/myapp-mychart not ready. ...
2         Tue Oct 13 13:18:54 2026  superseded  mychart-0.1.0  1.16.0       Upgrade complete
3         Tue Oct 13 13:18:54 2026  deployed    mychart-0.1.0  1.16.0       Upgrade complete

helm upgrade に --set だけを渡すと、前回の -f の値は引き継がれません。 手元で --dry-run=client を付けて試した結果です。

値を何も渡さなければ前回の値を使い、1つでも渡すとチャートの既定値から作り直します。 毎回 -f values-dev.yaml を付けるのが確実です。--reuse-values は前回の値をそのまま使うので、チャートの values.yaml に新しく足したキーが入りません。--reset-then-reuse-values は「新しいチャートの既定値に、前回の値を重ねる」動きです。

helm get values myapp -n web                 # 利用者が渡した値
helm get values myapp -n web --all           # 既定値も含めた全部
helm get values myapp -n web --revision 2    # 版 2 のときの値
helm get manifest myapp -n web               # 入れた YAML
helm upgrade --install myapp ./mychart -n web -f values-dev.yaml   # 無ければ install、あれば upgrade（CI で使う）

helm rollback

失敗した更新は、--rollback-on-failure（Helm 3 の --atomic）を付けると自動で前の版に戻ります。 手元で存在しないタグ 9.9.9 に更新した結果です。

helm upgrade myapp ./mychart -n web -f values-dev.yaml --set image.tag=9.9.9 --rollback-on-failure --timeout 40s

Error: UPGRADE FAILED: release myapp failed, and has been rolled back due to rollback-on-failure being set: resource Deployment/web/myapp-mychart not ready. status: InProgress, message: Pending termination: 1
context deadline exceeded

REVISION  STATUS      DESCRIPTION
4         failed      Upgrade "myapp" failed: resource Deployment/web/myapp-mychart not ready. ...
5         deployed    Rollback to 3

手で戻すときは、戻したい版の番号を指定します。戻すと、新しい版の番号が増えます（版 3 に戻すと版 7 ができる）。

helm rollback myapp 3 -n web --wait
# Rollback was a success! Happy Helming!

helm uninstall

helm uninstall myapp -n web                  # リソースと記録を消す
helm uninstall myapp -n web --keep-history   # 記録を残す（helm list --uninstalled で見られる）

パッケージにして配る：helm package と OCI

helm package mychart                                  # Chart.yaml の version で作る
helm package mychart --version 0.2.0 --app-version 2.0.0

Successfully packaged chart and saved it to: （今いるフォルダ）/mychart-0.1.0.tgz

手元では 5,344 バイトの mychart-0.1.0.tgz ができ、.helmignore に書いたもの（.git/・*.swp・.vscode/ など）は入りませんでした。

チャートは、コンテナイメージと同じ OCI レジストリに置けます。 手元のレジストリ（http）に push し、そこから install できました。ECR・GHCR・Docker Hub・Artifact Registry も OCI レジストリとして使えます。

helm push mychart-0.1.0.tgz oci://localhost:5000/charts --plain-http
# Pushed: localhost:5000/charts/mychart:0.1.0
helm show chart oci://localhost:5000/charts/mychart --version 0.1.0 --plain-http
helm install myapp oci://localhost:5000/charts/mychart --version 0.1.0 --plain-http -n web -f values-dev.yaml

--plain-http は TLS なしのレジストリ用です。通常のレジストリでは付けません。認証が要るレジストリは helm registry login でログインします。

テンプレート関数の早見表

手元で helm template を動かして得た結果です（values：name: " My App "、tag: ""、port: 8080、debug: false、labels: {team: web, tier: front}、hosts: [a.example.com, b.example.com]）。

よく使う組み込みの値

Helm 3 と Helm 4 の違い

Helm 4 は 2025年11月に出ました。 Helm の公式ブログでは、Helm 3 のバグ修正は 2026年9月9日まで、セキュリティ修正は 2027年2月10日までと案内されています。

Helm 4 で新しく入れたリリースは、サーバー側の適用で反映されます。 Helm 3 で入れたリリースを Helm 4 で更新した場合は、前回の方法（クライアント側）を引き継ぎます（--server-side の既定値 auto）。

よくあるエラーと直し方

手元で起こしたエラーの原文です。

helm install --dry-run=server でも、すべての誤りが見つかるとは限りません。 手元では、ConfigMap に数字を入れたチャートが --dry-run=server を通り、実際の install で上の expected string のエラーになりました。

pending-upgrade から戻した手順です。

helm list -n web --pending
# NAME   NAMESPACE  REVISION  STATUS           CHART
# myapp  web        8         pending-upgrade  mychart-0.1.0
helm history myapp -n web | tail -2
helm rollback myapp 7 -n web
# Rollback was a success! Happy Helming!

Pod が起動しないときの切り分けは、関連記事「CrashLoopBackOffの直し方｜原因別の切り分け表」と「ImagePullBackOffの直し方｜ErrImagePullとの違いと原因表」で扱っています。

コマンド一覧

よくある質問

Q. Kustomize とどちらを使えばよいですか？ A. 値を変えて同じものを何度も入れる、版を記録して戻す、という用途は Helm が向いています。Kustomize は YAML に差分を重ねる方式で、kubectl apply -k で使えます。Helm で描画した YAML に Kustomize で手を加える組み合わせもあります。

Q. Secret の値を values.yaml に書いてよいですか？ A. values.yaml は Git に入るので、パスワードは書かないのが一般的です。--set で CI から渡す、External Secrets Operator などで外の保管庫から読む、といった方法があります。リリースの記録（Secret）には、描画した YAML と値が入る点にも注意します。

Q. ConfigMap を変えても Pod が作り直されません。 A. Deployment の Pod テンプレートが変わらないと、Pod は作り直されません。Pod の注釈に checksum/config: {{ include (print $.Template.BasePath "/configmap.yaml") . | sha256sum }} を入れると、ConfigMap が変わるたびに注釈も変わり、Pod が作り直されます。

まとめ

• helm create → helm lint → helm template で確かめてから helm install
• values は -f の後ろが勝ち、--set 系はその上。--set-string は --set より強い
• upgrade で値を1つでも渡すと、前回の -f は引き継がれない。毎回 -f を付ける
• 失敗に備えて --rollback-on-failure（Helm 3 は --atomic）と --wait・--timeout
• pending-upgrade で止まったら helm rollback
• Helm 4 は新規 install がサーバー側の適用。Helm 3 のセキュリティ修正は 2027年2月10日まで

Kubernetes のリソースと YAML の基本は、関連記事「Kubernetes入門｜主要リソースとYAMLの書き方、kubectl早見表」で扱っています。

参考・出典

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

• Helm「Installing Helm」：https://helm.sh/docs/intro/install/
• Helm「Helm 4 Overview」：https://helm.sh/docs/overview/
• Helm「Chart Template Guide - Values Files」：https://helm.sh/docs/chart_template_guide/values_files/
• Helm「Chart Template Guide - Template Function List」：https://helm.sh/docs/chart_template_guide/function_list/
• Helm「Chart Template Guide - Built-in Objects」：https://helm.sh/docs/chart_template_guide/builtin_objects/
• Helm「Use OCI-based registries」：https://helm.sh/docs/topics/registries/
• Helm「Charts」：https://helm.sh/docs/topics/charts/
• Helm「Helm Commands」：https://helm.sh/docs/helm/
• Helm Blog「Helm 4 Released」：https://helm.sh/blog/helm-4-released
• Helm Blog「Helm 3 End of Life」：https://helm.sh/blog/helm-v3-end-of-life
• k3s：https://docs.k3s.io/

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