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 ディレクトリが作成されます。特別なことがなければ基本的にはこれをベースに作成していくことになると思います。
Vim にもプラグイン があるので利用しているエディターごとに入れていただければと思います。
各ファイルの説明について
作成した mychart ディレクトリに移動して、Chart の設定を編集します。
Chart.yaml
Chart.yaml は、作成した Chart のメタ情報を管理するファイルです。幾つかの必須パラメーターと追加のパラメーターがあります。詳細は公式のドキュメントを読んでください。
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
のように)
.helmignore
Chart をリポジトリ化する際には、作成したファイル一式を helm package
コマンドを利用して tar ファイルにするのですが、.helmignore を利用すると、その tar ファイルに含めたくないファイルを指定できるようなります。
template/
templates/
はテンプレートファイル用のディレクトリです。テンプレートとして利用するファイルが納入されています。
templates/NOTES.txt
templates/NOTES.txt
は、Chart をインストールやアップデートした時にターミナル上で表示される文言を記述できます。アクセスすべきURLやリリース結果が見れるものを記載したりしてます。
{{ .Chart.Name }}
や {{ .Chart.Version }}
といった記述できます、これが Helm Template Language となります。Helm Template Language の記法については後述。
templates/_helpers.tpl
templates/\_helpers.tpl
は、マニフェストファイルではなく、マニフェストファイル内で利用されるグローバル変数(Helm では Named Template と呼ばれます)を定義したファイルとなります。
Helm について知る
Helm Template Language の記法
コメントは #
の他、{{/*...*/}}
のような記法を利用できます。
#
を利用したコメントはデバッグモードで表示される、という違いがあります。
values.yaml へのアクセス
Built-in Object とは、Helm Template Lunguage で利用できるオブジェクトというかインスタンスとなります。values.yaml
等に定義した値を取得するには、Values オブジェクト内のインスタンス変数 なになに にアクセスする、みたいな感じで利用するイメージとなります。
Release
のほか、Values
や Chart
といった Built-in Object を利用しています。Values
は、values.yaml
に定義された値へアクセスできるオブジェクトです。Chart
は、Chart.yaml
に定義された値へアクセスできるオブジェクトです。
Helm Template で利用できる関数
Helmファイルを書いていくとこうしたいあぁしたいとなると思うのですがHelm Template Language 内では、様々な関数がビルトインされています。Helmは60以上の利用可能な関数を持っています。そのうちのいくつかは、Go Tepmplate自体で定義されています。
{{ .Release.Name | quote }}
という記述があったとして、.Release.Name
という値に対して、パイプを介し、 quote
という引用符を付与する関数を実行しているものになります。こんな感じで、実行したい関数をパイプを介して記述していくことなります。
Helm Chart で利用できる制御構文
Helm には制御構造が利用できます。 これは、テンプレートの生成の流れを制御する機能を提供します。制御構文は、以下が用意されています。
if/else
for creating conditional blockswith
to specify a scoperange
, which provides a "for each"-style loop
ちなみにGo Tepmplate自体で定義されています。
Named Templates を用いて一つのページで定義していく
名前付きテンプレートとは、単にファイルの中で定義され、名前が付けられたテンプレートのことです。
Named Template は、{{ define }} ... {{ end }}
アクションで定義を行い、{{ template }}
や {{ include }}
アクションで、その値を利用することになります。
ちなみに{{ template }}
でなく、 {{ include }}
しないと、パイプを介した関数の実行できないため、{{ include }}
が良い。
空白を管理する - の話
まず、テンプレート宣言の中括弧の構文を特別な文字で変更し、テンプレートエンジンに空白を切り詰めるように指示する。{{- xxx }}
や {{ XX -}}
とかで出てきているハイフンですが、これは Helm Template Lunguate を利用した行の空白を管理するものです。ハイフンの有無により空白の除去を実行してくれます。空白を消したあとにindentを追加するような形で利用したりもします。
Helm Chart をよくしていく
Helm Chart をデバッグしたりリファクタリングする時のヒントを書いていきます。
Helm Chart のデバッグ
Helm Chart ではデバッグする方法をいくつか用意しています。
helm lint
は、Chart がベストプラクティスに沿っているかを確認するためのツールです。helm template --debug
はローカルでChart template のレンダリングをテストします。困ったらこれでyaml を直接、確認します。helm install --dry-run --debug
は、サーバーがテンプレートをレンダリングし、その結果のマニフェストファイルを返すという素晴らしい方法です。helm get manifest
は、サーバーにインストールされているテンプレートを確認する良い方法です。
Helm Chart のリファクタリング
Helm Chart の品質をあげるためのヒントとコツをいくつか取り上げられています。
- テンプレートの関数を知り有用と判断すれば利用する
- 文字列を引用する、整数を引用しない。これは絶対に頼む。
1つのコマンドでリリースをインストールまたはアップグレード
Helm Chart のテスト
templates/tests/
ディレクトリ配下においたマニフェストファイルは、helm test
コマンドにより実行することができます。
Helm Chart のリポジトリ化
リポジトリ化するには、index.yaml というファイルとChart 一式を固めた tar ファイルを静的 Web ホスティングサイトにアップロードすることで実現されます。
さいごに
これもあれば読んでほしいという内容があれば名前付きで掲載させていただくので連絡いただきたいです。