Helm を導入する前にChartについて読んでおいてほしいドキュメントをまとめました。この記事は、執筆時点のHelm 3を前提にしています。

Chart の作成
各ファイルの説明について
Helm について知る
Helm Chart をよくしていく
- Helm Chart のデバッグ
- Helm Chart のリファクタリング
Helm Chart のテスト
Helm Chart のリポジトリ化
さいごに
参考資料

Chart の作成

helm create でHelm Chart の雛形を作成します。Chart とは、Kubernetes リソースのまとまりを定義するファイル群のことです。中身を見ればなんとなく動きもわかるかもしれないので、実際に手を動かしながら読んでもらえると嬉しいです。

$ helm create mychart
Creating mychart
$ tree -a ./mychart
./chart-name
mychart/
├── .helmignore
├── Chart.yaml
├── charts
├── templates
│   ├── NOTES.txt
│   ├── _helpers.tpl
│   ├── deployment.yaml
│   ├── hpa.yaml
│   ├── ingress.yaml
│   ├── service.yaml
│   ├── serviceaccount.yaml
│   └── tests
│       └── test-connection.yaml
└── values.yaml

これにより、mychart ディレクトリが作成されます。特別なことがなければ基本的にはこれをベースに作成していくことになると思います。

Helm Create

Vim にもプラグインがあるので利用しているエディターごとに入れていただければと思います。

各ファイルの説明について

作成した mychart ディレクトリに移動して、Chart の設定を編集します。

Chart.yaml

Chart.yaml は、作成した Chart のメタ情報を管理するファイルです。幾つかの必須パラメーターと追加のパラメーターがあります。詳細は公式のドキュメントを読んでください。

Chart.yaml

values.yaml

values.yaml は、Helm Template Language で利用する変数の、デフォルト値を指定したファイルです。上書きしたい時は別途指定してあげます。

チャート内のvalues.yamlファイル
サブチャートの場合、親チャートのvalues.yamlファイル
helm install または helm upgrade に -f フラグを付けて渡した場合の values ファイル (helm install -f myvals.yaml ./mychart)
set で渡される個々のパラメータ (helm install --set foo=bar ./mychart のように)
Values Files

.helmignore

Chart をリポジトリ化する際には、作成したファイル一式を helm package コマンドでアーカイブにまとめます。.helmignore を利用すると、そのアーカイブに含めたくないファイルを指定できます。

The .helmignore file

templates/

templates/ はテンプレートファイル用のディレクトリです。テンプレートとして利用するファイルが格納されています。

A First Template

templates/NOTES.txt

templates/NOTES.txt は、Chart をインストールやアップデートした時にターミナル上で表示される文言を記述できます。アクセスすべきURLやリリース結果が見れるものを記載したりしてます。 {{ .Chart.Name }} や {{ .Chart.Version }} といった記述もできます。これが Helm Template Language です。記法については後述します。

Creating a NOTES.txt File

templates/_helpers.tpl

templates/_helpers.tpl は、ほかのテンプレートから名前で呼び出して再利用するNamed Templateを定義するファイルです。このファイル自体がKubernetesのマニフェストとして出力されるわけではありません。

Using "Partials" and Template Includes

Helm について知る

Helm Template Language の記法

コメントは # の他、{{/*...*/}}のような記法を利用できます。 # を利用したYAMLコメントはレンダリング後にも残ります。一方、{{/*...*/}}で書いたテンプレートのコメントは出力されません。

Comments (YAML Comments vs. Template Comments)

values.yaml へのアクセス

Built-in Object とは、Helm Template Language で利用できる組み込みオブジェクトです。values.yaml 等に定義した値は、.Valuesを通じて取得します。

Release のほか、Valuesや Chart といった Built-in Object を利用しています。Values は、values.yaml に定義された値へアクセスできるオブジェクトです。Chart は、Chart.yaml に定義された値へアクセスできるオブジェクトです。

Built-in Objects

Helm Template で利用できる関数

Helmファイルを書いていくと、こうしたいあぁしたいとなると思います。Helm Template Language には様々な関数が組み込まれています。そのうちのいくつかは、Go Template自体で定義されています。

{{ .Release.Name | quote }} は、.Release.Name の値をパイプで quote 関数へ渡し、引用符を付ける記述です。こんな感じで、実行したい関数をパイプでつなげていきます。

Template Function List

Helm Chart で利用できる制御構文

Helm には制御構造が利用できます。これは、テンプレートの生成の流れを制御する機能を提供します。制御構文は、以下が用意されています。

if/else for creating conditional blocks
with to specify a scope
range, which provides a "for each"-style loop

ちなみに、これらはGo Template自体で定義されています。

Flow Control

Named Templates を用いて一つのページで定義していく

名前付きテンプレートとは、単にファイルの中で定義され、名前が付けられたテンプレートのことです。 Named Template は、{{ define }} ... {{ end }} アクションで定義を行い、{{ template }} や {{ include }} アクションで、その値を利用することになります。

Named Templates

ちなみに{{ template }} でなく、 {{ include }} しないと、パイプを介した関数の実行できないため、{{ include }} が良い。

Using the 'include' Function

空白を管理する - の話

{{- xxx }} や {{ XX -}} に出てくるハイフンは、テンプレートの前後の空白を取り除く指定です。左側なら直前、右側なら直後の空白を取り除き、改行も対象になります。空白を消したあとにindentで字下げを追加するような形でも利用します。

Helm Chart をよくしていく

Helm Chart をデバッグしたりリファクタリングする時のヒントを書いていきます。

Helm Chart のデバッグ

Helm Chart ではデバッグする方法をいくつか用意しています。

Debugging Templates
helm lint は、Chart がベストプラクティスに沿っているかを確認するためのツールです。
helm template --debug はローカルでChart template のレンダリングをテストします。困ったらこれでyaml を直接、確認します。
helm install --dry-run --debugは、実際にはインストールせず、生成したマニフェストを確認する方法です。Helm 3ではテンプレートのレンダリングはクライアント側で行います。
helm get manifestは、インストール済みリリースのマニフェストを確認する方法です。