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)

{{ }}で変数を使用する。

  • .Values
    • values.yamlファイルで定義された変数。
  • .Charts
    • Charts.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 }}
      
  • 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 {ネームスペース}

参考