Helm を導入する前にChartについて読んでおいてほしいドキュメントをまとました。

Chart の作成

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

$ 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 コマンドを利用して tar ファイルにするのですが、.helmignore を利用すると、その tar ファイルに含めたくないファイルを指定できるようなります。

The .helmignore file

template/

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

A First Template

templates/NOTES.txt

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

Creating a NOTES.txt File

templates/_helpers.tpl

templates/\_helpers.tpl は、マニフェストファイルではなく、マニフェストファイル内で利用されるグローバル変数（Helm では Named Template と呼ばれます）を定義したファイルとなります。

Using "Partials" and Template Includes

Helm について知る

Helm Template Language の記法

コメントは # の他、{{/*...*/}}のような記法を利用できます。 # を利用したコメントはデバッグモードで表示される、という違いがあります。

Comments (YAML Comments vs. Template Comments)

values.yaml へのアクセス

Built-in Object とは、Helm Template Lunguage で利用できるオブジェクトというかインスタンスとなります。values.yaml 等に定義した値を取得するには、Values オブジェクト内のインスタンス変数なになににアクセスする、みたいな感じで利用するイメージとなります。

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

Built-in Objects

Helm Template で利用できる関数

Helmファイルを書いていくとこうしたいあぁしたいとなると思うのですがHelm Template Language 内では、様々な関数がビルトインされています。Helmは60以上の利用可能な関数を持っています。そのうちのいくつかは、Go Tepｍplate自体で定義されています。

{{ .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 Tepｍplate自体で定義されています。

Flow Control

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

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

Named Templates

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

Using the 'include' Function

空白を管理する - の話

まず、テンプレート宣言の中括弧の構文を特別な文字で変更し、テンプレートエンジンに空白を切り詰めるように指示する。{{- xxx }} や {{ XX -}}とかで出てきているハイフンですが、これは Helm Template Lunguate を利用した行の空白を管理するものです。ハイフンの有無により空白の除去を実行してくれます。空白を消したあとに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 get manifestは、サーバーにインストールされているテンプレートを確認する良い方法です。