チャート

Helmはチャートと呼ばれるパッケージ形式を使用します。チャートは、関連するKubernetesリソースのセットを記述するファイルのコレクションです。単一のチャートを使用して、memcachedポッドのような単純なものや、HTTPサーバー、データベース、キャッシュなどを含む完全なWebアプリスタックのような複雑なものをデプロイできます。

チャートは、特定のディレクトリツリーに配置されたファイルとして作成されます。それらは、デプロイするためにバージョン管理されたアーカイブにパッケージ化できます。

インストールせずに、公開されたチャートのファイルをダウンロードして確認したい場合は、helm pull chartrepo/chartnameで実行できます。

このドキュメントでは、チャート形式について説明し、Helmでチャートを構築するための基本的なガイダンスを提供します。

チャートファイル構造

チャートは、ディレクトリ内のファイルのコレクションとして編成されます。ディレクトリ名は、チャートの名前（バージョン情報なし）です。したがって、WordPressを記述するチャートは、wordpress/ディレクトリに格納されます。

このディレクトリ内で、Helmはこの構造に一致することを期待します。

wordpress/
  Chart.yaml          # A YAML file containing information about the chart
  LICENSE             # OPTIONAL: A plain text file containing the license for the chart
  README.md           # OPTIONAL: A human-readable README file
  values.yaml         # The default configuration values for this chart
  values.schema.json  # OPTIONAL: A JSON Schema for imposing a structure on the values.yaml file
  charts/             # A directory containing any charts upon which this chart depends.
  crds/               # Custom Resource Definitions
  templates/          # A directory of templates that, when combined with values,
                      # will generate valid Kubernetes manifest files.
  templates/NOTES.txt # OPTIONAL: A plain text file containing short usage notes

Helmは、charts/、crds/、templates/ディレクトリ、およびリストされたファイル名の使用を予約します。その他のファイルはそのまま残されます。

Chart.yamlファイル

Chart.yamlファイルは、チャートに必須です。これには、次のフィールドが含まれます。

apiVersion: The chart API version (required)
name: The name of the chart (required)
version: A SemVer 2 version (required)
kubeVersion: A SemVer range of compatible Kubernetes versions (optional)
description: A single-sentence description of this project (optional)
type: The type of the chart (optional)
keywords:
  - A list of keywords about this project (optional)
home: The URL of this projects home page (optional)
sources:
  - A list of URLs to source code for this project (optional)
dependencies: # A list of the chart requirements (optional)
  - name: The name of the chart (nginx)
    version: The version of the chart ("1.2.3")
    repository: (optional) The repository URL ("https://example.com/charts") or alias ("@repo-name")
    condition: (optional) A yaml path that resolves to a boolean, used for enabling/disabling charts (e.g. subchart1.enabled )
    tags: # (optional)
      - Tags can be used to group charts for enabling/disabling together
    import-values: # (optional)
      - ImportValues holds the mapping of source values to parent key to be imported. Each item can be a string or pair of child/parent sublist items.
    alias: (optional) Alias to be used for the chart. Useful when you have to add the same chart multiple times
maintainers: # (optional)
  - name: The maintainers name (required for each maintainer)
    email: The maintainers email (optional for each maintainer)
    url: A URL for the maintainer (optional for each maintainer)
icon: A URL to an SVG or PNG image to be used as an icon (optional).
appVersion: The version of the app that this contains (optional). Needn't be SemVer. Quotes recommended.
deprecated: Whether this chart is deprecated (optional, boolean)
annotations:
  example: A list of annotations keyed by name (optional).

v3.3.2以降、追加のフィールドは許可されていません。推奨される方法は、annotationsにカスタムメタデータを追加することです。

チャートとバージョニング

すべてのチャートにはバージョン番号が必要です。バージョンは、SemVer 2標準に従う必要があります。Helm Classicとは異なり、Helm v2以降では、バージョン番号をリリースマーカーとして使用します。リポジトリ内のパッケージは、名前とバージョンで識別されます。

たとえば、バージョンフィールドがversion: 1.2.3に設定されているnginxチャートは、次のように命名されます。

nginx-1.2.3.tgz

version: 1.2.3-alpha.1+ef365のような、より複雑なSemVer 2名もサポートされています。しかし、非SemVer名はシステムによって明示的に許可されていません。

注：Helm ClassicとDeployment Managerはどちらもチャートに関して非常にGitHub指向でしたが、Helm v2以降はGitHubやGitに依存したり、必要としたりしません。したがって、Git SHAをバージョニングに使用することはありません。

Chart.yaml内のversionフィールドは、CLIを含む多くのHelmツールによって使用されます。パッケージを生成する場合、helm packageコマンドは、Chart.yamlで見つけたバージョンをパッケージ名のトークンとして使用します。システムは、チャートパッケージ名のバージョン番号がChart.yamlのバージョン番号と一致することを前提としています。この前提を満たさないと、エラーが発生します。

`apiVersion`フィールド

apiVersionフィールドは、少なくともHelm 3を必要とするHelmチャートの場合はv2である必要があります。以前のHelmバージョンをサポートするチャートは、apiVersionがv1に設定されており、Helm 3でもインストール可能です。

v1からv2への変更

チャートの依存関係を定義するdependenciesフィールド。これは、v1チャートでは別のrequirements.yamlファイルにありました（チャートの依存関係を参照）。
アプリケーションチャートとライブラリチャートを区別するtypeフィールド（チャートタイプを参照）。

`appVersion`フィールド

appVersionフィールドは、versionフィールドとは関係がないことに注意してください。これは、アプリケーションのバージョンを指定する方法です。たとえば、drupalチャートにはappVersion: "8.2.1"があり、チャートに含まれるDrupalのバージョン（デフォルトで）が8.2.1であることを示している場合があります。このフィールドは情報提供のみを目的としており、チャートのバージョン計算には影響しません。バージョンを引用符で囲むことを強くお勧めします。これにより、YAMLパーサーはバージョン番号を文字列として扱うようになります。引用符で囲まない場合、場合によっては解析の問題が発生する可能性があります。たとえば、YAMLは1.0を浮動小数点値として、1234e10のようなgitコミットSHAを科学表記法として解釈します。

Helm v3.5.0以降、helm createはデフォルトのappVersionフィールドを引用符で囲みます。

`kubeVersion`フィールド

オプションのkubeVersionフィールドでは、サポートされているKubernetesバージョンのセムバー制約を定義できます。Helmは、チャートをインストールするときにバージョン制約を検証し、クラスターがサポートされていないKubernetesバージョンを実行している場合は失敗します。

バージョン制約は、次のようなスペースで区切られたAND比較で構成できます。

>= 1.13.0 < 1.15.0

これらは、次の例のように、OR ||演算子と組み合わせることができます。

>= 1.13.0 < 1.14.0 || >= 1.14.1 < 1.15.0

この例では、バージョン1.14.0が除外されています。これは、特定のバージョンでのバグがチャートの適切な実行を妨げることがわかっている場合に意味があります。

演算子= != > < >= <=を採用するバージョン制約とは別に、次の省略表記がサポートされています。

閉区間のハイフン範囲。ここで、1.1 - 2.3.4は>= 1.1 <= 2.3.4と同等です。
ワイルドカードx、X、および*。ここで、1.2.xは>= 1.2.0 < 1.3.0と同等です。
チルダ範囲（パッチバージョンの変更が許可されます）。ここで、~1.2.3は>= 1.2.3 < 1.3.0と同等です。
キャレット範囲（マイナーバージョンの変更が許可されます）。ここで、^1.2.3は>= 1.2.3 < 2.0.0と同等です。

サポートされているセムバー制約の詳細な説明については、Masterminds/semverを参照してください。

チャートの非推奨化

チャートリポジトリでチャートを管理する場合、チャートを非推奨にする必要がある場合があります。Chart.yamlのオプションのdeprecatedフィールドを使用して、チャートを非推奨としてマークできます。リポジトリ内のチャートの最新バージョンが非推奨としてマークされている場合、チャート全体が非推奨と見なされます。チャート名は、非推奨としてマークされていない新しいバージョンを公開することで後で再利用できます。チャートを非推奨にするワークフローは次のとおりです。

チャートのChart.yamlを更新してチャートを非推奨としてマークし、バージョンを上げます。
チャートリポジトリで新しいチャートバージョンをリリースします。
ソースリポジトリ（例：git）からチャートを削除します。

チャートタイプ

typeフィールドは、チャートのタイプを定義します。タイプは、applicationとlibraryの2つあります。Applicationはデフォルトのタイプであり、完全に操作できる標準のチャートです。ライブラリチャートは、チャートビルダーにユーティリティまたは機能を提供します。ライブラリチャートは、インストールできず、通常はリソースオブジェクトが含まれていないため、アプリケーションチャートとは異なります。

注：アプリケーションチャートはライブラリチャートとして使用できます。これは、タイプをlibraryに設定することで有効になります。その後、チャートは、すべてのユーティリティと機能を活用できるライブラリチャートとしてレンダリングされます。チャートのすべてのリソースオブジェクトはレンダリングされません。

チャートのLICENSE、README、およびNOTES

チャートには、チャートのインストール、構成、使用、およびライセンスを記述するファイルを含めることもできます。

LICENSEは、チャートのライセンスを含むプレーンテキストファイルです。チャートには、テンプレートにプログラミングロジックが含まれている場合があるため、構成のみではなく、ライセンスを含めることができます。必要に応じて、チャートによってインストールされたアプリケーション用の個別のライセンスを含めることもできます。

チャートのREADMEはMarkdown（README.md）でフォーマットする必要があり、通常は次のものを含める必要があります。

チャートが提供するアプリケーションまたはサービスの説明
チャートを実行するための前提条件または要件
values.yamlのオプションとデフォルト値の説明
チャートのインストールまたは構成に関連する可能性のあるその他の情報

ハブやその他のユーザーインターフェイスがチャートに関する詳細を表示する場合、その詳細はREADME.mdファイルの内容から取得されます。

チャートには、インストール後やリリースのステータスを表示する際に表示される、短いプレーンテキストのtemplates/NOTES.txtファイルを含めることもできます。このファイルはテンプレートとして評価され、使用上の注意、次のステップ、またはチャートのリリースに関連するその他の情報を表示するために使用できます。たとえば、データベースへの接続方法や、Web UIへのアクセス方法に関する指示を提供できます。このファイルはhelm installまたはhelm statusを実行するとSTDOUTに出力されるため、内容は簡潔にし、詳細についてはREADMEを参照するようにすることをお勧めします。

チャートの依存関係

Helmでは、1つのチャートが他の複数のチャートに依存する可能性があります。これらの依存関係は、Chart.yamlのdependenciesフィールドを使用して動的にリンクするか、charts/ディレクトリに組み込んで手動で管理することができます。

`dependencies`フィールドによる依存関係の管理

現在のチャートに必要なチャートは、dependenciesフィールドにリストとして定義されます。

dependencies:
  - name: apache
    version: 1.2.3
    repository: https://example.com/charts
  - name: mysql
    version: 3.2.1
    repository: https://another.example.com/charts

nameフィールドは、必要なチャートの名前です。
versionフィールドは、必要なチャートのバージョンです。
repositoryフィールドは、チャートリポジトリへの完全なURLです。ローカルでリポジトリを追加するには、helm repo addも使用する必要があることに注意してください。
URLの代わりにリポジトリの名前を使用することもできます。

$ helm repo add fantastic-charts https://charts.helm.sh/incubator

dependencies:
  - name: awesomeness
    version: 1.0.0
    repository: "@fantastic-charts"

依存関係を定義したら、helm dependency updateを実行すると、依存関係ファイルを使用して、指定されたすべてのチャートがcharts/ディレクトリにダウンロードされます。

$ helm dep up foochart
Hang tight while we grab the latest from your chart repositories...
...Successfully got an update from the "local" chart repository
...Successfully got an update from the "stable" chart repository
...Successfully got an update from the "example" chart repository
...Successfully got an update from the "another" chart repository
Update Complete. Happy Helming!
Saving 2 charts
Downloading apache from repo https://example.com/charts
Downloading mysql from repo https://another.example.com/charts

helm dependency updateがチャートを取得すると、charts/ディレクトリにチャートアーカイブとして保存します。したがって、上記の例では、chartsディレクトリに次のファイルが表示されると予想されます。

charts/
  apache-1.2.3.tgz
  mysql-3.2.1.tgz

依存関係におけるaliasフィールド

上記の他のフィールドに加えて、各要件エントリにはオプションのフィールドaliasを含めることができます。

依存関係チャートにエイリアスを追加すると、新しい依存関係の名前としてエイリアスを使用して、依存関係にチャートが配置されます。

別の名前でチャートにアクセスする必要がある場合は、aliasを使用できます。

# parentchart/Chart.yaml

dependencies:
  - name: subchart
    repository: http://localhost:10191
    version: 0.1.0
    alias: new-subchart-1
  - name: subchart
    repository: http://localhost:10191
    version: 0.1.0
    alias: new-subchart-2
  - name: subchart
    repository: http://localhost:10191
    version: 0.1.0

上記の例では、parentchartに対して合計3つの依存関係が得られます。

subchart
new-subchart-1
new-subchart-2

これを手動で実現する方法は、charts/ディレクトリに同じチャートを異なる名前で複数回コピー/貼り付けすることです。

依存関係におけるタグと条件フィールド

上記の他のフィールドに加えて、各要件エントリにはオプションのフィールドtagsとconditionを含めることができます。

すべてのチャートはデフォルトでロードされます。tagsまたはconditionフィールドが存在する場合、それらは評価され、適用されるチャートのロードを制御するために使用されます。

Condition - conditionフィールドには、1つ以上のYAMLパス（カンマで区切られます）が保持されます。このパスがトップレベルの親の値に存在し、ブール値に解決される場合、チャートはそのブール値に基づいて有効または無効になります。リスト内で最初に見つかった有効なパスのみが評価され、パスが存在しない場合、条件は無効になります。

Tags - tagsフィールドは、このチャートに関連付けるラベルのYAMLリストです。トップレベルの親の値では、タグを持つすべてのチャートは、タグとブール値を指定することにより有効または無効にできます。

# parentchart/Chart.yaml

dependencies:
  - name: subchart1
    repository: http://localhost:10191
    version: 0.1.0
    condition: subchart1.enabled,global.subchart1.enabled
    tags:
      - front-end
      - subchart1
  - name: subchart2
    repository: http://localhost:10191
    version: 0.1.0
    condition: subchart2.enabled,global.subchart2.enabled
    tags:
      - back-end
      - subchart2

# parentchart/values.yaml

subchart1:
  enabled: true
tags:
  front-end: false
  back-end: true

上記の例では、front-endタグを持つすべてのチャートは無効になりますが、subchart1.enabledパスは親の値で「true」と評価されるため、条件はfront-endタグを上書きし、subchart1は有効になります。

subchart2はback-endでタグ付けされており、そのタグはtrueと評価されるため、subchart2は有効になります。また、subchart2には条件が指定されていますが、親の値に対応するパスと値がないため、その条件は無効であることにも注意してください。

タグと条件でのCLIの使用

--setパラメーターは、通常どおりタグと条件の値を変更するために使用できます。

helm install --set tags.front-end=true --set subchart2.enabled=false

タグと条件の解決

（値で設定された場合）条件は常にタグを上書きします。 存在する最初の条件パスが優先され、そのチャートの後続のパスは無視されます。
タグは、「チャートのタグのいずれかがtrueの場合、チャートを有効にする」として評価されます。
タグと条件の値は、トップレベルの親の値で設定する必要があります。
値のtags:キーは、トップレベルのキーである必要があります。グローバルおよびネストされたtags:テーブルは現在サポートされていません。

依存関係を介した子値のインポート

場合によっては、子チャートの値が親チャートに伝播され、共通のデフォルトとして共有されることが望ましい場合があります。exports形式を使用する追加の利点は、将来のツールがユーザー設定可能な値をイントロスペクトできるようになることです。

インポートする値を含むキーは、YAMLリストを使用して、親チャートのdependenciesのimport-valuesフィールドで指定できます。リストの各項目は、子チャートのexportsフィールドからインポートされるキーです。

exportsキーに含まれていない値をインポートするには、child-parent形式を使用します。両方の形式の例を以下に示します。

exports形式の使用

子チャートのvalues.yamlファイルにルートにexportsフィールドが含まれている場合、インポートするキーを指定することで、その内容を親の値に直接インポートできます。以下の例のように

# parent's Chart.yaml file

dependencies:
  - name: subchart
    repository: http://localhost:10191
    version: 0.1.0
    import-values:
      - data

# child's values.yaml file

exports:
  data:
    myint: 99

インポートリストでキーdataを指定しているため、Helmは子チャートのexportsフィールドでdataキーを探し、その内容をインポートします。

最終的な親の値には、エクスポートされたフィールドが含まれます。

# parent's values

myint: 99

親キーdataは親の最終的な値に含まれていないことに注意してください。親キーを指定する必要がある場合は、「child-parent」形式を使用してください。

child-parent形式の使用

子チャートの値のexportsキーに含まれていない値にアクセスするには、インポートする値のソースキー（child）と、親チャートの値の宛先パス（parent）を指定する必要があります。

以下の例のimport-valuesは、child:パスにある値を、parent:で指定されたパスの親の値にコピーするようにHelmに指示します。

# parent's Chart.yaml file

dependencies:
  - name: subchart1
    repository: http://localhost:10191
    version: 0.1.0
    ...
    import-values:
      - child: default.data
        parent: myimports

上記の例では、subchart1の値のdefault.dataにある値は、以下に示すように親チャートの値のmyimportsキーにインポートされます。

# parent's values.yaml file

myimports:
  myint: 0
  mybool: false
  mystring: "helm rocks!"

# subchart1's values.yaml file

default:
  data:
    myint: 999
    mybool: true

親チャートの結果の値は次のようになります。

# parent's final values

myimports:
  myint: 999
  mybool: true
  mystring: "helm rocks!"

親の最終的な値には、subchart1からインポートされたmyintフィールドとmyboolフィールドが含まれるようになりました。

`charts/`ディレクトリを介して依存関係を手動で管理する

依存関係をより詳細に制御したい場合は、依存関係チャートをcharts/ディレクトリにコピーすることで、これらの依存関係を明示的に表現できます。

依存関係は展開されたチャートディレクトリである必要がありますが、その名前は_または.で始めることはできません。このようなファイルは、チャートローダーによって無視されます。

たとえば、WordPressチャートがApacheチャートに依存している場合、Apacheチャート（正しいバージョン）はWordPressチャートのcharts/ディレクトリに提供されます。

wordpress:
  Chart.yaml
  # ...
  charts/
    apache/
      Chart.yaml
      # ...
    mysql/
      Chart.yaml
      # ...

上記の例は、WordPressチャートが、charts/ディレクトリ内にそれらのチャートを含めることによって、ApacheおよびMySQLへの依存関係をどのように表現するかを示しています。

ヒント: 依存関係をcharts/ディレクトリにドロップするには、helm pullコマンドを使用します

依存関係の使用に関する運用上の側面

上記のセクションでは、チャートの依存関係を指定する方法を説明しましたが、これはhelm installおよびhelm upgradeを使用したチャートのインストールにどのように影響するのでしょうか。

「A」という名前のチャートが次のKubernetesオブジェクトを作成するとします。

namespace "A-Namespace"
statefulset "A-StatefulSet"
service "A-Service"

さらに、Aはオブジェクトを作成するチャートBに依存しています。

namespace "B-Namespace"
replicaset "B-ReplicaSet"
service "B-Service"

チャートAのインストール/アップグレード後、単一のHelmリリースが作成/変更されます。リリースは、上記のすべてのKubernetesオブジェクトを次の順序で作成/更新します。

A-Namespace
B-Namespace
A-Service
B-Service
B-ReplicaSet
A-StatefulSet

これは、Helmがチャートをインストール/アップグレードするとき、チャートとそのすべての依存関係からのKubernetesオブジェクトが

単一のセットに集約され、その後
タイプでソートされ、その後に名前でソートされ、そして
その順序で作成/更新されるためです。

したがって、チャートとその依存関係のすべてのオブジェクトを含む単一のリリースが作成されます。

Kubernetesタイプのインストール順序は、kind_sorter.goの列挙InstallOrderで指定されています（Helmソースファイルを参照）。

テンプレートと値

Helmチャートテンプレートは、Goテンプレート言語で記述されており、Sprigライブラリからの約50個のアドオンテンプレート関数と、他のいくつかの特殊関数が追加されています。

すべてのテンプレートファイルは、チャートのtemplates/フォルダーに保存されます。Helmがチャートをレンダリングすると、そのディレクトリ内のすべてのファイルがテンプレートエンジンを通過します。

テンプレートの値は、2つの方法で提供されます。

チャート開発者は、チャート内にvalues.yamlというファイルを供給できます。このファイルには、デフォルト値を含めることができます。
チャートユーザーは、値を含むYAMLファイルを供給できます。これは、helm installでコマンドラインで提供できます。

ユーザーがカスタム値を供給すると、これらの値はチャートのvalues.yamlファイルの値よりも優先されます。

テンプレートファイル

テンプレートファイルは、Goテンプレートを記述するための標準的な規則に従います（詳細については、text/template Goパッケージのドキュメントを参照してください）。テンプレートファイルの例は次のようになります。

apiVersion: v1
kind: ReplicationController
metadata:
  name: deis-database
  namespace: deis
  labels:
    app.kubernetes.io/managed-by: deis
spec:
  replicas: 1
  selector:
    app.kubernetes.io/name: deis-database
  template:
    metadata:
      labels:
        app.kubernetes.io/name: deis-database
    spec:
      serviceAccount: deis-database
      containers:
        - name: deis-database
          image: {{ .Values.imageRegistry }}/postgres:{{ .Values.dockerTag }}
          imagePullPolicy: {{ .Values.pullPolicy }}
          ports:
            - containerPort: 5432
          env:
            - name: DATABASE_STORAGE
              value: {{ default "minio" .Values.storage }}

上記の例は、https://github.com/deis/charts を大まかに基にしたもので、Kubernetes レプリケーションコントローラーのテンプレートです。これは以下の 4 つのテンプレート値（通常は values.yaml ファイルで定義されます）を使用できます。

imageRegistry: Docker イメージのソースレジストリ。
dockerTag: Docker イメージのタグ。
pullPolicy: Kubernetes のプルポリシー。
storage: ストレージバックエンド。デフォルトは "minio" に設定されています。

これらの値はすべてテンプレートの作成者が定義します。Helm はパラメータを要求したり、指示したりしません。

多くの動作するチャートを見るには、CNCF の Artifact Hub を参照してください。

事前定義された値

values.yaml ファイル（または --set フラグ）を介して提供される値は、テンプレート内の .Values オブジェクトからアクセスできます。しかし、テンプレートでアクセスできる他の事前定義されたデータもあります。

以下の値は事前定義されており、すべてのテンプレートで使用可能で、上書きできません。すべての値と同様に、名前は大文字と小文字を区別します。

Release.Name: リリースの名前（チャートの名前ではありません）。
Release.Namespace: チャートがリリースされた名前空間。
Release.Service: リリースを実行したサービス。
Release.IsUpgrade: 現在の操作がアップグレードまたはロールバックの場合、true に設定されます。
Release.IsInstall: 現在の操作がインストールの場合、true に設定されます。
Chart: Chart.yaml の内容。したがって、チャートのバージョンは Chart.Version として取得でき、メンテナーは Chart.Maintainers に存在します。
Files: チャート内のすべての特別なファイルではないファイルを含むマップのようなオブジェクト。これにより、テンプレートにアクセスすることはできませんが、存在する追加のファイルにアクセスできます（.helmignore を使用して除外されている場合を除く）。ファイルには、{{ index .Files "file.name" }} を使用するか、{{.Files.Get name }} 関数を使用してアクセスできます。また、{{ .Files.GetBytes }} を使用してファイルの内容を []byte としてアクセスすることもできます。
Capabilities: Kubernetes のバージョン ({{ .Capabilities.KubeVersion }}) とサポートされている Kubernetes API バージョン ({{ .Capabilities.APIVersions.Has "batch/v1" }}) に関する情報を含むマップのようなオブジェクト。

注: 不明な Chart.yaml フィールドはすべて削除されます。それらは Chart オブジェクト内ではアクセスできません。したがって、Chart.yaml を使用して、任意の構造化データをテンプレートに渡すことはできません。ただし、値ファイルはそれに使用できます。

値ファイル

前のセクションのテンプレートを考慮すると、必要な値を指定する values.yaml ファイルは次のようになります。

imageRegistry: "quay.io/deis"
dockerTag: "latest"
pullPolicy: "Always"
storage: "s3"

値ファイルは YAML でフォーマットされています。チャートにはデフォルトの values.yaml ファイルが含まれている場合があります。Helm インストールコマンドを使用すると、ユーザーは追加の YAML 値を指定して値を上書きできます。

$ helm install --generate-name --values=myvals.yaml wordpress

値がこの方法で渡されると、デフォルトの値ファイルにマージされます。たとえば、次のような myvals.yaml ファイルを考えます。

storage: "gcs"

これがチャート内の values.yaml とマージされると、生成される結果の内容は次のようになります。

imageRegistry: "quay.io/deis"
dockerTag: "latest"
pullPolicy: "Always"
storage: "gcs"

最後のフィールドのみが上書きされたことに注意してください。

注: チャート内に含まれるデフォルトの値ファイルは、必ず values.yaml という名前でなければなりません。ただし、コマンドラインで指定されたファイルには任意の名前を付けることができます。

注: --set フラグが helm install または helm upgrade で使用されている場合、これらの値はクライアント側で単に YAML に変換されます。

注: 値ファイルに必要なエントリが存在する場合、「required」関数を使用して、チャートテンプレートで必須として宣言できます。

これらの値はすべて、.Values オブジェクトを使用してテンプレート内でアクセスできます。

apiVersion: v1
kind: ReplicationController
metadata:
  name: deis-database
  namespace: deis
  labels:
    app.kubernetes.io/managed-by: deis
spec:
  replicas: 1
  selector:
    app.kubernetes.io/name: deis-database
  template:
    metadata:
      labels:
        app.kubernetes.io/name: deis-database
    spec:
      serviceAccount: deis-database
      containers:
        - name: deis-database
          image: {{ .Values.imageRegistry }}/postgres:{{ .Values.dockerTag }}
          imagePullPolicy: {{ .Values.pullPolicy }}
          ports:
            - containerPort: 5432
          env:
            - name: DATABASE_STORAGE
              value: {{ default "minio" .Values.storage }}

スコープ、依存関係、および値

値ファイルは、最上位のチャートだけでなく、そのチャートの charts/ ディレクトリに含まれるすべてのチャートの値も宣言できます。または、別の言い方をすれば、値ファイルは、チャートとその依存関係の両方に値を供給できます。たとえば、上記の WordPress デモチャートには、mysql と apache の両方が依存関係としてあります。値ファイルは、これらのすべてのコンポーネントに値を供給できます。

title: "My WordPress Site" # Sent to the WordPress template

mysql:
  max_connections: 100 # Sent to MySQL
  password: "secret"

apache:
  port: 8080 # Passed to Apache

上位レベルのチャートは、下位で定義されたすべての変数にアクセスできます。したがって、WordPress チャートは、MySQL パスワードを .Values.mysql.password としてアクセスできます。ただし、下位レベルのチャートは親チャートのものにアクセスできないため、MySQL は title プロパティにアクセスできません。また、apache.port にもアクセスできません。

値は名前空間化されていますが、名前空間はプルーニングされます。そのため、WordPress チャートの場合、MySQL パスワードフィールドに .Values.mysql.password としてアクセスできます。ただし、MySQL チャートの場合、値のスコープが縮小され、名前空間プレフィックスが削除されているため、パスワードフィールドは単に .Values.password として認識されます。

グローバル値

2.0.0-Alpha.2 以降、Helm は特別な「グローバル」値をサポートしています。前の例の修正版を考えてみましょう。

title: "My WordPress Site" # Sent to the WordPress template

global:
  app: MyWordPress

mysql:
  max_connections: 100 # Sent to MySQL
  password: "secret"

apache:
  port: 8080 # Passed to Apache

上記では、値 app: MyWordPress を持つ global セクションが追加されています。この値は、すべてのチャートで .Values.global.app として使用できます。

たとえば、mysql テンプレートは app を {{ .Values.global.app}} としてアクセスでき、apache チャートも同様です。事実上、上記の値ファイルは次のように再生成されます。

title: "My WordPress Site" # Sent to the WordPress template

global:
  app: MyWordPress

mysql:
  global:
    app: MyWordPress
  max_connections: 100 # Sent to MySQL
  password: "secret"

apache:
  global:
    app: MyWordPress
  port: 8080 # Passed to Apache

これにより、ラベルのような metadata プロパティを設定するなど、1 つの最上位変数をすべてのサブチャートと共有する方法が提供されます。

サブチャートがグローバル変数を宣言した場合、そのグローバル変数は下方向（サブチャートのサブチャートへ）に渡されますが、上方向（親チャートへ）には渡されません。サブチャートが親チャートの値に影響を与える方法はありません。

また、親チャートのグローバル変数が、サブチャートのグローバル変数よりも優先されます。

スキーマファイル

場合によっては、チャートのメンテナーが値の構造を定義したい場合があります。これは、values.schema.json ファイルでスキーマを定義することで実行できます。スキーマは JSON スキーマとして表されます。それは次のようなものかもしれません。

{
  "$schema": "https://json-schema.dokyumento.jp/draft-07/schema#",
  "properties": {
    "image": {
      "description": "Container Image",
      "properties": {
        "repo": {
          "type": "string"
        },
        "tag": {
          "type": "string"
        }
      },
      "type": "object"
    },
    "name": {
      "description": "Service name",
      "type": "string"
    },
    "port": {
      "description": "Port",
      "minimum": 0,
      "type": "integer"
    },
    "protocol": {
      "type": "string"
    }
  },
  "required": [
    "protocol",
    "port"
  ],
  "title": "Values",
  "type": "object"
}

このスキーマは値を検証するために適用されます。検証は、以下のいずれかのコマンドが呼び出されたときに発生します。

helm install
helm upgrade
helm lint
helm template

このスキーマの要件を満たす values.yaml ファイルの例は次のようになります。

name: frontend
protocol: https
port: 443

スキーマは最終的な .Values オブジェクトに適用され、values.yaml ファイルだけに適用されるわけではないことに注意してください。これは、チャートが以下に示す適切な --set オプションでインストールされている場合、次の yaml ファイルが有効であることを意味します。

name: frontend
protocol: https

helm install --set port=443

さらに、最終的な .Values オブジェクトは、すべてのサブチャートスキーマに対してチェックされます。これは、サブチャートの制限を親チャートで回避できないことを意味します。これは逆方向にも機能します。サブチャートの values.yaml ファイルで満たされていない要件がサブチャートにある場合、親チャートは有効であるためにこれらの制限を満たす必要があります。

参照

テンプレート、値、スキーマファイルを作成する際には、役立ついくつかの標準的な参照があります。

カスタムリソース定義（CRD）

Kubernetes は、新しいタイプの Kubernetes オブジェクトを宣言するためのメカニズムを提供します。カスタムリソース定義（CRD）を使用すると、Kubernetes 開発者はカスタムリソースタイプを宣言できます。

Helm 3 では、CRD は特別な種類のオブジェクトとして扱われます。それらはチャートの残りの部分の前にインストールされ、いくつかの制限があります。

CRD YAML ファイルは、チャート内の crds/ ディレクトリに配置する必要があります。複数の CRD（YAML の開始マーカーと終了マーカーで区切られています）を同じファイルに配置できます。Helm は、CRD ディレクトリ内のすべてのファイルを Kubernetes にロードしようとします。

CRD ファイルはテンプレート化できません。それらはプレーンな YAML ドキュメントである必要があります。

Helm が新しいチャートをインストールすると、CRD をアップロードし、CRD が API サーバーで使用可能になるまで一時停止し、テンプレートエンジンを起動してチャートの残りをレンダリングし、Kubernetes にアップロードします。この順序付けのため、CRD 情報は Helm テンプレートの .Capabilities オブジェクトで使用でき、Helm テンプレートは CRD で宣言されたオブジェクトの新しいインスタンスを作成できます。

たとえば、チャートの crds/ ディレクトリに CronTab の CRD がある場合、templates/ ディレクトリに CronTab 種のインスタンスを作成できます。

crontabs/
  Chart.yaml
  crds/
    crontab.yaml
  templates/
    mycrontab.yaml

crontab.yaml ファイルには、テンプレートディレクティブなしで CRD が含まれている必要があります。

kind: CustomResourceDefinition
metadata:
  name: crontabs.stable.example.com
spec:
  group: stable.example.com
  versions:
    - name: v1
      served: true
      storage: true
  scope: Namespaced
  names:
    plural: crontabs
    singular: crontab
    kind: CronTab

次に、テンプレート mycrontab.yaml は新しい CronTab を作成できます（通常どおりにテンプレートを使用）。

apiVersion: stable.example.com
kind: CronTab
metadata:
  name: {{ .Values.name }}
spec:
   # ...

Helm は、templates/ のものをインストールする前に、CronTab 種がインストールされ、Kubernetes API サーバーから利用可能であることを確認します。

CRD の制限事項

Kubernetes のほとんどのオブジェクトとは異なり、CRD はグローバルにインストールされます。そのため、Helm は CRD の管理において非常に慎重なアプローチを取ります。CRD には次の制限があります。

CRD は再インストールされません。Helm が crds/ ディレクトリ内の CRD がすでに存在すると判断した場合（バージョンに関係なく）、Helm はインストールまたはアップグレードを試行しません。
CRD は、アップグレードまたはロールバック時にインストールされません。Helm はインストール操作でのみ CRD を作成します。
CRD は削除されません。CRD を削除すると、クラスター内のすべての名前空間で CRD の内容が自動的に削除されます。したがって、Helm は CRD を削除しません。

CRD をアップグレードまたは削除したいオペレーターは、手動で慎重に行うことをお勧めします。

Helm を使用したチャートの管理

helm ツールには、チャートを操作するためのいくつかのコマンドがあります。

新しいチャートを作成できます。

$ helm create mychart
Created mychart/

チャートを編集したら、helm はそれをチャートアーカイブにパッケージ化できます。

$ helm package mychart
Archived mychart-0.1.-.tgz

また、helm を使用して、チャートの書式設定や情報に関する問題を検出することもできます。

$ helm lint mychart
No issues found

チャートリポジトリ

チャートリポジトリとは、1 つ以上のパッケージ化されたチャートを格納する HTTP サーバーです。helm を使用してローカルチャートディレクトリを管理できますが、チャートを共有する場合、推奨されるメカニズムはチャートリポジトリです。

YAML ファイルと tar ファイルを提供でき、GET リクエストに応答できる HTTP サーバーは、リポジトリサーバーとして使用できます。Helm チームは、ウェブサイトモードが有効になっている Google Cloud Storage や、ウェブサイトモードが有効になっている S3 など、いくつかのサーバーをテストしています。

リポジトリは主に、リポジトリが提供するすべてのパッケージのリストと、それらのパッケージの取得と検証を可能にするメタデータを含む、index.yaml という特別なファイルの存在によって特徴付けられます。

クライアント側では、リポジトリは helm repo コマンドで管理されます。ただし、Helm はチャートをリモートリポジトリサーバーにアップロードするためのツールを提供していません。これは、そうすることで、実装サーバーに多大な要件が追加され、リポジトリを設定するための障壁が高くなるためです。

チャートスターターパック

helm create コマンドは、オプションの --starter オプションを使用して、「スターターチャート」を指定できます。また、スターターオプションには短いエイリアス -p があります。

使用例

helm create my-chart --starter starter-name
helm create my-chart -p starter-name
helm create my-chart -p /absolute/path/to/starter-name

スターターは通常のチャートと変わりませんが、$XDG_DATA_HOME/helm/starters に配置されます。チャート開発者は、特にスターターとして使用するように設計されたチャートを作成できます。そのようなチャートは、以下の点を考慮して設計する必要があります。

Chart.yaml はジェネレーターによって上書きされます。
ユーザーは、そのようなチャートの内容を変更することを期待するため、ドキュメントでユーザーがどのように変更できるかを示す必要があります。
<CHARTNAME> のすべての出現箇所は、指定されたチャート名に置き換えられ、スターターチャートをテンプレートとして使用できるようにします。ただし、一部の変数ファイルは除きます。たとえば、vars ディレクトリのカスタムファイルや特定の README.md ファイルでは、<CHARTNAME> は内部では上書きされません。さらに、チャートの説明は継承されません。

現在、チャートを $XDG_DATA_HOME/helm/starters に追加する唯一の方法は、手動でそこにコピーすることです。チャートのドキュメントでは、そのプロセスについて説明することをお勧めします。