Helm Chart
Helm chartとは
Helm chartは、アプリケーションをKubernetesクラスタへデプロイするために必要なすべてのリソースを含むパッケージである。パッケージには、Deployment、Service、Secret、そして特定アプリケーションの状態を定義するConfigMapなど、さまざまなYAML設定ファイルが含まれる。
Helm chartはこれらのYAMLファイルとテンプレートをパッケージ化したものであり、パラメータ化された値に応じて追加の設定ファイルを生成できる。この方式により、さまざまな環境に合わせて設定ファイルをカスタマイズしたり、複数のデプロイで再利用できる設定ファイルを作成したりできる。また、各Helm chartを個別にバージョン管理できるため、異なる設定を持つ複数バージョンのアプリケーションを簡単に管理できる。
Helm packageとchart
Helmはchartsというpackaging formatを使用する。パッケージはHelm chartをパッケージ化したものであり、チャートはKubernetesのresource YAMLファイルをテンプレートとして作成し、メタ情報ファイルなどを圧縮したファイルを指す。
- ここでのchartは、Kubernetes resourcesをdescribeするfileの集合である。
- chartは何かをデプロイするために使用される。
- 例: memcached Pod、HTTP serversを持つWeb app、databasesなど。
- chartは特定のdirectory treeで構成されたfileから作成される。
- これらのfileは、デプロイされるversionのarchiveとしてpackagingできる。
chartファイルの作成と構造
chartディレクトリの作成
Helmチャートを作成するディレクトリを作り、helm create {directory}コマンドで基本ディレクトリを生成する。
% mkdir charts
% cd charts
% helm create app
Creating app
chartファイル構造
生成された基本ファイル構造は次のとおりである。
% tree app
app
├── Chart.yaml # Chartの名前、バージョン、説明などの情報を書いたYAMLファイル。 (required)
├── charts # このChartが依存するチャートを含むディレクトリ。 (optional)
├── templates # valuesと結合されたとき、有効なKubernetes manifestファイルを生成するテンプレートファイルのディレクトリ。 (required)
│ ├── NOTES.txt # 簡単な使い方を含むテキストファイル。 (optional)
│ ├── _helpers.tpl # template manifestファイルで共有する変数定義。 (required)
│ ├── deployment.yaml # クラスタに起動するリソーステンプレートファイル
│ ├── hpa.yaml
│ ├── ingress.yaml
│ ├── service.yaml
│ ├── serviceaccount.yaml
│ └── tests
│ └── test-connection.yaml
└── values.yaml # Chartのテンプレートで使用するデフォルト環境設定変数を定義したファイル。 (optional)
4 directories, 10 files
マニフェストファイル(manifest file)とは、コンピューティングにおいて、集合の一部または論理的な単位であるファイル群のためのメタデータを含むファイルである。
YAMLファイル
chart.yaml
apiVersion: Helm Chart自体のAPIバージョン (required)
name: Chart名 (required)
version: Chartバージョン。SemVer(Semantic Versioning)規則に従う必要がある。 (required)
# 例: X.X.X形式。SemVer規則参照: https://semver.org/lang/ko/
kubeVersion: Chartのインストールと実行を保証する、互換性のある最小KubernetesバージョンのSemVer範囲 (optional)
# 例: ">=1.15.3"
description: Chartプロジェクトの簡単な説明 (optional)
type: Chartタイプ (optional)
keywords:
- Chartプロジェクトに関するキーワードリスト (optional)
# Helm search時にkeywordも一緒に検索される。
home: ChartプロジェクトホームページのURL (optional)
sources:
- ChartプロジェクトのソースコードURLリスト (optional)
# Chart repositoryアドレスではない。
dependencies: # チャート要件のリスト (optional)
- name: チャート名 (nginx)
version: チャートのバージョン ("1.2.3")
repository: リポジトリURL ("https://example.com/charts") または ("@repo-name")
condition: (optional) チャートの有効/無効を決定するboolean値を作るYAMLパス。例: subchart1.enabled
tags: # (optional)
- 有効化/無効化をまとめるためにチャートをグループ化できるタグ
enabled: (optional) チャートをロードできるかを決定するboolean
import-values: # (optional)
- ImportValuesは、取り込む親キーに対するソース値のマッピングを保持する。各項目は文字列、または子/親子リスト項目ペアにできる。
alias: (optional) チャートの別名として使用される。同じチャートを複数回追加する必要があるときに便利である。
maintainers: # (optional)
- name: maintainerの名前(各maintainerごとにrequired)
email: maintainerのemail(各maintainerごとにoptional)
url: maintainerに関するURL(各maintainerごとにoptional)
icon: アイコンとして使用されるSVGまたはPNG画像URL。カタログでチャートを表示するときに使用される。 (optional)
appVersion: Chartを利用して提供されるアプリのバージョン (optional)
# Chartを利用して提供されるアプリのバージョンであり、SemVer形式に従わなくてもよい。
deprecated: チャートがdeprecatedされたチャートかどうかをboolean(true/false)で明示 (optional)
annotations:
example: キーでマッピングされた注釈のリスト (optional).
values.yaml
templateでは{{ .Values.image.tag }}のような形で使用する。これはインデントに注意して作成する必要がある。
templatesフォルダにデプロイするresourceを定義
基本的にdeployment、service、serviceaccount、ingressが存在する。
必要に応じてpersistentvolume、configmapなどを定義する。
apiVersion: apps/v1
kind: Deployment
metadata:
name: {{ .Values.name }}
labels:
app: {{ .Values.name }}
spec:
{{- if not .Values.autoscaling.enabled }}
replicas: {{ .Values.replicaCount }}
{{- end }}
selector:
matchLabels:
name: {{ .Values.name }}
template:
metadata:
{{- with .Values.podAnnotations }}
annotations:
{{- toYaml . | nindent 8 }}
{{- end }}
labels:
name: {{ .Values.name }}
spec:
containers:
- name: {{ .Chart.Name }}
image: "{{ .Values.image.repository }}:{{ .Values.image.tag | default .Chart.AppVersion }}"
imagePullPolicy: {{ .Values.image.pullPolicy }}
ports:
- name: http
containerPort: {{ .Values.container.port }}
protocol: TCP
envFrom:
- configMapRef:
name: {{ .Values.config.name }}
volumeMounts:
- mountPath: {{ .Values.container.mountpath }}
name: {{ .Values.container.volumename }}
volumes:
- name: {{ .Values.container.volumename }}
persistentVolumeClaim:
claimName: {{ .Values.PVC.name }}
Helmのtemplate構文
テンプレートファイルはGoテンプレート作成の標準規約に従う。(text/template Go package documentation)
{{ }}で変数を使用する。
.Valuesvalues.yamlファイルで定義された変数。
.ChartsCharts.yamlファイルで定義された変数。- Chartのバージョンは
Chart.Versionで、メンテナはChart.Maintainersで取得できる。
.Release- デプロイ時に割り当てた情報を使用する。
- たとえば、
--namespace testでinstallした場合、.Release.Namespaceにtestが割り当てられる。
- たとえば、
Release.Name: リリース名(Chart名ではない)Release.Namespace: ChartがリリースされたネームスペースRelease.Service: リリースを実行するサービスRelease.IsUpgrade: 現在アップグレードまたはロールバック中ならtrueに設定される。Release.IsInstall: 現在インストール中ならtrueに設定される。
- デプロイ時に割り当てた情報を使用する。
include...- _helpers.tplファイルで定義された変数。
with ~ end- 変数に対するscopeを定める構文であり、その区間の
.が設定した変数に属することを定義する。 - 例: 次のコードでは
.drinkは.Values.favorite.drinkを意味する。{{- with .Values.favorite }} drink: {{ .drink | default "tea" | quote }} food: {{ .food | upper | quote }} {{- end }}
- 変数に対するscopeを定める構文であり、その区間の
toYaml- 該当変数をYAML形式に変更する。
quote- string型に変更する。
Chartを検査する
定義したchartに構文上の問題がないか確認できる。
helm lint {Chart.yamlの場所}
これは構文エラーだけを点検するものであり、問題なくインストールされることを意味しない。
templatesを基に変数を参照し、リソースデプロイ時の結果をプレビューできる。
helm template {Chart.yamlの場所}
この過程により、デプロイしたい形になっているか確認できる。
chartを試験インストールしてエラーを確認できる。
helm install {release name} {Chart.yamlの場所} --debug --dry-run
--dry-run: 実際のクラスタにはインストールせず、chartを試験インストールするオプション。--debug: デプロイ用manifestファイルの内容を表示する。
chartを作成してrepoに登録する
helm repositoryには、チャート保存所の各チャート情報を含むindex.yamlファイルが必要である。
index.yamlが存在するフォルダで次のコマンドを実行し、パッケージングしてchartを作成する。
helm package {Chart.yamlの場所}
Chart.yamlに定義した{name}-{version}.tgzとして圧縮ファイルが作成される。
リポジトリに登録せず、生成した圧縮ファイルをローカルで使うだけなら
helm install {name}で可能である。
chartを作成したので、チャート情報を含むindexファイルを更新する。
helm repo index {index.yamlパス}
GitHub repositoryの場合はgit pushを行ったあと、
helm repo update
chart一覧をrepositoryから再取得して更新する。
更新されたか検索して確認する。
helm search repo {チャート名}
検索語はキーワードとして扱われ、その語を含むチャートとチャートのrepository一覧が出力される。
作成したChartを利用してインストールする
作成したチャートを次のコマンドでインストールする。
helm install {デプロイ名} {リポジトリ名/chart名} -n {ネームスペース}