Helmの使い方

このガイドでは、Helmを使用してKubernetesクラスタ上のパッケージを管理する基本について説明します。Helmクライアントが既にインストールされていることを前提としています。

いくつかの簡単なコマンドを実行するだけの場合、クイックスタートガイドから始めることをお勧めします。この章では、Helmコマンドの詳細とHelmの使用方法について説明します。

3つの重要な概念

チャートとは、Helmパッケージのことです。チャートには、アプリケーション、ツール、またはサービスをKubernetesクラスタ内で実行するために必要なすべてのリソース定義が含まれています。Homebrewのformula、Aptのdpkg、YumのRPMファイルのKubernetes版と考えてください。

リポジトリとは、チャートを収集して共有できる場所のことです。PerlのCPANアーカイブやFedoraパッケージデータベースのようなものですが、Kubernetesパッケージ用です。

リリースとは、Kubernetesクラスタで実行されているチャートのインスタンスのことです。1つのチャートを同じクラスタに複数回インストールすることがよくあります。そして、インストールされるたびに、新しいリリースが作成されます。MySQLチャートを考えてみましょう。クラスタ内で2つのデータベースを実行したい場合、そのチャートを2回インストールできます。それぞれに独自のリリースがあり、それぞれに独自のリリース名があります。

これらの概念を踏まえて、Helmを次のように説明できます。

HelmはチャートをKubernetesにインストールし、インストールごとに新しいリリースを作成します。そして、新しいチャートを見つけるために、Helmチャートリポジトリを検索できます。

'helm search': チャートの検索

Helmには強力な検索コマンドが付属しています。2種類のソースを検索するために使用できます。

helm search hubは、数十の異なるリポジトリからのHelmチャートを一覧表示するArtifact Hubを検索します。
helm search repoは、ローカルのHelmクライアントに追加したリポジトリ（helm repo addを使用）を検索します。この検索はローカルデータに対して行われ、パブリックネットワーク接続は必要ありません。

helm search hubを実行することで、公開されているチャートを見つけることができます。

$ helm search hub wordpress
URL                                                 CHART VERSION APP VERSION DESCRIPTION
https://hub.helm.sh/charts/bitnami/wordpress        7.6.7         5.2.4       Web publishing platform for building blogs and ...
https://hub.helm.sh/charts/presslabs/wordpress-...  v0.6.3        v0.6.3      Presslabs WordPress Operator Helm Chart
https://hub.helm.sh/charts/presslabs/wordpress-...  v0.7.1        v0.7.1      A Helm chart for deploying a WordPress site on ...

上記は、Artifact Hub上のすべてのwordpressチャートを検索します。

フィルタがない場合、helm search hubは利用可能なすべてのチャートを表示します。

helm search repoを使用すると、既に追加したリポジトリにあるチャートの名前を見つけることができます。

$ helm repo add brigade https://brigadecore.github.io/charts
"brigade" has been added to your repositories
$ helm search repo brigade
NAME                          CHART VERSION APP VERSION DESCRIPTION
brigade/brigade               1.3.2         v1.2.1      Brigade provides event-driven scripting of Kube...
brigade/brigade-github-app    0.4.1         v0.2.1      The Brigade GitHub App, an advanced gateway for...
brigade/brigade-github-oauth  0.2.0         v0.20.0     The legacy OAuth GitHub Gateway for Brigade
brigade/brigade-k8s-gateway   0.1.0                     A Helm chart for Kubernetes
brigade/brigade-project       1.0.0         v1.0.0      Create a Brigade project
brigade/kashti                0.4.0         v0.4.0      A Helm chart for Kubernetes

Helm searchはあいまい文字列一致アルゴリズムを使用しているため、単語やフレーズの一部を入力できます。

$ helm search repo kash
NAME            CHART VERSION APP VERSION DESCRIPTION
brigade/kashti  0.4.0         v0.4.0      A Helm chart for Kubernetes

検索は、利用可能なパッケージを見つけるための良い方法です。インストールしたいパッケージが見つかったら、helm installを使用してインストールできます。

'helm install': パッケージのインストール

新しいパッケージをインストールするには、helm installコマンドを使用します。最も単純な形では、2つの引数を取ります。選択したリリース名と、インストールするチャートの名前です。

$ helm install happy-panda bitnami/wordpress
NAME: happy-panda
LAST DEPLOYED: Tue Jan 26 10:27:17 2021
NAMESPACE: default
STATUS: deployed
REVISION: 1
NOTES:
** Please be patient while the chart is being deployed **

Your WordPress site can be accessed through the following DNS name from within your cluster:

    happy-panda-wordpress.default.svc.cluster.local (port 80)

To access your WordPress site from outside the cluster follow the steps below:

1. Get the WordPress URL by running these commands:

  NOTE: It may take a few minutes for the LoadBalancer IP to be available.
        Watch the status with: 'kubectl get svc --namespace default -w happy-panda-wordpress'

   export SERVICE_IP=$(kubectl get svc --namespace default happy-panda-wordpress --template "{{ range (index .status.loadBalancer.ingress 0) }}{{.}}{{ end }}")
   echo "WordPress URL: http://$SERVICE_IP/"
   echo "WordPress Admin URL: http://$SERVICE_IP/admin"

2. Open a browser and access WordPress using the obtained URL.

3. Login with the following credentials below to see your blog:

  echo Username: user
  echo Password: $(kubectl get secret --namespace default happy-panda-wordpress -o jsonpath="{.data.wordpress-password}" | base64 --decode)

これで、wordpressチャートがインストールされました。チャートをインストールすると、新しいリリースオブジェクトが作成されることに注意してください。上記のリリースの名前はhappy-pandaです。（Helmに名前を生成させたい場合は、リリース名を省略して--generate-nameを使用します。）

インストール中に、helmクライアントは、どのリソースが作成されたか、リリースの状態、および追加の構成手順を実行できるか、または実行する必要があるかについての役立つ情報を出力します。

Helmは、以下の順序でリソースをインストールします。

Namespace
NetworkPolicy
ResourceQuota
LimitRange
PodSecurityPolicy
PodDisruptionBudget
ServiceAccount
Secret
SecretList
ConfigMap
StorageClass
PersistentVolume
PersistentVolumeClaim
CustomResourceDefinition
ClusterRole
ClusterRoleList
ClusterRoleBinding
ClusterRoleBindingList
Role
RoleList
RoleBinding
RoleBindingList
Service
DaemonSet
Pod
ReplicationController
ReplicaSet
Deployment
HorizontalPodAutoscaler
StatefulSet
Job
CronJob
Ingress
APIService

Helmは、すべてのリソースが実行されるまで待機してから終了するわけではありません。多くのチャートは、サイズが600MBを超えるDockerイメージを必要とし、クラスタへのインストールに長い時間がかかる場合があります。

リリースの状態を追跡したり、構成情報を再読み込みしたりするには、helm statusを使用します。

$ helm status happy-panda
NAME: happy-panda
LAST DEPLOYED: Tue Jan 26 10:27:17 2021
NAMESPACE: default
STATUS: deployed
REVISION: 1
NOTES:
** Please be patient while the chart is being deployed **

Your WordPress site can be accessed through the following DNS name from within your cluster:

    happy-panda-wordpress.default.svc.cluster.local (port 80)

To access your WordPress site from outside the cluster follow the steps below:

1. Get the WordPress URL by running these commands:

  NOTE: It may take a few minutes for the LoadBalancer IP to be available.
        Watch the status with: 'kubectl get svc --namespace default -w happy-panda-wordpress'

   export SERVICE_IP=$(kubectl get svc --namespace default happy-panda-wordpress --template "{{ range (index .status.loadBalancer.ingress 0) }}{{.}}{{ end }}")
   echo "WordPress URL: http://$SERVICE_IP/"
   echo "WordPress Admin URL: http://$SERVICE_IP/admin"

2. Open a browser and access WordPress using the obtained URL.

3. Login with the following credentials below to see your blog:

  echo Username: user
  echo Password: $(kubectl get secret --namespace default happy-panda-wordpress -o jsonpath="{.data.wordpress-password}" | base64 --decode)

上記は、リリースの現在の状態を示しています。

インストール前にチャートをカスタマイズする

ここで説明した方法でインストールすると、このチャートのデフォルトの構成オプションのみが使用されます。多くの場合、好みの構成を使用するようにチャートをカスタマイズする必要があります。

チャートで構成可能なオプションを確認するには、helm show valuesを使用します。

$ helm show values bitnami/wordpress
## Global Docker image parameters
## Please, note that this will override the image parameters, including dependencies, configured to use the global value
## Current available global Docker image parameters: imageRegistry and imagePullSecrets
##
# global:
#   imageRegistry: myRegistryName
#   imagePullSecrets:
#     - myRegistryKeySecretName
#   storageClass: myStorageClass

## Bitnami WordPress image version
## ref: https://hub.docker.com/r/bitnami/wordpress/tags/
##
image:
  registry: docker.io
  repository: bitnami/wordpress
  tag: 5.6.0-debian-10-r35
  [..]

その後、YAML形式のファイルでこれらの設定を上書きし、インストール中にそのファイルを渡すことができます。

$ echo '{mariadb.auth.database: user0db, mariadb.auth.username: user0}' > values.yaml
$ helm install -f values.yaml bitnami/wordpress --generate-name

上記は、user0という名前のデフォルトのMariaDBユーザーを作成し、このユーザーに新しく作成されたuser0dbデータベースへのアクセス権を付与しますが、そのチャートの残りのデフォルトはすべて受け入れます。

インストール中に構成データを渡すには、2つの方法があります。

--values（または-f）: 上書きを含むYAMLファイルを指定します。これは複数回指定でき、一番右側のファイルが優先されます。
--set: コマンドラインで上書きを指定します。

両方を使用する場合、--setの値は、より高い優先度で--valuesにマージされます。--setで指定された上書きは、Secretに永続化されます。--setされた値は、helm get values <release-name>で特定のリリースに対して表示できます。--setされた値は、--reset-valuesを指定してhelm upgradeを実行することでクリアできます。

`--set`の形式と制限

--setオプションは、0個以上の名前と値のペアを取ります。最も単純な形では、次のように使用されます。--set name=value。そのYAML同等物は次のとおりです。

name: value

複数の値は,文字で区切られます。そのため、--set a=b,c=dは次のようになります。

a: b
c: d

より複雑な式もサポートされています。たとえば、--set outer.inner=valueは次のように変換されます。

outer:
  inner: value

リストは、値を{と}で囲むことによって表現できます。たとえば、--set name={a, b, c}は次のように変換されます。

name:
  - a
  - b
  - c

特定の名前/キーは、null または空の配列 [] に設定できます。たとえば、--set name=[],a=null は

name:
  - a
  - b
  - c
a: b

以下のように変換されます。

name: []
a: null

Helm 2.5.0 以降、配列インデックス構文を使用してリストアイテムにアクセスできます。たとえば、--set servers[0].port=80 は

servers:
  - port: 80

以下のように変換されます。複数値をこの方法で設定できます。 --set servers[0].port=80,servers[0].host=example という行は

servers:
  - port: 80
    host: example

以下のように変換されます。--set 行で特殊文字を使用する必要がある場合があります。バックスラッシュを使用して文字をエスケープできます。 --set name=value1\,value2 は

name: "value1,value2"

以下のように変換されます。同様に、ドットシーケンスもエスケープできます。これは、チャートがアノテーション、ラベル、ノードセレクターを解析するために toYaml 関数を使用する場合に役立ちます。 --set nodeSelector."kubernetes\.io/role"=master の構文は

nodeSelector:
  kubernetes.io/role: master

以下のように変換されます。深くネストされたデータ構造は、--set を使用して表現するのが難しい場合があります。チャート設計者は、values.yaml ファイルの形式を設計する際に、--set の使用方法を考慮することをお勧めします（値ファイルの詳細をご覧ください）。

その他のインストール方法

helm install コマンドは、いくつかのソースからインストールできます。

チャートリポジトリ（上記で見たとおり）
ローカルチャートアーカイブ（helm install foo foo-0.1.1.tgz）
展開されたチャートディレクトリ（helm install foo path/to/foo）
完全なURL（helm install foo https://example.com/charts/foo-1.2.3.tgz）

'helm upgrade' と 'helm rollback'：リリースのアップグレードと障害からの復旧

チャートの新しいバージョンがリリースされた場合、またはリリースの構成を変更する場合、helm upgrade コマンドを使用できます。

アップグレードは、既存のリリースを取得し、提供された情報に従ってアップグレードします。 Kubernetesチャートは大きく複雑になる可能性があるため、Helmは最小限の侵襲的なアップグレードを実行しようとします。最後のリリース以降に変更されたもののみが更新されます。

$ helm upgrade -f panda.yaml happy-panda bitnami/wordpress

上記のケースでは、happy-panda リリースは同じチャートでアップグレードされますが、新しいYAMLファイルが使用されます。

mariadb.auth.username: user1

helm get values を使用して、新しい設定が有効になったかどうかを確認できます。

$ helm get values happy-panda
mariadb:
  auth:
    username: user1

helm get コマンドは、クラスタ内のリリースを確認するための便利なツールです。そして、上記で見ることができるように、panda.yaml からの新しい値がクラスタにデプロイされたことがわかります。

リリース中に計画どおりに進まない場合は、helm rollback [RELEASE] [REVISION] を使用して以前のリリースに簡単にロールバックできます。

$ helm rollback happy-panda 1

上記は、happy-pandaを最初のリリースバージョンにロールバックします。リリースバージョンは、増分リビジョンです。インストール、アップグレード、またはロールバックが発生するたびに、リビジョン番号は1ずつ増加します。最初のリビジョン番号は常に1です。また、helm history [RELEASE] を使用して、特定のリリースのリビジョン番号を確認できます。

インストール/アップグレード/ロールバックの便利なオプション

インストール/アップグレード/ロールバック中にHelmの動作をカスタマイズするために指定できる、他にもいくつかの便利なオプションがあります。これはCLIフラグの完全なリストではないことに注意してください。すべてのフラグの説明を表示するには、helm <command> --help を実行してください。

--timeout：Kubernetesコマンドが完了するのを待つGo期間値。デフォルトは5m0sです。
--wait：すべてのPodがready状態になり、PVCがバインドされ、Deploymentにready状態の最小限のPod（Desired - maxUnavailable）があり、ServiceにIPアドレス（およびLoadBalancerの場合はIngress）があるまで、リリースが成功したとマークされるのを待ちます。 --timeout 値と同じだけ待機します。タイムアウトに達した場合、リリースはFAILEDとマークされます。注：Deploymentのreplicasが1に設定され、ローリングアップデート戦略の一部としてmaxUnavailableが0に設定されていないシナリオでは、--waitは最小限のPodがready状態になった時点でreadyとして返されます。
--no-hooks：これは、コマンドのフックの実行をスキップします。
--recreate-pods （upgrade および rollback でのみ使用可能）：このフラグは、すべてのPodを再作成します（デプロイメントに属するPodを除く）。（Helm 3では非推奨）

'helm uninstall'：リリースのアンインストール

クラスタからリリースをアンインストールする場合は、helm uninstall コマンドを使用します。

$ helm uninstall happy-panda

これは、クラスタからリリースを削除します。 helm list コマンドを使用して、現在デプロイされているすべてのリリースを確認できます。

$ helm list
NAME            VERSION UPDATED                         STATUS          CHART
inky-cat        1       Wed Sep 28 12:59:46 2016        DEPLOYED        alpine-0.1.0

上記の出力から、happy-panda リリースがアンインストールされたことがわかります。

以前のバージョンのHelmでは、リリースが削除されると、削除のレコードが残っていました。 Helm 3では、削除によってリリースレコードも削除されます。削除リリースレコードを保持する場合は、helm uninstall --keep-historyを使用します。 helm list --uninstalledを使用すると、--keep-historyフラグでアンインストールされたリリースのみが表示されます。

helm list --all フラグは、失敗したアイテムまたは削除されたアイテムのレコード（--keep-history が指定されている場合）を含む、Helmが保持しているすべてのリリースレコードを表示します。

$  helm list --all
NAME            VERSION UPDATED                         STATUS          CHART
happy-panda     2       Wed Sep 28 12:47:54 2016        UNINSTALLED     wordpress-10.4.5.6.0
inky-cat        1       Wed Sep 28 12:59:46 2016        DEPLOYED        alpine-0.1.0
kindred-angelf  2       Tue Sep 27 16:16:10 2016        UNINSTALLED     alpine-0.1.0

リリースはデフォルトで削除されるため、アンインストールされたリソースをロールバックすることはできなくなりました。

'helm repo'：リポジトリの操作

Helm 3には、デフォルトのチャートリポジトリが付属していません。 helm repo コマンドグループは、リポジトリを追加、一覧表示、および削除するためのコマンドを提供します。

helm repo list を使用して、どのリポジトリが構成されているかを確認できます。

$ helm repo list
NAME            URL
stable          https://charts.helm.sh/stable
mumoshu         https://mumoshu.github.io/charts

新しいリポジトリは、helm repo add で追加できます。

$ helm repo add dev https://example.com/dev-charts

チャートリポジトリは頻繁に変更されるため、いつでもhelm repo updateを実行することで、Helmクライアントが最新であることを確認できます。

リポジトリは、helm repo remove で削除できます。

独自のチャートの作成

チャート開発ガイドでは、独自のチャートを開発する方法について説明しています。ただし、helm create コマンドを使用すると、すぐに始めることができます。

$ helm create deis-workflow
Creating deis-workflow

これで、./deis-workflow にチャートが作成されました。編集して独自のテンプレートを作成できます。

チャートを編集するときは、helm lint を実行して、チャートが適切に作成されていることを検証できます。

配布用にチャートをパッケージ化する場合は、helm package コマンドを実行できます。

$ helm package deis-workflow
deis-workflow-0.1.0.tgz

これで、そのチャートは helm install によって簡単にインストールできます。

$ helm install deis-workflow ./deis-workflow-0.1.0.tgz
...

パッケージ化されたチャートは、チャートリポジトリにロードできます。詳細については、Helmチャートリポジトリのドキュメントを参照してください。

結論

この章では、検索、インストール、アップグレード、アンインストールなど、helm クライアントの基本的な使用方法パターンについて説明しました。また、helm status、helm get、helm repo などの便利なユーティリティコマンドについても説明しました。

これらのコマンドの詳細については、Helmの組み込みヘルプ：helm help をご覧ください。

次の章では、チャートの開発プロセスについて説明します。