--- title: "Helmとは？チャート・リポジトリ・リリースの基本とhelm repo addなど主要コマンド解説" url: "https://www.issoh.co.jp/tech/details/7694/" published: 2025-07-14 updated: 2026-10-19 categories: ["アーキテクチャ"] publisher: "株式会社一創" --- # 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の意味から仕組みまでの解説](/tech/details/2928/)も参照してください。 Helmが提供する価値は、テンプレート化による再利用、リリース単位でのバージョン管理と切り戻し、そしてパブリックリポジトリで公開された既製チャート（データベースやIngressコントローラなど）をコマンド1つで導入できる点にあります。自前でマニフェストを1から書く手間を、実績のあるチャートの利用に置き換えられます。[コンテナ技術とは何か：仮想化との違いや基本概念の解説](/column/details/13000/)を踏まえると、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）とは｜できること・料金・始め方の解説](/tech/details/7272/)が参考になります。 ``` 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ファイルを分ければ、開発・本番の切り替えが値ファイルの指定だけで済みます。このvaluesファイルの指定をGitで管理してArgo CDから同期する手順は[ArgoCDでHelm chartを使う方法](https://www.issoh.co.jp/tech/details/18562/)で解説しています。 ### 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を実現するための基本ガイド](/tech/details/2715/)の考え方がそのまま応用できます。 ## 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](https://www.issoh.co.jp/tech/details/15572/)のほうが見通しが良いこともあります。チャートや環境差分・バージョン管理が増えて手作業がつらくなってきたタイミングが、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などで分岐を書かずに冪等なデプロイができます。 ## 関連記事 - [Kubernetes（クーベネティス）とは？読み方・K8sの意味から解説](/tech/details/2928/) - [コンテナ技術とは何か：仮想化との違いや基本概念を解説](/column/details/13000/) - [AKS（Azure Kubernetes Service）とは｜できること・料金・始め方を解説](/tech/details/7272/) - [TerraformとGitHub Actionsを使ってCI/CDを実現するための基本ガイド](/tech/details/2715/) --- 出典: [Helmとは？チャート・リポジトリ・リリースの基本とhelm repo addなど主要コマンド解説]()（株式会社一創）