コンテンツにスキップ
AggregaAggrega
言語の選択: 日本語
このページは機械翻訳されています。英語の原文を読む。

Helm-Chart Provider

helm-chart プロバイダーは、アセンブリパスごとにパッケージ化された Helm アンブレラチャートを生成します。helm プロバイダーが GitOps で直接利用するためのフラットな Kubernetes YAML を出力するのに対し、helm-chart はチャートの雛形(アンブレラの Chart.yaml + values.yaml と、寄与する各ノードにつき 1 つのサブチャート)を出力し、下流のツールはそれを helm install でインストールすることも、環境ごとのさらなるカスタマイズのためにベンダリングすることもできます。このプロバイダーは (path, provider) ごとにアセンブルします。helm-chart Recipe にバインドされたすべてのノードは、境界の評価済み directory: にコンポーネントごとの subDirectory: を結合した位置でアンブレラに寄与します。同じパスに評価される 2 つの境界は 1 つのマージされたアンブレラチャートにまとめられ、そのチャートはすべての寄与元をサブチャートの依存関係として列挙します。

ソースチャートからコピーされたサブチャートのテンプレートは、作成者が記述した内容を持ちます。境界の syncWave: <integer> の値、フックの helm.sh/hook-weight、Aggrega の来歴ラベルは、チャートがそれらを記述している場合にのみテンプレートに含まれます。レンダリングするすべてのリソースに argocd.argoproj.io/sync-wave: "<N>"、helm.sh/hook-weight: "<N>"、来歴ラベルを付与するのは helm プロバイダーです。このプロバイダーがサブチャートに追加する、$import: で読み込まれた artifact は、来歴ラベルと argocd.argoproj.io/sync-wave アノテーションを持ち、helm.sh/hook-weight は持ちません(後述の「artifacts: 注入ルール」を参照)。ArgoCD は sync-wave アノテーションを読み取り、Helm はフックの重みを読み取ります。

このページは helm-chart プロバイダーのオーサリングリファレンスです。helm と helm-chart の分担については、Status ページの Providers セクションを参照してください。プロバイダー横断の入力合成モデルについては、architecture/16-recipe-input-composition.md を参照してください。

サポートされる入力の種類

helm-chart プロバイダーは 2 種類の入力を受け付けます。

  • ソースモード。 source: <chart-path> を持つ Recipe は、ディスク上の Helm チャートディレクトリを指します。チャートはサブチャートとしてアンブレラ構造にコピーされ、チャート自身の name を除いてそのまま保持されます。「The chart name the umbrella owns」を参照してください。ノード単位でのレンダリングやテンプレート処理は行われません。Aggrega の役割は合成(境界のノード全体にわたるアンブレラの組み立て)であり、テンプレートの評価ではありません。
  • $import: で読み込む artifacts: モード。 エントリごとに $import: として記述された artifacts: エントリを持つ Recipe は、追加のテンプレートファイルを宣言します。helm-chart プロバイダーは、ソースチャートのコピー後にこれらをサブチャートの templates/ ディレクトリに注入します。各ファイルは [[ ]] 区切り文字を使って Aggrega のテンプレートコンテキストに対して事前にテンプレート処理されるため(後述の「artifacts: 注入ルール」を参照)、同じファイル内の {{ }} による Helm テンプレートは下流の helm install によるレンダリングまでそのまま残ります。

workload: を宣言する helm-chart 向けの Recipe は、レンダリング前に拒否されます。その拒否は、宣言していない入力種別に対してどのプロバイダーも返すものと同じで、このプロバイダーがサポートする種別を示し、合成を行うプロバイダーを作成者に案内します。

provider does not support the node’s input kind (node “api”). provider “helm-chart” does not support synthesized recipes (this provider supports: sourced); declare one of the supported input kinds, or target a provider that supports synthesized(プロバイダーはノードの入力種別をサポートしていません(ノード「api」)。プロバイダー「helm-chart」は合成された recipe をサポートしていません(このプロバイダーがサポートするもの: sourced)。サポートされている入力種別のいずれかを宣言するか、合成をサポートするプロバイダーを対象にしてください)

この分担は意図的なものです。ワークロードの合成(抽象的な Workload を Kubernetes リソースに変換すること)は helm プロバイダーだけが担います。helm-chart の役割は、作成者がすでに用意したチャートに対するアンブレラとサブチャートの合成です。

helm-chart 向けの Recipe は、インラインコンテンツの artifacts: エントリ($import: で読み込む参照ではなく、ファイル本体を Recipe 内にインラインで持つブロックスカラーを値とするエントリ)も宣言できます。インラインコンテンツのエントリは、記述されたキーのままサブチャートのルートに配置されます。templates/ プレフィックスは付かず、来歴の挿入も行われません。チャート自身のテンプレートは、このような独立したファイルを Helm の .Files.Get / .Files.Glob で読み取ります(ファイルから ConfigMap を作る標準的なパターン)。そのため、チャートルートのファイルはエラーではなく、正当で第一級の形です。

どちらの形式も、配置前に Aggrega の [[ ]] 区切り文字で評価されます。 そのため、どちらの形式の本体も Recipe のピラーコンテキストを参照できます。どちらの本体でも {{ }} は変更されず、下流の helm install 時に Helm ディレクティブになります。両形式で異なるのは、ファイルの配置先と、来歴がマージされるかどうかです。

  • $import: で読み込むエントリはテンプレートファイルです。評価後(後述の「artifacts: 注入ルール」を参照)、来歴がマージされた状態でサブチャートの templates/ ディレクトリに注入され、Helm はチャート自身のテンプレートとともにこれをマニフェストとしてレンダリングします。
  • インラインコンテンツのエントリは独立したデータファイルです。評価後、評価結果から変更されず、来歴もマージされない状態でチャートルートに配置され、.Files による利用に供されます。

artifacts: の注入ルール

helm-chart の Recipe がエントリごとの $import: によって artifacts: エントリを宣言する場合、各 $import: の値は、Recipe 自身のディレクトリ(ディスク上で Recipe の YAML を含むディレクトリ)からの相対パスとして解決されるテンプレートファイルへのパスです。provider は次の処理を行います。

  1. 各ファイルの内容を読み込みます。
  2. Aggrega のデリミタ [[ ]] を使い、Recipe のテンプレートコンテキスト(Recipe の valuesMapping: が評価されるのと同じコンテキスト)に対して内容を事前にテンプレート処理します。ファイル内容の {{ }} はそのまま残され、helm install の時点で Helm のテンプレートディレクティブになります。
  3. 各ファイルを umbrella のアセンブリパス配下の charts/<instance-id>/templates/<authored-key> に書き込みます。バンドルのファイルはそのキーの下にネストされます。ファイル名はエントリが記述されたキーで決まります。$import: のパスは内容を選択するだけで名前には何も寄与しないため、そのパス内のディレクトリ構造が出力に現れることはありません。

[[ ]] / {{ }} の二重デリミタの使い分けが、要となる詳細です。典型的な $import: で読み込まれる artifact ファイルでは、Aggrega 時の補間(例: [[ .values.image ]])と Helm 時の補間(例: {{ .Release.Namespace }})が混在することがあります。各デリミタの組はそれぞれのフェーズで処理されます。Aggrega は、ファイルが配置される前のコンパイル時に [[ ]] を解決し、Helm は、umbrella が出荷された後のインストール時に {{ }} を解決します。

ソースチャートのテンプレートと $import: で読み込まれた artifact の注入との間でファイル名が衝突すると、CATALOG_ERROR が発生します。この診断は、衝突する出力パス(templates/cm.yaml など)と、それを生成した 2 つの入力種別を示します。作成者は、artifact のキーまたはチャート自身のテンプレートの名前を変更することで衝突を解消します。

source: のキーセット

helm-chart プロバイダーの source: はチャートを指定し、source: フィールドが取る 2 つの形の両方を受け付けます。いずれも helm プロバイダーの source: キーセットの説明どおりに読み取られます。すなわち、素のファイルシステムパス文字列と、url: が場所を保持する構造化オブジェクトです。url: がファイルシステムパスを指す場合は何も取得されず、チャートはディスクから読み込まれます。トランスポートスキーム(たとえば kind: helm-oci-chart を伴う oci://…)を持つ場合は、aggrega pull がチャートを取得して固定し、ビルドはディスクから読み込んだチャートと同じ条件で、それをキャッシュからアンブレラへサブチャートとしてコピーします。

spec:
capability: helm-chart
source: ./charts/api-server # filesystem path to a chart directory
valuesMapping: |
image: "{{ .values.image }}"
replicaCount: {{ optional .infra `replicas` 2 }}

ソースパスにあるチャートは、そのルートに有効な Chart.yaml を含んでいなければなりません。存在しない場合は、コピーの実行前に明確なエラーが表示されます。チャートのディレクトリ構成はコピー時に保持され、合成後のサブチャートディレクトリには templates/、values.yaml、Chart.yaml、その他すべてのファイルが存在します。どのファイルも、コメント、キーの順序、クォートに至るまで書いたとおりのバイト列で届きます。唯一の例外はチャート自身の Chart.yaml の name フィールドで、これはアンブレラが設定します。「アンブレラが所有するチャート名」を参照してください。

チャートを指定し損なう 2 つの方法はどちらも拒否され、その 2 つの拒否は 異なる場所から来ます。capability を切り替えたときに変わるのは一方だけなので、 知っておく価値があります。存在するのに何も宣言していない source: は、 どのプロバイダーも実行される前にコンパイラによって拒否されるため、Recipe が どの capability を指定しても結果は同じです。診断は、ソースなしモードにするには フィールドを省略するか、空でないパスを指定するよう伝えます。source: を完全に省略することは 正当な記述であり、Recipe がソースなしモードを要求する方法ですが、 ここで拒否されるのは helm-chart がソースありの入力種別しか宣言していないためで、 コンパイラは、宣言していない入力種別を要求されたあらゆる capability に対するのと 同じメッセージでその組み合わせを拒否します。helm-chart 固有なのは宣言であって、 独自の拒否ではありません。workload: ブロックから生成される Kubernetes リソースには、 代わりに helm capability を使用してください。

omits: を宣言する Recipe は拒否されます。omits: キーはソースがレンダリングするドキュメントをビルドから除外しますが、このプロバイダーはビルド時に ドキュメントを一切レンダリングしません。チャートをアンブレラにコピーし、チャートの テンプレートはアンブレラのインストール時にレンダリングされます。何もレンダリングされなければ 除外するものもないため、このプロバイダーはこのキーに従うことを宣言しておらず、 これを宣言する Recipe または FeatureRecipe は何かがコピーされる前に拒否されます。 The provider does not support omits(プロバイダーは omits をサポートしていません)を参照してください。 Recipe の隣に置いたチャートであれば、そこにある .aggregaignore に 1 行書くことで、 次に Recipe が固定されたときから、代わりにチャートのファイルを除外できます。取得したチャートで 出力からドキュメントを取り除く必要がある場合は、このキーに従う helm プロバイダーを通して レンダリングしてください。

パスをキーとする合成 — アンブレラの形

このプロバイダーは、アセンブリパスごとに 2 つのフェーズで実行されます。

  1. コントリビューターごとのコピー。 helm-chart Recipe にバインドされた各ノードについて、プロバイダーはソースチャートのディレクトリツリー全体をサブチャートのスロットにコピーします。ファイルはコントリビューターごとの出力マップにフラットに配置されます。アセンブラーはコントリビューターを配置するサブディレクトリとして charts を指定し、オーケストレーターはアンブレラを組み立てる際に、その下に各コントリビューター専用のディレクトリを与えます。コンポーネントの場合は charts/<instance_id>/ です。Feature のアタッチメントもコントリビューターであり(チャートをベンダリングする場合も、helm プロバイダーを通じてマニフェストをレンダリングする場合も同様です)、コンポーネントのディレクトリの内側ではなく隣にディレクトリを持ちます。「アタッチメントのチャートの配置先」を参照してください。
  2. (path, provider) ごとのアンブレラの組み立て。 パスに対するノードごとのコピーがすべて完了すると、アセンブラーはアセンブリパスのルートにアンブレラの Chart.yaml と values.yaml を出力します。アンブレラはコントリビュートするノードごとに 1 つの依存関係を宣言し、ノードごとの値をインスタンス ID をキーとするサブブロックの下にルーティングします。アセンブリパスが複数のバウンダリ(directory: を共有するバウンダリ)からコントリビューターを受け取る場合、すべてのコントリビューターが同じアンブレラの依存関係として配置されます。

アンブレラの Chart.yaml は次の形になります。

apiVersion: v2
name: <effective-chart-name> # see "Chart-name resolution" below
version: 0.1.0
description: Aggrega umbrella chart for boundary "<assembly-path>"
dependencies:
- name: <encoded-instance-id> # the name the placed sub-chart carries
version: <user-chart-version> # from the source chart's Chart.yaml
alias: <encoded-instance-id> # see "How a name is derived" below
repository: file://charts/<instance_id> # the sub-chart's own directory

チャート名の解決

アンブレラのチャートの name は、バウンダリのアノテーションのカスケードを通じて解決されます。コントリビュートする各バウンダリの有効な aggrega.ai/chart-name アノテーション(バウンダリツリーを上にたどってカスケードで解決された値)がアンブレラの名前を決定します。解決された値は、他のあらゆる ID と同様にチャート名の位置向けにエンコードされるため、以下の規則が保持する英字、数字、アンダースコア、ハイフンのみを含む値は、そのままチャートに届きます。アセンブリパスが複数のバウンダリからコントリビューターを受け取る場合、すべてのコントリビューターの有効な aggrega.ai/chart-name は同じ値に解決されなければなりません(MUST)。不一致があると、競合する値とコントリビュートしているバウンダリを示す診断とともにビルドが停止します。

カスケードは DRY との緊張関係を自然に解消します。親バウンダリで aggrega.ai/chart-name を一度宣言すれば、子バウンダリはカスケードを通じてそれを継承します。共通の親を持たない兄弟バウンダリは、一致する値を明示的に宣言する必要があります。カスケードのどこにも aggrega.ai/chart-name が宣言されていないバウンダリは、aggregate 名とアセンブリパス(dist/ 配下のアンブレラの出力ディレクトリ。例: boundaries/data/helm-chart)にフォールバックし、それぞれが以下で説明するとおりにエンコードされて結合されます。

各依存関係エントリの name は、配置されたサブチャートが持つ名前、つまりコンポーネントインスタンス自身のエンコードされた ID であり、alias と同じ値です。その理由は「アンブレラが所有するチャート名」で説明しています。その version は、引き続きソースチャート自身の Chart.yaml にあるバージョンです。alias はサブチャートの値を values.yaml.<alias>.* の下にスコープします。これは Helm のアンブレラの値の慣例に合致しており、アンブレラのインストール時にインスタンスごとの値が正しく伝播します。

コンポーネントのサブチャートディレクトリは instance_id を記述されたとおりに保持するため、charts/<instance_id>/ がそのファイルの配置先であり、依存関係の repository が指す場所です。したがって、同じソースチャートの 2 つのインスタンスはファイルシステム上で衝突することなく共存し、それぞれが自身の alias の下に独自の値ブロックを保持します。

依存関係の name と repository は異なる文字列であり、それは設計によるものです。 name はその場所にあるチャートが宣言する(DECLARES)ものです。Helm は子チャート自身が宣言した名前によって依存関係を子チャートにバインドするからです。repository はそのチャートが置かれている場所です。コンポーネントの場合、両者はどちらも同じインスタンス ID から導出されるため、たまたま同じように見えます。Feature のアタッチメントの場合は異なります。宣言された名前はアタッチメントの合成された ID を持ち、ディレクトリはその 2 つの座標を結合したものを持つため、一方を他方として読むと存在しないものを指すことになります。

アタッチメントのチャートの配置先

チャートをベンダリングする Feature のアタッチメントは、アタッチ先のコンポーネントの隣、charts/ の 1 階層下に専用のディレクトリを持ちます。

charts/
├── api/ # the component's own chart
├── api--guardrail/ # a Feature attached to `api` under `guardrail`
└── api--audit/ # a second Feature attached to the same component

コンポーネントではなくバウンダリにアタッチされた Feature には名前を付けるホストコンポーネントがないため、そのディレクトリはインスタンス名のみになります: charts/aux/。

内側ではなく隣に置く理由。 Helm は charts/* にある子チャートを検出します。これは 1 階層のみで、再帰的な走査ではありません。それより深い場所に置かれたチャートは何の子でもなく、別の子のディレクトリ内にあるデータであり、.Files を通じてしか到達できません。そのため、コンポーネント自身のチャートディレクトリ内に置かれたチャートは、出力にコピーされ、ビルドを成功させますが、デプロイするものには何のリソースも寄与せず、しかもそれを報告するものは何もありません。各コントリビューターを専用のトップレベルディレクトリに配置することで、アタッチメントのリソースがレンダリングされます。

アンブレラは、アタッチメントも依存関係の 1 つとして宣言します。両方が必要です。charts/ の下に存在し dependencies: にないチャートは lint エラーになり、dependencies: で宣言されていても一致する子チャートが存在しない場合、アンブレラは読み込みを拒否します。

2 つの座標は単純に連結されるのではなく、結合されます。 ディレクトリ名は、以下で説明するのと同じエスケープ規則を各座標に適用してから -- で結合することで、ホストとインスタンスから合成されます。両者を直接 -- でつなげると曖昧になります。a--b という名前のホストとインスタンス c、そしてホスト a とインスタンス b--c が同じディレクトリになってしまいます。各座標を先にエンコードすることで両者は区別され、座標内に記述された -- は -zh- として現れます。

ディレクトリ名に使用できる文字。 大文字・小文字の ASCII 英字、数字、ピリオド、アンダースコアは記述したとおりに通過するため、API--aux や web.api--aux は期待どおりに読めます。記述したハイフンは、その次の文字がこれらのいずれかである場合には保持されるため、web-api--aux は変わりません。二重のハイフンはエスケープされます。そのペアが結合を表すからです。それ以外の文字は、チャート名と同じ規則でエスケープされます。このように範囲が定められているのは、これらのディレクトリ名がディスク上のパスであると同時に、依存関係の file:// ポインターが解決する場所でもあり、ファイル名としては問題のない文字が URL を切り詰めたり再デコードさせたりすることがあるためです。

値はディレクトリではなく、宣言された名前に従います。 子チャートの値はそのチャートが宣言する名前の下にスコープされるため、上記のチャートの値はディレクトリではなく、api--guardrail の宣言された名前である cfr-zh-api-zh-guardrail としてアドレス指定されます。

そのキーを自分で書くことはありません。 値はアタッチメントに記述し、アンブレラの values.yaml は、配置されたチャートがアドレス指定されるアドレスにすでにブロックがある状態で自動的に合成されます。コンポーネントにアタッチされた Feature の場合、それはアタッチメントに宣言する values: であり、FeatureRecipe 自身の valuesMapping: によって読み取られます。バウンダリにアタッチされた Feature の場合は、そこで宣言する infra: です。バウンダリにアタッチされた Feature にはコンポーネントの値の柱がないためです。いずれの場合も、valuesMapping: が解決するマップが、アンブレラ内のアタッチメント専用のブロックになります。

# the umbrella's values.yaml, composed for you
api: # the component's own chart
replicaCount: 3
cfr-zh-api-zh-guardrail: # the chart the Feature attached under `guardrail` brought
auditEndpoint: "https://audit.internal"

これらの値の経路はこれだけです。 Feature が持ち込むチャートは、「アンブレラが所有するチャート名」で説明する単一のマニフェストフィールドを除き、作成者が書いたとおりのファイルで届きます。そのため、そのチャートに値を書き込むものは何もなく、値を供給するのはアンブレラのブロックです。ブロックが届かなかったチャートは壊れたチャートではありません。自身の values.yaml に含まれるデフォルトでレンダリングされ、成功を報告します。オーサリング中に違いを確認したい場合は、気付けるような値をデフォルトに設定してください。

FeatureRecipe が helm プロバイダーを通じてレンダリングするアタッチメント

helm ケイパビリティの FeatureRecipe をこのターゲット上のコンポーネントにアタッチすると、チャートではなく完成した Kubernetes マニフェストがもたらされます。それらは helm プロバイダーがレンダリングしたとおりにアタッチメント自身のディレクトリに配置され、プロバイダーはそのディレクトリを Helm がインストールできるチャートにするための 2 つのものを与えます。アタッチメント自身の名前をバージョン 0.1.0 で宣言する最小限の Chart.yaml と、レンダリングされた各 YAML ファイルをその名前で Helm の .Files.Get を通じて出力する 1 つのテンプレート templates/rendered.yaml です。

charts/api--guardrail/
├── Chart.yaml # apiVersion: v2, name: cfr-zh-api-zh-guardrail, version: 0.1.0
├── guardrail-config.yaml # the manifest the helm provider rendered
└── templates/
└── rendered.yaml # {{ .Files.Get "guardrail-config.yaml" }}

宣言される名前は、同じアタッチメントがチャートをベンダリングした場合にそのチャートが宣言する名前と同じです。そのため、アンブレラの依存関係エントリと values ブロックは、上で説明したとおりにアドレス指定されます。.Files.Get はファイルのバイトを再評価せずにそのまま返すため、リテラルのテンプレート括弧を持つマニフェスト(アラートルールの {{ $labels.instance }} やダッシュボードのクエリなど)は、それらを保ったままインストールされます。その値は helm プロバイダーがマニフェストをレンダリングした時点でマニフェストに解決済みであるため、アンブレラの values.yaml がその名前の下に持つブロックは何にも読まれません。

アンブレラが所有するチャート名

ベンダリングしたチャートの中で Aggrega が変更する唯一のものは、そのチャート自身の name フィールドです。 配置されたチャートの Chart.yaml では、name はそのチャートを提供したもののエンコード済みアイデンティティに設定されます。

コンポーネントの場合、それはコンポーネントインスタンス自身のアイデンティティ(依存関係の alias と同じ値)であり、アンブレラの依存関係エントリもその値を指定するため、両側は常に一致します。

Feature アタッチメントが持ち込むチャートはそれ自体が独立したコントリビューターであり、アタッチ先のコンポーネントのアイデンティティを繰り返すのではなく、自身のアイデンティティを宣言します。そのアイデンティティは、記述した 2 つのもの(アタッチメントをホストするコンポーネントと、Feature がアタッチされる名前)から、コンポーネントではなくアタッチメントのアイデンティティであることを示す短い接頭部の後に合成されます。合成された値は、他のアイデンティティとまったく同様に、以下の導出によってチャート名の位置用に書き出されます。

したがって、チャートをベンダリングする Feature を api という名前のコンポーネントに guardrail という名前でアタッチすると、cfr-zh-api-zh-guardrail を宣言するチャートが配置され、そのコンポーネント自身のチャートは引き続き api を宣言します。両者は別々のコントリビューターであり、どちらもホストの名前を宣言するのではなく、それぞれが独自の名前を宣言します。

チャート内のそれ以外のものには一切手を加えません。他のすべてのファイルは記述したとおりにバイト単位で届き、Chart.yaml 内でも他のすべてのフィールド、すべてのコメント、キーの順序、クォートは記述したとおりです。マニフェスト内の別の場所にネストされ、たまたま同じく name という名前のキー(たとえばメンテナーの名前)はそのまま残されます。

アンブレラがそのフィールドを必要とする理由。 チャートの name は、Helm がアンブレラの依存関係をバインドする対象です。これはチャートの作成者が書くものであり、上流から取得したチャートではデプロイする人とは別人です。そのため、1 つのアセンブリパス内の 2 つのコンポーネントが、マニフェストで同じ名前を宣言するチャートをベンダリングすることは十分にありえます。両方のサブチャートがその共有名を保持していると、アンブレラの 2 つの依存関係はどちらも Helm が先に読み込んだ方に解決されます。一方のコンポーネントのチャートが 2 回レンダリングされ、もう一方はまったくレンダリングされず、それでも各コンポーネントの値は届くため、出力は完全に見えて誤ったものになります。配置名をコンポーネントインスタンスから導出することで共有名そのものがなくなるため、何も拒否する必要がありません。これには、他に解決策のない 2 つのケース、すなわち名前が構造上共有される同じチャートを 2 つのコンポーネントでベンダリングする場合と、名前を変更できない自分が書いていないチャートをベンダリングする場合も含まれます。

観察できる唯一の点。 自身のチャート名を読むテンプレート({{ .Chart.Name }}、および一般的な {{ .Chart.Name }}-{{ .Release.Name }} というリソース命名のイディオムなど、そこから派生するもの)は、ソースチャートの Chart.yaml に書かれた名前ではなく、エンコード済みのインスタンスアイデンティティを読みます。Helm は親がバインドするエイリアスでサブチャートを報告するため、これはフィールドが設定される前からそのようなテンプレートが読んでいた値です。フィールドを設定することで、ディスク上のファイルがレンダリング結果と一致するようになります。したがって、以下の例では、api-east サブチャート内のテンプレートは api-east を読みます。

リソース名にチャートの元の名前を含める必要がある場合は、その名前をチャートの values.yaml に入れてそこから読んでください。値は利用者のものであり、Aggrega は手を加えません。

名前の導出方法

Helm のチャート名と Helm の依存関係エイリアスは、それぞれ aggregate 名、boundary パス、instance_id が持ちうる文字よりも狭い文字集合しか受け付けません。導出では、対象が受け付けない文字を置き換えるのではなく書き出すため、句読点だけが異なる 2 つのアイデンティティは常に 2 つの名前になり、あるエイリアスの下に書かれた値は、そのエイリアスが指すサブチャートにしか届きません。

  • 英字、数字、アンダースコアは記述どおりにそのまま引き継がれます。
  • ハイフンは、その次の文字がそのまま引き継がれる文字であり、かつ小文字の z でない場合に、記述どおり保持されます。小文字の z が続くハイフンはエスケープの開始となるため、その位置に記述されたハイフン自体が書き出されます。api-zone は api-zhzone になり、これによってどの名前も推測なしに読み戻せます。
  • その他のすべての文字は、-z の後にその文字を示す英字を続けて書き出されます。ドットは d、パス区切りは s、上記の規則で保持されないハイフンは h です。それ以外は x と文字の 6 桁の 16 進コードポイントで書き出され、どの文字の先頭にもならないバイトは b とその 2 桁の値で書き出されます。そのため、有効なテキストでない名前も、潰されることなく区別して書き出されます。
  • 空の値は -ze と書き出され、空でない値がこれを生成することはありません。
  • 2 つのアイデンティティが 1 つのチャート名を構成する場合(aggregate 名がアセンブリパスを修飾する場合)、それらは -- で結合されます。単一のエンコード済みアイデンティティにこのペアが含まれることはないため、結合された名前はどちらがどのアイデンティティかを曖昧さなく示します。

したがって、instance_id が data.main-db であればエイリアスは data-zdmain-db になり、aggregate fullstack-app とアセンブリパス boundaries/data/helm-chart からはチャート名 fullstack-app--boundaries-zsdata-zshelm-chart が得られます。同一の入力は常に同一の名前を生成します。

アンブレラの values.yaml はエイリアスをキーとします。

api-server: # sub-chart alias = encoded instance_id
image: "registry/api-server:v2"
replicaCount: 3
billing-svc:
image: "registry/billing:v1"
replicaCount: 2

サブチャートの valuesMapping: がテンプレートコンテキストに対して評価されると、結果の値マップがこのエイリアスをキーとするサブブロックに自動的に格納されます。これはコンポーネントだけでなく、アンブレラへのすべてのコントリビューターに当てはまります。チャートをベンダリングする Feature アタッチメントはそれ自体が独立したコントリビューターであるため、その FeatureRecipe の valuesMapping: は、配置されたチャートが宣言する名前をキーとする独自のブロックに格納されます。「Where an attachment’s chart lands」を参照してください。

valuesMapping: が null に設定したキーは、そのブロックに null として書き込まれます。Helm 4 でインストールした場合、アンブレラ自身の values.yaml 内の null がそのキーについてサブチャートのデフォルトを削除するのは、インストール時にそのサブチャート用の値も指定された場合に限られます。そのサブチャート用の値を指定しないインストールでは null が破棄され、サブチャートのデフォルトが残ります。helm install に渡す値の中の null は、どちらの場合でもデフォルトを削除します。

Provider 固有の注意点

  • サブチャートの Chart.yaml は必須です。 コピー処理は、ソースパスのルートに Chart.yaml が存在することを強制します。存在しない場合、アンブレラのステップが実行される前にビルドが停止します。
  • 配置されたチャートの name はアンブレラが所有します。 この値は、そのチャートを提供したもののエンコード済みアイデンティティに設定されます。すなわち、component インスタンス自身のアイデンティティ、または Feature アタッチメントがもたらすチャートの場合はそのアタッチメント自身のアイデンティティです。これは、ベンダリングしたチャートの中で Aggrega が変更する唯一のものです。「アンブレラが所有するチャート名」を参照してください。
  • ソースチャートはバージョンと名前を宣言する必要があります。 依存エントリのバージョンはソースチャート自身の Chart.yaml が宣言するものであるため、バージョンを宣言していないチャートには値が補われることはなく、ビルドが停止します。サブチャートが持たないバージョンに固定された依存では、アンブレラのインスタンスごとの値がそのサブチャートに届かなくなるためです。Chart.yaml が名前を宣言していない、複数の YAML ドキュメントを含む、またはパースできないチャートも同じ理由で停止します。アンブレラは読み取れないサブチャートを構成できません。
  • エンコードされたエイリアスとチャート名。 Helm のチャート名または依存エイリアスが受け付けない文字を含む instance_id、aggregate 名、またはバウンダリパスは、上記の「名前の導出方法」に従い、レンダリングされたアンブレラ内でエンコードされた形で現れます。英字、数字、アンダースコア、および導出で保持されるハイフンのみで構成されたアイデンティティは、記述したとおりに現れます。
  • file:// リポジトリポインタ。 アンブレラの依存エントリは、子チャート自身のディレクトリを指す file:// リポジトリポインタを使用します。component の場合は file://charts/<instance_id>、Feature がもたらすチャートの場合はアタッチメント自身のディレクトリです。これはツリー内の子チャートに対するローカルファイルシステムの慣例であり、helm dependency build が外部レジストリを呼び出さずにアンブレラを解決できるようにします。ポインタが指すのは場所であり、チャートが宣言する名前ではありません。アタッチメントではこの 2 つが異なり、存在しないディレクトリを指すポインタを拒否するのは helm dependency build のステップです。
  • helm-chart レベルではテンプレートのレンダリングを行いません。 この provider は Helm SDK のレンダリングパイプラインを呼び出さず、コピーと構成のみを行います。事前にレンダリングされたフラットなマニフェストが必要な場合は、代わりに helm provider の sourced モードを使用してください。

実例

2 ノードのバウンダリで、各ノードが同じソースチャートを指す helm-chart Recipe にバインドされている場合:

# Recipe — used by both `api-east` and `api-west` instances
apiVersion: aggrega.ai/v1beta1
kind: Recipe
metadata:
name: api-server-helmchart
version: 1.0.0
spec:
capability: helm-chart
implements: core/api-server
source: ./charts/api-server
valuesMapping: |
image: "{{ .values.image }}"
replicaCount: {{ optional .infra `replicas` 2 }}

合成後、バウンダリの評価済みアセンブリパス(subDirectory: のデフォルトが {{ .capability }} であるため、デフォルトは dist/<boundary-directory>/<capability>/)には次の内容が含まれます:

dist/<boundary-directory>/helm-chart/
├── Chart.yaml # umbrella; lists api-east and api-west as dependencies
├── values.yaml # alias-keyed: api-east + api-west values blocks
└── charts/
├── api-east/ # ./charts/api-server, name: api-east
│ ├── Chart.yaml
│ ├── values.yaml
│ └── templates/
│ └── deployment.yaml
└── api-west/ # ./charts/api-server, name: api-west
├── Chart.yaml
├── values.yaml
└── templates/
└── deployment.yaml

両方のサブチャートは 1 つのソースチャートのコピーであり、それぞれが自身のインスタンスの名前を Chart.yaml に持ちます。これにより、1 つのチャートを単一のアンブレラ内に 2 回ベンダリングできます。両方のコピーのそれ以外の部分はすべてソースと同一です。

このレイアウトに対して helm install <release-name> dist/<boundary-directory>/helm-chart を実行すると、両方のインスタンスが単一の Helm リリースとしてインストールされ、アンブレラのエイリアスをキーとする値が各サブチャートのテンプレートを駆動します。

相互参照