2025.07.14 アーキテクチャ

Helmとは？チャート・リポジトリ・リリースの基本とhelm repo addなど主要コマンド解説

Helmは、Kubernetes上のアプリケーションを「チャート」という単位でパッケージ化し、インストール・更新・削除をコマンド1つで扱えるようにするツールです。KubernetesのパッケージマネージャーとしてCNCFの卒業プロジェクトになっており、複数のマニフェスト（Deployment・Service・ConfigMapなど）を手作業でkubectl applyする運用から解放してくれます。この記事では、Helmを理解する軸になるチャート・リポジトリ・リリースの3概念を整理したうえで、helm repo addによるリポジトリ追加からhelm install・helm upgrade・helm uninstallといった主要コマンドまでを、実際に打てるコマンド付きで解説します。Helm3での変更点や、現場でつまずきやすいエラーの対処もあわせて扱います。

目次

まとめ

  • HelmはKubernetesのパッケージマネージャーで、複数マニフェストをチャートとしてまとめて管理する。
  • 基本は3概念で捉える。チャート（配布物のひな型）、リポジトリ（チャートの置き場）、リリース（クラスタにインストールされた実体）。
  • 使い始めはhelm repo addでリポジトリを登録し、helm repo updateでインデックスを更新してからhelm installする、という流れ。
  • 更新はhelm upgrade、切り戻しはhelm rollback、削除はhelm uninstallで完結する。
  • Helm3ではTillerが廃止され、リリース状態はKubernetesのSecretとして保持される。この仕様が「cannot re-use a name that is still in use」エラーの理解にも直結する。

ここから、各概念とコマンドを実例付きで順に見ていきます。まずHelmが何を解決するのかを押さえます。

HelmとはKubernetesのパッケージマネージャー：解決する課題と役割

Kubernetesにアプリケーションをデプロイするには、Deployment・Service・Ingress・ConfigMapといった複数のYAMLマニフェストを書き、kubectl applyで個別に適用します。環境（開発・ステージング・本番）ごとにレプリカ数やイメージタグを変えたい場合、マニフェストをコピーして値を書き換える運用になりがちで、差分管理とバージョン管理がすぐ破綻します。Helmはこの一式をチャートという単位でパッケージ化し、環境ごとの差分はvalues.yamlという設定ファイルに外出しすることで、同じチャートを値だけ変えて再利用できるようにします。Kubernetes自体の基礎はKubernetes（クーベネティス）とは？読み方・K8sの意味から仕組みまでの解説も参照してください。

Helmが提供する価値は、テンプレート化による再利用、リリース単位でのバージョン管理と切り戻し、そしてパブリックリポジトリで公開された既製チャート（データベースやIngressコントローラなど）をコマンド1つで導入できる点にあります。自前でマニフェストを1から書く手間を、実績のあるチャートの利用に置き換えられます。コンテナ技術とは何か：仮想化との違いや基本概念の解説を踏まえると、Helmがコンテナオーケストレーションの運用工数をどこで削るのかが掴みやすくなります。

チャート・リポジトリ・リリースという3つの基本概念と相互関係

Helmの用語は、この3つの関係で理解すると迷いません。チャート＝ひな型、リポジトリ＝ひな型の配布元、リリース＝インストールされた稼働中の実体です。リポジトリからチャートを取得し、値を与えてインストールするとリリースが1つ生まれる、という一方向の流れになります。

チャート：Kubernetesリソースをまとめたパッケージ

チャートは、テンプレート化されたマニフェスト群とメタ情報をまとめたディレクトリです。中心となるのは、チャートの名前やバージョンを書くChart.yaml、既定値を持つvalues.yaml、そしてテンプレート本体を置くtemplatesディレクトリの3つです。

myapp/
├── Chart.yaml      # チャートのメタ情報（名前・バージョン）
├── values.yaml     # 既定の設定値
├── charts/         # 依存チャート
└── templates/      # テンプレート化したマニフェスト
    ├── deployment.yaml
    ├── service.yaml
    └── _helpers.tpl

リポジトリ：チャートを配布する場所

リポジトリは、パッケージ化したチャート（.tgz）と、その一覧を記したindex.yamlを置いたHTTPサーバーです。helm repo addで登録すると、そのリポジトリのチャートを名前で検索・インストールできるようになります。公式のArtifact Hubには多数の公開リポジトリが集約されています。

リリース：クラスタにインストールされたチャートの実体

同じチャートを違う名前で何度でもインストールでき、そのインストール1回ぶんがリリースです。リリースにはリビジョン番号が振られ、helm upgradeのたびに1、2、3と増えていきます。この履歴があるため、問題が起きたらhelm rollbackで以前のリビジョンへ即座に戻せます。

Chart.yamlのversionとappVersionの違い

混同しやすいのがversionとappVersionです。versionは「チャート自体のバージョン」でSemVerに従い、テンプレートを直すたびに上げます。appVersionは「チャートが載せているアプリのバージョン」で、例えばnginx 1.25を載せているなら1.25を書きます。両者は独立しており、アプリを変えずテンプレートだけ修正したときはversionだけ上がります。

apiVersion: v2
name: myapp
version: 0.1.0        # チャートのバージョン
appVersion: "1.25.3"  # 載せているアプリのバージョン

Helmのインストールとバージョン確認（macOS・Windows・Linux）

Helmはクライアント側のCLIをインストールするだけで使えます。Helm3ではサーバー側コンポーネント（旧Tiller）が不要になったため、クラスタ側に何かを常駐させる必要はありません。OSごとの代表的な導入方法は次のとおりです。

# macOS（Homebrew）
brew install helm

# Windows（Chocolatey）
choco install kubernetes-helm

# Linux（公式インストールスクリプト）
curl -fsSL -o get_helm.sh https://raw.githubusercontent.com/helm/helm/main/scripts/get-helm-3
chmod 700 get_helm.sh
./get_helm.sh

導入後はhelm versionでバージョンを確認します。Helmはkubectlと同じkubeconfig（既定で~/.kube/config）を参照して接続先クラスタを決めるため、kubectlが通っていればHelmもそのクラスタを操作対象にします。マネージドKubernetesであるAKSなどでも同様で、接続の考え方はAKS（Azure Kubernetes Service）とは｜できること・料金・始め方の解説が参考になります。

helm version
# （例）version.BuildInfo{Version:"v3.16.2", GoVersion:"go1.22.7"}
# ↑バージョン部分は環境・時期で変わる。3系であることを確認する

# 接続先クラスタの確認（kubectlのcurrent-contextを利用）
kubectl config current-context

Helmのバージョンは頻繁に更新されるため、最新版はhelm versionの出力とHelm公式ドキュメントで確認してください。ここではHelm3系を前提に説明します。

helm repo addによるリポジトリの追加・検索・更新・削除

Helmを使い始める最初のステップが、チャートの配布元を登録するhelm repo addです。書式はhelm repo add [ローカルでの名前] [リポジトリのURL]で、以降はここで付けた名前でチャートを参照します。ここでは公式にメンテナンスされているingress-nginxリポジトリを例に、一連の流れを示します。

helm repo add：リポジトリの登録

helm repo add ingress-nginx https://kubernetes.github.io/ingress-nginx

登録は端末ごとのローカル設定に保存されるだけで、この時点ではクラスタには何も起きません。追加した直後は必ず次のhelm repo updateを実行して、リポジトリのインデックス（index.yaml）を手元に取り込みます。

helm repo update：インデックス更新の必要性

helm repo update

このコマンドは登録済みリポジトリの最新のindex.yamlを取得します。実行しないと、リポジトリ側に新しいバージョンのチャートが公開されても手元の一覧が古いままになり、helm searchやhelm installで最新版を掴めません。新しいチャートが見つからない、といったトラブルの多くはupdate忘れが原因です。

helm searchによるチャート検索

# 登録済みリポジトリから検索
helm search repo ingress-nginx

# Artifact Hub全体から検索
helm search hub wordpress

helm search repoはhelm repo addで登録したリポジトリ内を、helm search hubはArtifact Hubに公開された全チャートを対象にします。目的のチャートがどのリポジトリにあるか分からないときはhubで探し、URLをhelm repo addで登録してからrepoで絞り込む、という順番になります。

helm repo list／removeによるリポジトリ管理

# 登録済みリポジトリの一覧
helm repo list

# 不要になったリポジトリの削除
helm repo remove ingress-nginx

なお、長く定番だったBitnamiのチャートは2025年8月28日以降、無償での保守が止まりました。Helmチャート自体はdocker.io/bitnamichartsに残るものの更新されず、チャートが参照するコンテナイメージはbitnamilegacy（アーカイブ・更新なし）へ退避、最新の保守版は有償のBitnami Secure Imagesへ移りました。過去記事のとおりにhelm repo add bitnamiして本番運用する場合は、この「チャートは残るがイメージは更新されない」状況を踏まえ、イメージタグの固定や代替リポジトリへの移行を検討してください。

helm install・list・upgrade・uninstallなど主要コマンドの操作

リポジトリを登録したら、実際のデプロイと運用に入ります。日常的に使うのは、インストール・確認・更新・切り戻し・削除の一連のコマンドです。

helm install：チャートのデプロイ

# helm install [リリース名] [リポジトリ名/チャート名]
helm install my-nginx ingress-nginx/ingress-nginx

第1引数がリリース名、第2引数が「リポジトリ名/チャート名」です。同じチャートでもリリース名を変えれば複数を並行して動かせます。適用前に生成されるマニフェストを確認したいときは、後述の--dry-runを付けます。

helm list／statusによるリリースの確認

# インストール済みリリースの一覧
helm list

# 特定リリースの状態
helm status my-nginx

helm listはリリース名・リビジョン・状態（deployed／failedなど）・チャートバージョンを一覧します。トラブル時はhelm list -aで失敗状態のものも含めて表示させるのがコツです。

helm upgrade／rollbackによる更新と切り戻し

# 設定を変えて更新（リビジョンが増える）
helm upgrade my-nginx ingress-nginx/ingress-nginx --set controller.replicaCount=2

# リビジョン履歴の確認
helm history my-nginx

# 直前のリビジョンへ切り戻し
helm rollback my-nginx 1

helm upgradeのたびにリビジョンが1つ増え、履歴はクラスタ側に保持されます。更新後に不具合が出たらhelm rollback [リリース名] [リビジョン番号]で以前の状態へ即座に戻せます。この巻き戻しの手軽さが、生のkubectl運用に対するHelmの実務的な強みです。

helm uninstall：リリースの削除

helm uninstall my-nginx

リリースが作ったKubernetesリソースをまとめて削除します。Helm3では削除と同時に履歴も消えるため、履歴を残したい場合は--keep-historyを付けます。この履歴（Secret）の扱いが、次章のエラーとも関係します。

helm template／–dry-runによる事前確認

# クラスタに触れずマニフェストだけ生成
helm template my-nginx ingress-nginx/ingress-nginx

# 実際のinstallを模擬（APIサーバー検証あり）
helm install my-nginx ingress-nginx/ingress-nginx --dry-run --debug

helm templateはクラスタに接続せずローカルでマニフェストを描画するだけなので、CIでの構文チェックに向きます。一方--dry-runはAPIサーバーに問い合わせて検証まで行うため、適用直前の最終確認に使い分けます。

values.yamlのカスタマイズとhelm createによる自作チャート

既製チャートをそのまま使うだけでなく、値を上書きして自社向けに調整したり、ゼロから自作チャートを作ったりできます。ここは「設定を変える」と「作る」の2軸です。

values.yamlと–setによる設定の上書き

# チャートの既定値を確認
helm show values ingress-nginx/ingress-nginx

# ファイルで上書き
helm install my-nginx ingress-nginx/ingress-nginx -f my-values.yaml

# コマンドラインで個別に上書き
helm install my-nginx ingress-nginx/ingress-nginx --set controller.replicaCount=3

まずhelm show valuesで上書きできる項目を確認し、変更点だけを自前のmy-values.yamlに書いて-fで渡すのが基本です。少数の値なら--setが手軽ですが、項目が増えるとファイル管理のほうが差分を追いやすくなります。環境ごとにvaluesファイルを分ければ、開発・本番の切り替えが値ファイルの指定だけで済みます。

helm createによる雛形生成とテンプレート構文

helm create myapp

helm createは動作する最小構成のチャート雛形を生成します。テンプレートはGoテンプレート構文で書き、values.yamlの値を.Valuesで参照します。例えばレプリカ数やイメージを値から差し込むと、次のようになります。

# templates/deployment.yaml（抜粋）
spec:
  replicas: {{ .Values.replicaCount }}
  containers:
    - image: "{{ .Values.image.repository }}:{{ .Values.image.tag }}"

作成したチャートは、CI/CDに組み込んで自動デプロイするのが定石です。GitHub Actionsなどと組み合わせる流れはTerraformとGitHub Actionsを使ってCI/CDを実現するための基本ガイドの考え方がそのまま応用できます。

Helm3とHelm2の違いとバージョン選定の判断

いま新規に採用するならHelm3一択です。Helm2にはTillerというサーバー側コンポーネントがクラスタ内に常駐し、これが強い権限を持つためセキュリティ上の懸念とされていました。2019年11月にリリースされたHelm3ではTillerが廃止され、Helmはクライアントから直接Kubernetes APIを叩く構成になりました。

この変更に伴い、リリースの状態はTillerではなく各NamespaceのSecret（sh.helm.release.v1.*）として保存されるようになりました。Helm2は公式サポートが終了しているため、既存のHelm2環境が残っている場合はhelm-2to3プラグインでの移行を検討してください。バージョン選定に迷う要素は実質なく、判断基準は「Helm2資産の移行が済んでいるか」だけです。

helm repo addやinstallでよくあるエラーと対処法

Helmの操作で実際につまずきやすいエラーを、原因と対処をセットで挙げます。いずれもHelm3の「状態をSecretで持つ」という仕組みを知っていると理解が早くなります。

cannot re-use a name that is still in use の原因と解消

installが途中で失敗した後に同じリリース名で再installすると、この「INSTALLATION FAILED: cannot re-use a name that is still in use」が出ます。原因は、前回の失敗したリリースの状態Secret（sh.helm.release.v1.[リリース名].v1）がNamespaceに残り、Helmがその名前を使用中と判断するためです。まず失敗状態も含めて一覧し、リリースを削除します。

# 失敗・削除済みも含めて一覧
helm list -a -n default

# リリースを削除
helm uninstall my-nginx -n default

# それでも残るときは状態Secretを直接削除
kubectl delete secret sh.helm.release.v1.my-nginx.v1 -n default

helm uninstallで消えれば同名で再installできます。uninstallでも消えない場合のみ、上のように残ったSecretをkubectl delete secretで削除します。Namespaceの指定（-n）を間違えると別の場所を見てしまうため、対象Namespaceを必ず合わせてください。

リポジトリ参照エラー（helm repo update忘れ・URLミス）

「chart not found」や「no repository definition」で止まる場合、多くはhelm repo add後のhelm repo update忘れ、またはリポジトリ名の打ち間違いです。helm repo listで登録名とURLを確認し、updateを実行し直します。社内のプライベートリポジトリで認証が要る場合は、helm repo addに--username／--passwordを付けて登録します。

テンプレート構文エラーのデバッグ（–debug）

自作チャートでhelm installが「parse error」や「render error」で失敗するのは、Goテンプレートの構文ミスやvalues.yamlに無いキーの参照が原因です。--dry-run --debugを付けると、レンダリング結果とエラー箇所が出力され、どのテンプレート行で失敗しているかを特定できます。修正前にまずhelm templateでローカル描画して切り分けるのが早道です。

よくある質問（FAQ）

Helmとは何ですか？

HelmはKubernetes向けのパッケージマネージャーです。Deployment・Serviceなど複数のマニフェストを「チャート」という単位でまとめ、helm installでクラスタへ導入し、helm upgradeやhelm uninstallで更新・削除まで一貫して管理します。LinuxのaptやmacOSのHomebrewのKubernetes版と考えると分かりやすいです。

Helmを使うメリットは何ですか？向かない場面はありますか？

メリットは、values.yamlで環境差分を外出しした再利用、リビジョン履歴による切り戻し、既製チャートの即時導入です。一方で万能ではありません。扱うマニフェストが小さく1種類しかない、あるいはテンプレートの間接性でかえって読みにくくなる場面では、素のkubectlやKustomizeのほうが見通しが良いこともあります。チャートや環境差分・バージョン管理が増えて手作業がつらくなってきたタイミングが、Helm導入の判断ラインです。

helm repo addで追加したリポジトリはどこに保存されますか？

クラスタではなく、コマンドを実行した端末のローカル設定に保存されます（helm envで表示されるHELM_REPOSITORY_CONFIGのパス）。そのため別のマシンやCIランナーでは改めてhelm repo addが必要です。登録内容はhelm repo listで確認できます。

Helm2とHelm3の違いは何ですか？

最大の違いはTillerの廃止です。Helm2はクラスタ内のTillerを介して動作しましたが、Helm3ではTillerが無くなり、クライアントから直接Kubernetes APIへアクセスします。リリース状態もSecretとして各Namespaceに保存される方式に変わりました。Helm2はサポート終了のため、新規はHelm3を使います。

helm installとhelm upgradeはどう使い分けますか？

helm installは新規リリースの作成、helm upgradeは既存リリースの更新に使います。存在しなければ作成、あれば更新、という挙動を1コマンドで済ませたい場合はhelm upgrade --install（-i）を使うと、CIなどで分岐を書かずに冪等なデプロイができます。

関連記事

資料請求

RELATED POSTS 関連記事

一覧へ戻る