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

Helm Provider

helm プロバイダーは、GitOps のコンシューマー(ArgoCD、Flux)向けにフラットにレンダリングされた Kubernetes YAML を生成します。このプロバイダーは (path, provider) ごとにアセンブルを行います。helm を対象とするすべてのノードのレンダリング済み YAML は、境界の評価済み directory: とコンポーネントごとの subDirectory: を結合したものをキーとするアセンブラーにルーティングされ、そのアセンブラーが Kubernetes リソースごとに 1 つの YAML ファイルを出力します。下流のツールは、Helm のインストール手順を経ずに、これらのファイルを直接 diff して適用します。

境界の syncWave: <integer> が 0 でない場合、出力される各 Kubernetes リソースにはその値が argocd.argoproj.io/sync-wave: "<N>" アノテーションとして付与されます。Helm フックにはさらに helm.sh/hook-weight: "<N>" が付与されます。ArgoCD は sync-wave アノテーションを、Helm はフックの重みを読み取り、それぞれそれに従ってリソースを順序付けます。デフォルトのウェーブ 0 の境界はどちらも持たず、両ツールはこれをウェーブ 0 として読み取ります。

このページは helm プロバイダーのオーサリングリファレンスです。プロバイダー横断の入力合成モデルについては、architecture/16-recipe-input-composition.md を参照してください。各プロバイダーの準備状況については、言語のステータス → Providers を参照してください。

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

helm プロバイダーは、Recipe の 3 種類の入力をすべて、それぞれ異なる役割で受け付けます。

  • ソースモード。 source: <chart-path> を持つ Recipe は、ディスク上の Helm チャートディレクトリを指します。Helm Go SDK がチャートを読み込み、ベースレンダリングの値辞書がチャートのデフォルトと統合され、チャートのテンプレートがフラットな Kubernetes YAML にレンダリングされます。
  • Workload(合成)モード。 workload:(インライン、または $import: で読み込み)を持つ Recipe は、Workload ドキュメントを宣言します。プロバイダーは、ノードごとに 1 つ以上の Kubernetes リソース(Workload の form によって選ばれるコントローラーオブジェクトに加え、サービスごとの Service と永続ボリュームごとの PVC)を、Workload の仕様から直接合成します。Workload(合成)モードを参照してください。
  • アーティファクトのみモード。 artifacts: を持ち、source: も workload: も持たない Recipe は、作成者が書いたマニフェストを出力します。その際、ビルドの来歴ラベルとアノテーションが各リソース自身のメタデータに挿入されます。

この 3 つは組み合わせられます。Recipe はチャート、Workload、artifacts: を同時に宣言でき、それぞれが個別にレンダリング・出力され、ノードの出力内に並んで配置されます。What each provider accepts, in full(各プロバイダーが受け付けるものの全容)を参照してください。

source: のキーセット

helm プロバイダーの source: はチャートを指定し、source: フィールドが取る 2 つの形の両方を受け付けます。裸のファイルシステムパス文字列と、url: が場所を保持する構造化オブジェクトです。その場所がファイルシステムパスである場合、それはビルドを起動したディレクトリではなく、それを宣言する recipe.yaml を含むディレクトリを基点とし、そのディレクトリの内側に留まらなければなりません。そこから外へ出るパスや絶対パスは拒否されます。Recipe の公開物が持つファイルはすべてそのディレクトリから取られるためです。entities/recipe.md の「Content paths stay inside the Recipe’s own directory」を参照してください。このように指定されたチャートは Recipe とともに公開され、Recipe のピン留め時に記録された無視ルールが残すその配下のすべてのファイルが含まれます。helm プロバイダーはバージョン管理ディレクトリとチャートの templates/ 配下の隠しファイルを除外し、チャート自身の .helmignore に従い、作成者の .aggregaignore が最終的に決定します。これは Which files ship with an entity に記載されているとおりです。一方、Recipe の横にあっても Recipe が宣言するものがどれも指定していないファイルは含まれません。レンダリングは公開物が持つのと同じファイルを読むため、チャートは手元のディレクトリからでもレジストリからでも同じようにレンダリングされます。記述した形はこれを変えません。url: が ./charts/api-server である構造化 source: は、裸の文字列 ./charts/api-server とまったく同じように基点が決まります。

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

構造化 source: は同じことを名前付きフィールドで表し、その url: が何を保持するかによって、何かが取得されるかどうかが決まります。url: がトランスポートスキームを持つ場合、つまり OCI チャートの oci://…、直接のチャートアーカイブの https://….tgz、または chart: と組み合わせた https:// リポジトリルートの場合、チャートは取得されます。種類は URL スキームまたは明示的な kind: から決まり、aggrega pull がチャートを取得してロックファイルにピン留めし、ビルドはキャッシュからそれを展開します。url: がファイルシステムパスを指定する場合は、何も取得されず何もピン留めされません。チャートはディスクから読まれ、上記の裸の文字列形式とまったく同じように基点が決まります。

spec:
capability: helm
source:
kind: helm-oci-chart
url: ./charts/api-server # a path, so nothing is fetched and nothing is pinned
version: "1.0.0"

チャートをどこから読むかを決めるのは url: だけです。その他のフィールドは取得される対象を選択するため、パスの場合は何も選択しません。それでも、それらは .source.* として Recipe 自身のテンプレートに渡されます。

チャートをローカルにベンダリングすることは、取得の代替としてサポートされていますが、必須ではありません。スキーマは開いた構造化オブジェクトを受け付けます。

source パスにあるチャートには、有効な Chart.yaml が含まれている必要があります。チャートの読み込みに失敗した sourced レンダリングでは、基盤となる Helm SDK のエラーがそのまま表示されます。空の source: "" は helm に固有の問題ではありません。これは sourceless モードも sourced モードも指定しないため、それが受ける拒否は Recipe がどのプロバイダを対象としていても同じであり、Recipe が読み込まれる時点、つまりチャートが読み込まれる前、かつこのプロバイダがディスパッチされる前に発生します。どのコマンドがそれを報告するかは、entities/recipe.md の「Source field scheme inventory」と errors/fatal-halts.md の「Recipe source: is an empty string(Recipe の source フィールドが空文字列です)」で説明しています。

ソースモード

source: <chart-path> と valuesMapping: を持つ Recipe は、ベースレンダリング時に次のパイプラインを実行します。

  1. <chart-path> にあるチャートが Helm Go SDK によって読み込まれます。
  2. valuesMapping テンプレートが Recipe のテンプレートコンテキストに対して評価されます。その YAML 出力は、チャートに対する値のオーバーレイとして扱われます。
  3. オーバーレイはチャートの values.yaml のデフォルト値と一度だけ結合され、キーが衝突した場合はオーバーレイのキーが優先されます(Helm の標準的な helm install --values のセマンティクス)。オーバーレイが null に設定したキーは、トップレベル、テーブルの内部、依存関係の値のいずれであっても、helm install --values と同様にそのキーに対するチャートのデフォルト値を削除するため、チャートのテンプレートはそのキーを存在しないものとして読み取ります。チャートがデフォルト値を与えていないキーに対する null は、null のままテンプレートに渡されます。
  4. Helm SDK が、マージされた値に対してチャートのテンプレートをレンダリングします。
  5. Aggrega は、レンダリング後の YAML 書き換えによって、レンダリングされたマニフェストに来歴メタデータを注入し、sourced モードの出力が workload モードの出力と同じラベル付けを持つようにします。識別値はラベルになり(app.kubernetes.io/name、aggrega.ai/component-id、aggrega.ai/provider、aggrega.ai/provider-version、aggrega.ai/environment、および設定されている場合は aggrega.ai/aggregate-name、aggrega.ai/compiler-version)、それぞれ Kubernetes がラベル値として受け入れる形式で書かれます。Kubernetes のラベルで表現できない値はアノテーションになります(aggrega.ai/recipe-uri、aggrega.ai/boundary-path、ウェーブが 0 でない場合の aggrega.ai/sync-wave、および値を書き換える必要があったラベルの元の値。imported/flow という名前の Aggregate には、同じキーでラベル imported-flow とアノテーション imported/flow が付きます)。書き換えの規則は well-known-annotations.md の「プロバイダーが出力する来歴ラベル」に記載されています。
  6. 出力ファイルは Recipe の出力ディレクトリにフラットに配置され、レンダリングされたリソースごとに 1 つずつ、<name-basis>-<kind>[-<namespace>]-<name>.yaml という名前が付けられます。これは、後述のリリース名の導出元と同じ基盤に、リソース自身の kind、namespace(ある場合)、name を続けたもので、それぞれ小文字化され、それ以外の文字の連続はすべて 1 つのハイフンに置き換えられます。通常の component では、その基盤は component 自身の識別子であり、リソースの aggrega.ai/component-id ラベルが持つ値でもあります。Feature のアタッチメントの作成者が提供したチャートでは、基盤はホストの component のものになり、ラベルにはアタッチメント自身の識別子が入ります。kind または name を持たないドキュメントは、代わりにテンプレートのパスに基づいて命名されます。チャートのディレクトリ構成はフラット化されます。レンダリングされた出力には templates/ サブディレクトリはなく、異なるサブディレクトリにある同じファイル名の 2 つのテンプレートは、名前がテンプレートではなくリソースに由来するため、2 つのファイルのまま残ります。Recipe の artifacts: ブロックが名前を挙げるファイルはここには配置されません。そのファイルは 1 階層下の、それを宣言した component の名前を持つディレクトリに置かれます。そのようなファイルは、含むリソースではなく作成者が書いたキーによって命名されるため、そのディレクトリがなければ、1 つの Recipe にバインドされた 2 つの component が同じパスに書き込み、どちらの作成者もそれらを分離できなくなるからです。

チャートがレンダリングの対象とする namespace は、boundary からカスケードされる aggrega.ai/namespace アノテーションから読み取られ、リリース namespace としてチャートに渡されます。どの boundary も宣言していない場合、チャートは default を対象にレンダリングされます。boundary が namespace を宣言している場合、チャートが namespace なしで(metadata.namespace がない、または空や null で書かれている)レンダリングするすべての namespaced リソースは、宣言された namespace で出力されます。これは、そのリリース namespace でチャートを Helm でインストールした場合に配置される場所であり、そのファイルは、テンプレートがこのフィールドを書いているリソースとまったく同じように namespace セグメント付きで命名されます。テンプレートが namespace を書いているリソースは、それがどの namespace であってもそれを保持します。cluster-scoped リソースは namespace なしのままです。kind が namespaced かどうかは、API 自身が提供する kind については Kubernetes API 自体のスコープにより、カスタム kind については同じレンダリング内の CustomResourceDefinition がその kind に対して宣言する scope により決まります。これはチャートのテンプレートからでも、その crds/ ディレクトリからでも構いません。これらのどちらでも分類されない kind のリソースはチャートが書いたまま残され、ビルドは kind ごとに 1 回、その kind と API グループを挙げて報告します。kind: List ドキュメントも同様で、その items は配置されません。どの boundary も namespace を宣言していない場合は、何も配置されず、何も報告されません。チャートが namespace なしで書いたリソースは namespace なしで出力され、適用するツールが選択する場所に配置されます。

この報告はビルドに対する警告であり、ビルドは完了します。

warning: node "store" (provider "helm"): resources of kind "Probe" in API group "monitoring.example.org" write no namespace and are left without one rather than placed in namespace "shop": the kind is not one the Kubernetes API serves itself, and no CustomResourceDefinition in this chart's render gives it a single scope, so whether it is namespaced is not known when the build runs, and they land wherever the tool applying the output places them

チャートに、その kind の CustomResourceDefinition をレンダリングする値、または namespace 自体を書き込む値がある場合、それを Recipe の valuesMapping で設定すると、そのようなリソースが配置されます。

チャートのレンダリング対象となる Kubernetes バージョン

チャートのテンプレートは、レンダリング対象の Kubernetes バージョンを .Capabilities.KubeVersion として読み取り、多くのチャートはそれに応じて API バージョン、フィールド、あるいは仕組み全体を選択します。たとえば、1.21 以降では投影されたサービスアカウントトークンを使い、それより前ではファーストパーティのトークンを使う、といった具合です。ビルドには問い合わせるクラスタがないため、バージョンは Release が component のデプロイ先を示す箇所で明示します。つまり、boundary に付ける aggrega.ai/kubernetes-version アノテーション、または component に付ける同アノテーションです。component に付けたものはその boundary のものより優先され、aggrega.ai/namespace とまったく同じようにカスケードします。

spec:
boundaries:
production:
annotations:
aggrega.ai/kubernetes-version: "1.31"
components:
api: {}
legacy:
annotations:
aggrega.ai/kubernetes-version: "1.28" # this component deploys to an older cluster

この値は helm template --kube-version がそのフラグを読むのと同じ方法で読み取られるため、そのフラグが受け付ける形式を受け付け、チャートはそのフラグが与えるのとまったく同じものを読み取ります。"1.31" は v1.31 として、"v1.31.2" は v1.31.2 として読まれ、数字の後ろのテキストは .Capabilities.KubeVersion.Version に記述どおり残ります("1.29.3-gke.100" は v1.29.3-gke.100 として読まれます)。一方、.Capabilities.KubeVersion を丸ごと出力すると、そのテキストを除いたバージョンになります。.Capabilities.KubeVersion.Version を semverCompare で比較するチャートは、このようなサフィックスをプレリリースとして読むため、">=1.21" のように -0 の下限を持たない制約はそれにマッチしません。また、前後に空白を含む値はその空白ごと読まれ(" 1.30 " は "v 1.30 " として読まれます)、そのような比較には必ず失敗します。チャートがバージョンを比較する場合は、余計なものを含まないバージョンを記述してください。バージョンではない値("one.two"、"latest"、単一の数値)は、プラグインが表現を持たない値に関する条件のもとでビルドを停止させ、その値、component、およびその boundary を示します。チャートが代わりに別のバージョン向けにレンダリングされることはありません。A Kubernetes version the helm provider cannot render a chart for(helm provider がチャートをレンダリングできない Kubernetes バージョン) を参照してください。空の値は未設定として扱われます。

バージョンを指定するアノテーションがない場合、チャートは同じ helm リリースの標準の helm template がレンダリング対象とするバージョン向けにレンダリングされます。これは provider のビルドに使われた Kubernetes クライアントライブラリのバージョンです。クライアントライブラリ v0.37 でビルドされた provider は Kubernetes v1.37.0 向けにレンダリングします。したがって、チャートは Aggrega において、そのチャート作成者自身の helm template がレンダリングするとおりにレンダリングされ、デフォルトが変わるのは provider のビルドに使われるクライアントライブラリが変わったときだけです。デプロイ先クラスタのバージョンが異なる場合は、必ずそのバージョンを指定してください。クラスタが実行しているものより新しいバージョン向けにレンダリングされたチャートは、そのクラスタが提供しない API バージョンを出力することがあります。

この方法で設定されるのはバージョンだけです。チャートが読み取るその他のケイパビリティ(.Capabilities.APIVersions と .Capabilities.HelmVersion)は helm ライブラリの組み込みのものであるため、クラスタがインストール済みの CustomResourceDefinition から提供する API はチャートに報告されません。チャート自身の Chart.yaml にある kubeVersion の範囲はバージョンと比較されません。helm template は範囲がレンダリング対象のバージョンを除外するチャートを拒否しますが、ビルドはそれをレンダリングします。このアノテーションが影響するのはソースからレンダリングされるチャートだけです。合成された Workload と artifacts: の本体は .Capabilities を読まず、helm-chart provider はチャートをレンダリングせずに引き渡し、インストール時にレンダリングされます。

レンダリングされたドキュメントの除外。 この provider は、Recipe または FeatureRecipe が宣言する omits: エントリを、このモードでのみ尊重します。合成された Workload と artifacts: の本体はそれらを適用せずにレンダリングされます。チャートがレンダリングするすべてのドキュメント(テンプレートからのもの、または crds/ ディレクトリのファイルからのもの)は、ビルドに適用される各エントリと照合され、いずれかのエントリが指すドキュメントは除外されます。エントリはドキュメント自身が持つ語、つまり出力ファイル名とレンダーファクトの構築元と同じ語でドキュメントを指します。すなわち、kind、metadata.name、そしてエントリが指定する場合に限り、ドキュメントが属する namespace です。これはテンプレートが記述する namespace、または上述のとおりこの provider がドキュメントを配置する場合は boundary が宣言した namespace です。チャートが単にレンダリング時に使う namespace は対象になりません。namespace が宣言されていない場合、チャートは default に対してレンダリングされますが、テンプレートが namespace を記述しないドキュメントはどの namespace にも属さないため、default を指定したエントリはそれにマッチしません。kind または name を持たないドキュメントはどのエントリにもマッチしません。除外されるドキュメントはレンダリングされた後、すべてのファイル名が確定した時点で破棄されるため、残る各ドキュメントはエントリがない場合とまったく同じように命名され書き出されます。また、除外されたドキュメントはビルドのその後の処理に一切届きません。ファイルも、2 つの寄与元が同じものに着地することを拒否する比較における名前も、Feature が読むレンダーファクトも、パイプラインステップに渡されるものもありません。provider は各エントリがマッチしたドキュメント数を報告し、何にもマッチしなかったエントリはビルドを停止させます。An omits entry left out nothing the source rendered(omits エントリがソースのレンダリング結果から何も除外しなかった) を参照してください。

チャートがレンダリングされる Helm リリース

この Provider は Helm 4 SDK の v4.3 でレンダリングするため、チャートは Helm 4 自身の helm template が与えるものを読み取り、同じチャートと値はどのビルドでも同じバイト列にレンダリングされます。Helm 3 を対象に作成・検証されたチャートでは、次の Helm 4 の挙動が観測される場合があります。

  • .Capabilities.HelmVersion は Helm 4 のバージョン v4.3 を報告します。
  • デフォルトの Kubernetes バージョンは v1.37.0 です。v4.3 の Helm 4 はクライアントライブラリ v0.37 に対してビルドされており、.Capabilities.APIVersions はそのクライアントライブラリの API バージョンの集合です。チャートがレンダリングされる Kubernetes バージョンの説明に従い、クラスタが実行しているバージョンを指定してください。
  • チャートの null のデフォルト値は削除されます。 チャートの values.yaml が null に設定しているキーは、トップレベルでもテーブル内でも、Recipe が与える値がそれを設定しない限り .Values に存在しません。そのため hasKey はそれを欠落として報告し、toYaml はそれを出力せず、チャートの values.schema.json はそのキーを含まない値に対して検証されます。
  • ブロックスカラーは --- の前の最後の改行を保持します。 ブロックスカラーで終わり、同じテンプレートの別のドキュメントが後に続くドキュメントは、そのスカラーの最後の改行を保持するため、|- ではなく | と書き出されます。
  • .Chart はフィールド名をキーとするマップです。 .Chart.Name、.Chart.Version、.Chart.AppVersion などのフィールドは従来どおり読み取れますが、toYaml .Chart や toJson .Chart.Maintainers はキーを Name、AppVersion などとして、空のフィールドも含めて出力します。また、チャートのメタデータが持たないフィールドはレンダリングを失敗させず、空として読み取られます。
  • .Capabilities.KubeVersion.Version はバージョンのテキストを記述どおりに保持します。これは前述の aggrega.ai/kubernetes-version アノテーションの説明のとおりです。
  • 複数の YAML ドキュメントを含む values.yaml は全体が読み込まれ、後のドキュメントが前のドキュメントの上にマージされます。
  • 空のファイルに対する .Files.Lines は、レンダリングを失敗させず、行を返しません。
  • Helm 4 で追加されたテンプレート関数(mustToYaml、mustToJson、mustToToml、mustToDuration、および duration… 変換)をチャートのテンプレートで使用できます。
  • 2 回エイリアスされた依存関係では、各エイリアスがその依存関係自身の依存関係のコピーをそれぞれ持ちます。
  • values スキーマの検証は、境界的なケースでのみ受理・拒否の結果が異なります。引用符付きのメールアドレスのローカル部、NaN と無限大の数値、enum と const における数値と非数値の比較、そして失敗した propertyNames、contentSchema、または後続の配列要素について報告される位置です。

エンジン自体が実行に失敗したテンプレート(たとえば存在しないテーブルを経由して値を読み取った場合)は、Helm 4 の形式で報告されます。テンプレートのファイル、行、列がそれぞれ独立した行に示され、続いて失敗が経由した各テンプレートについて、実行中だった内容とメッセージがインデントされて示されます。チャート自身の fail や required は 1 行の execution error at (<file>:<line>:<col>): <message> 形式を維持し、テンプレート関数が返すエラーも同様です。

リリース名の導出方法

ソース指定のチャートはリリース名に対してレンダリングされ、リリース名はすべてのテンプレートに .Release.Name として渡されます。チャートはリソースをこれにちなんで命名するのが一般的であるため、リリース名はビルド上のラベルではなく、クラスタ内での識別子です。

リリース名は、レンダリングされたリソースの出力ファイル名の接頭辞と同じ基底をエンコードした形であり、両者は 1 つの名前を 2 回書いたものです。その基底は、通常の component では instance_id であり、boundary にアタッチされた Feature では、その Feature が持つ合成された識別子です。Feature アタッチメントの作成者が提供したチャートの場合、基底は ホスト component の名前です。チャート自身のテンプレートはリリース名に対してレンダリングされるため、代わりにアタッチメントから導出すると、チャートが宣言するリソースが、すでにそれらがデプロイされているクラスタ内で名前変更されてしまいます。それらのリソースは、aggrega.ai/component-id ラベルには引き続きアタッチメント自身の識別子を持ちます。ここでは、リソースが何と呼ばれるかと何に属するかは別の問題であり、両者の答えが一致するのは通常の component の場合だけです。Helm のリリース名が受け付ける文字の範囲は、識別子が持ちうる文字よりも狭く、小文字、数字、ハイフン、ドットのみで、小文字または数字で始まり小文字または数字で終わり、最大 53 文字です。導出では、対象が受け付けない文字を別の文字で置き換えるのではなく書き出すため、句読記号や大文字小文字だけが異なる 2 つの component 識別子は、必ず 2 つの異なるリリース名になります。

  • 小文字と数字は、記述どおりにそのまま引き継がれます。
  • ハイフンは、その次の文字がそのまま引き継がれる文字で、かつ小文字の z でない場合に限り、記述どおりに保持されます。ハイフンの後に小文字の z が続くとエスケープの開始になるため、その位置に記述されたハイフン自体が書き出されます。api-zone は api-zhzone になり、これによってどの名前も推測なしに読み戻せます。後ろに何も続かないハイフンも同じ理由で書き出されるため、db- は db-zh になります。
  • それ以外の文字はすべて、-z の後にその文字を表す文字を続けて書き出されます。ドットは d、アンダースコアは u、パス区切り文字は s、上記の規則で保持されないハイフンは h です。それ以外のもの(大文字を含む)は、x とその文字の 6 桁の 16 進コードポイントとして書き出され、どの文字の先頭にもならないバイトは b とそのバイト自身の 2 桁の値として書き出されます。
  • 空の値は -ze と書き出され、空でない値がこれを生成することはありません。

Helm はリリース名にドットを受け付けますが、ドットはそのまま引き継がれず書き出されます。Helm はドットの両側に小文字または数字があることを要求し、導出では独自にハイフンを配置するためです。

1 つの component にアタッチされた 2 つの Features はどちらもその component のリリース名に対してレンダリングされるため、それぞれ .Release.Name にちなんでリソースを命名する 2 つのチャートは、同じ名前のリソースを 2 つ出力します。この Provider は、自身のレンダリングが生成するすべてのリソースが持つ名前を、そのリソースの kind、およびクラスタが namespace 内に保持する kind の場合はその namespace をスコープとして報告します。ビルドは、両方を適用すると最後のものだけが残る出力を生成するのではなく、そのいずれかの名前に 2 つの寄与元が重なることを拒否します。../errors/fatal-halts.md の「The same name is derived more than once inside the output(出力内で同じ名前が複数回導出されています)」を参照してください。クラスタがどの namespace にも属さずに保持する kind(ClusterRole、CustomResourceDefinition、または同じレンダリング内の CustomResourceDefinition がスコープ Cluster で宣言するカスタム kind)は、kind のみをスコープとし、上記の namespace 配置での分類とまったく同じ方法で分類されます。そのため、1 つの出力の 2 つの component がそれぞれそのようなオブジェクトを同じ名前で書き出す場合、Release がそれらを異なる namespace に配置していても拒否されます。対処法は名前を合成することであり、どの座標が必要かは構成によって異なります。1 つの component 上の 2 つのアタッチメントはすでにホストを共有しているため、テンプレートに届ける必要があるのはアタッチメントです。FeatureRecipe の valuesMapping: を通じて .attachment_name をチャートに渡し、チャート自身の値のうちリソース名の構築に使われるものに設定してください。1 つのチャートが 2 つの component にアタッチされる場合はその逆です。リリース名はすでにホストごとに異なるため、.Release.Name にちなんで命名されたリソースはそれぞれのホスト上で固有の名前を持ちますが、リテラルの名前はそうなりません。artifacts: を通じてリソースを提供する FeatureRecipe も同じ条件で報告されます。この Provider は、出力された各ドキュメントが持つ名前を、そのドキュメントがチャートテンプレートから来たか artifacts 本体から来たかに関係なく読み取るため、2 つの component にアタッチされた artifacts 本体内のリテラル名も停止を引き起こします。artifacts 本体はテンプレートであるため、名前は .context.rendered_name(ホストのリリース名で、ホストごとに異なり、Kubernetes の名前が許す文字で綴られます)と、ホストごとに区別が必要な場合は .attachment_name から合成してください。アーティファクトセットのみを配置し、リリース名を報告しないホストでは、代わりに .context.instance_id から合成してください。すべての名前が報告されるわけではないため、停止しないビルドであっても、出力が最終的に持つすべての名前を比較し終えたわけではありません。チャートを書く際に最も遭遇しやすいのは generateName を宣言するリソースで、これは補完がクラスタに委ねられるため、比較できるものがまだありません。完全な一覧は上記のリンク先のページにあります。

したがって、instance_id が api であればリリース名は api になり、data.main-db は data-zdmain-db に、db_host は db-zuhost になります。小文字、数字、および導出で保持されるハイフンのみで構成された識別子は、記述どおりにそのまま現れます。同一の入力は常に同一の名前を生成します。

Helm の条件のうち 2 つは、導出ではなく基底の性質です。リリース名は小文字または数字で始まる必要があり、また 53 文字以下である必要があります。最初の文字が書き出される基底は、すべてのエスケープが始まるハイフンで名前が始まり、書き出される文字を含む基底は、記述されたときよりも長くエンコードされます。ビルドはこの両方についてこの Provider に問い合わせ、その回答に基づいてビルド時に対処します。拒否を適用時のクラスタに任せることはしません。../errors/fatal-halts.md の「The target will not accept a name derived from an authored identity(記述された識別子から導出された名前を対象が受け付けません)」を参照してください。回答に対して何をするかは、基底を誰が書いたかによって異なります。利用者が書いた名前は変更されずに拒否され、その拒否には書いたフィールドと使える文字数が示されます。Aggrega が合成した名前は、この Provider が受け付けるまで短縮されます。

クラスタは、component にちなんで命名されたリソースに対して、Helm よりも厳しい規則を 1 つ課します。Service の名前は英字で始まる必要がありますが、リリース名は数字で始まってもかまいません。チャートは一般に Service をリリース名にちなんで命名し、合成された workload の Service もリリース名で始まるため、この Provider は数字で始まる component 名も拒否し、対象が使用できない Service name として報告します。最初の文字は長さでは修正できないため、この拒否では文字数は示されません。したがって、instance_id は小文字で始め、エンコード後の形も収まる程度に短くしてください。

**リリース名の導出元となる基底を変更すると、チャートが .Release.Name にちなんで命名するクラスタリソースと、この Provider がその component のために合成するすべてのリソースの名前が変わります。Kubernetes はリソースをその場で名前変更しません。**適用ツールは新しい名前でリソースを作成し、古い名前のリソースを削除します。ステートフルなリソースでは、これは古い名前に紐付いたストレージが解放されることを意味します。このような変更は、ロールアウトする更新としてではなく、計画が必要な置き換え(ドレイン、移行、またはスケジュール)として扱ってください。

Workload (合成) モード

workload: (インラインまたは $import: で読み込み) を持つ Recipe は、Workload の抽象的な意図から Kubernetes リソースを合成します。Workload のスキーマは entities/workload.md に記載されています。このセクションでは helm プロバイダーが出力する内容を扱います。

各ノードについて:

  • Workload の form によって選ばれる 1 つの コントローラーオブジェクト: stateless (およびデフォルト) は Deployment、stateful は StatefulSet、daemon は DaemonSet、task は Job、scheduled は spec.schedule が Workload の schedule フィールド (5 フィールドの cron 式または @ マクロ) である CronJob を出力します。スケジュールのない、または不正な形式の scheduled ワークロードは明示的に停止します。suspend: true を宣言する scheduled ワークロードは、CronJob を spec.suspend: true 付きで出力します。そのため、再開されるまでスケジュールから実行が開始されることはありませんが、CronJob から手動で Job を作成することは引き続き可能です。宣言しないワークロードは suspend キーを一切出力しません。Deployment と StatefulSet はレプリカ数を持ち、DaemonSet、Job、CronJob は持ちません。stateful の Workload は、StatefulSet を管理するために Workload 内で宣言された type: Headless の Service をちょうど 1 つ必要とします。プロバイダーは StatefulSet の serviceName をその Service のレンダリング後の名前に結び付け、ヘッドレス Service が宣言されていない場合 (または複数ある場合) はビルドが停止します。persistentTemplate ボリュームは form: stateful に付随するものであり、他の form で宣言すると修正方法を示すメッセージとともに停止します。
  • Workload で宣言された services: エントリごとに 1 つの Service を出力し、サービス仕様が列挙する名前付きポートを公開します。エントリの type が Service のタイプになります。ClusterIP、NodePort、LoadBalancer はそのまま、Headless は clusterIP: None を持つ ClusterIP Service になります。Loopback エントリは代わりにノードとサービスを示してビルドを停止します。Kubernetes の Service にはホストのループバックアドレスにバインドするタイプがなく、NodePort Service がどのノードアドレスで待ち受けるかはクラスター全体の設定であるため、そのエントリは要求していない到達範囲でレンダリングされるのではなく拒否されます。A service type the helm provider cannot render (helm プロバイダーがレンダリングできないサービスタイプ) を参照してください。
  • persistent ボリュームごとに 1 つの PersistentVolumeClaim を出力し、そのサイズと形状はボリュームの仕様から決まります。persistentTemplate ボリュームは単独のクレームを出力せず、StatefulSet 自身の spec 内の volumeClaimTemplates エントリになります。これが form: stateful に付随するものである理由です。

リソース名。 このモードがコンポーネントに対して出力するすべてのリソースは、そのコンポーネントのリリース名にちなんで命名されます。これはソース指定のチャートがレンダリングに使うのと同じ名前で、リリース名の導出方法 に示すとおりに導出されます。プロバイダーはその名前を {{ .context.rendered_name }} としてビルドに報告します。コントローラーオブジェクトはリリース名そのものを持ち、各 Service は <release name>-<service key>、各単独クレームは <release name>-<volume> で、Pod のボリュームはまさにそのクレームを参照します。ファイルとして配信されるシークレットは <release name>-secret-<slot> という名前の Pod ボリュームからマウントされ、スロットはリリース名と同じく、クラスターが受け付けるアルファベットで書き出されます。したがって、スロット server_certificate は <release name>-secret-server-zucertificate からマウントされ、接続を通じて読み取られるスロットでは、接続名の後のドットも同じ方法で書き出されます。StatefulSet の serviceName は出力されるヘッドレス Service の名前です。外部名のみで公開される Workload は、リリース名を持つ Service を 1 つ出力します。したがって、コンポーネント api は Deployment api と default Service api-default を出力し、コンポーネント my_api は my-zuapi と my-zuapi-default を出力します。これらは、記述どおりの識別子では受け付けられない場合でもクラスターが受け付ける名前です。これらの Service のいずれかのアドレスを公開する Recipe は、../templates/rendered-resource-names.md に示すとおり {{ .context.rendered_name }} からアドレスを組み立てます。名前にアンダースコアも大文字も含まないコンポーネントでは、リリース名は instance_id と等しくなるため、その名前は識別子どおりに読めます。唯一の例外は Feature のアタッチメントが合成するワークロードです。これはアタッチメント自身の合成された識別子 (その aggrega.ai/component-id ラベルが持つ値) にちなんで命名されます。アタッチメントはホストコンポーネントに対してレンダリングされるため、そこで導出されたリリース名ではアタッチメントのワークロードがホストにちなんで命名され、ホスト自身のものと衝突するからです。その識別子が大文字を含むことはありません。ホストの名前やアタッチメントの名前に含まれる大文字は、リソース名が拒否する他のすべての文字と同様にエスケープとして書き出されます。そのため、コンポーネント myApi 上のアタッチメント worker は Deployment cfr--my-zx000041pi--worker と default Service cfr--my-zx000041pi--worker-default を出力し、ワークロードが持つ各名前はいずれもクラスターが受け付けるものになります。

Workload に依存する名前の長さ。 これらの名前のうち 2 つには、クラスタがそれぞれ独自の上限を課しており、ビルドは拒否を適用時のクラスタに任せるのではなく、Workload が解決された時点で両方を検査します。CronJob の名前は最大 52 文字です。コントローラが各実行の Job に CronJob の名前にサフィックスを付けた名前を付けるため、クラスタの他の名前より短くなっています。これは scheduled Workload の場合にのみ検査されます。各 Service の名前 <release name>-<service key> は最大 63 文字です。どちらかの上限を超えた場合の扱いは、リリース名の場合とまったく同じく、名前を誰が書いたかによって決まります。自分で書いたコンポーネント名は拒否され、ビルドは自分で書いた spec.components のキーで停止し、名前の種類、その長さ、および名前に使える文字数を示します。../errors/fatal-halts.md の「The target will not accept a name derived from an authored identity(ターゲットは記述された識別子から導出された名前を受け入れません)」を参照してください。Feature のアタッチメントのワークロードの名前の元となる識別子のような合成された識別子は、すべての名前が収まるまで短縮されます。Service の名前は、自分のコンポーネント名と、ワークロードが(Recipe または FeatureRecipe で)宣言するキーから組み立てられるため、拒否ではそのキーと、ワークロードがそれを宣言している場所 spec.workload.services.<key> が示されます。どのコンポーネント名の余地も残さないキーは、キー自体を短くする必要があります。したがって、scheduled Workload を持つコンポーネントはエンコード後の名前を最大 52 文字まで、コンポーネント web は最大 59 文字の Service キーを持つことができます。境界全体にアタッチされた Feature は、その出力がどこでアセンブルされるかがその識別子に依存しうるため、Workload が解決される前に識別子が確定します。そのため、それが合成するリソースについてはどちらの上限も検査されません。

出力される各リソースは、Aggrega の完全な来歴ラベルとアノテーションに加え、Deployment/StatefulSet とその Service の間を結ぶセレクターのペア (app: <instance_id>) を持ちます。ラベル値は記述どおりの識別子を許容するため、セレクターはそれを保持し、上記の名前はリリース名を使います。レンダリングされた Deployment のコンテナ名は、Workload のコンテナキーの . と _ の文字を - に置き換えたものです (Kubernetes の名前サニタイズ)。

ポートのトランスポート。 トランスポートを宣言したコンテナポートは、それをレンダリングされた containerPort の protocol: としてそのまま出力し、そのコンテナポートを指定するすべての Service ポートも同じ値を持ちます。トランスポートはコンテナポートで一度だけ宣言されるため、公開側がそれと食い違うことはありません。トランスポートを宣言しないポートは、どちらのリソースにも protocol キーを出力せず、クラスターのデフォルトが適用されます。Workload が許容する 3 つの値 (TCP、UDP、SCTP) はすべてそのまま出力されます。Kubernetes はそれぞれを直接表現できるため、helm では機能の低下は必要ありません。

ノードのネットワーク上での実行。 hostNetwork: true を宣言した Workload は、レンダリングされる Pod spec に hostNetwork: true を出力します。これにより Pod はノード自身のネットワーク名前空間で実行され、コンテナが開くポートはノードのアドレスで到達可能になります。Kubernetes はこの選択を直接表現できるため、機能の低下はありません。この宣言は Pod spec にのみ反映されます。ポートの追加、削除、書き換えは行わず、出力される Service はこの宣言の有無にかかわらず同一です。宣言しない Workload は hostNetwork キーを一切出力しません。

リソース量。 プロバイダーがマニフェストにコピーするすべての量はそのまま出力され、それぞれはまず Workload → リソース量 に示す量の形式に照らしてチェックされます。対象は、各コンテナおよび init コンテナの resources.requests と resources.limits の値 (cpu、memory、および nvidia.com/gpu などのすべての拡張リソース) と、各ボリュームの ephemeral.sizeLimit、persistent.size、persistentTemplate.size です。チェックは Recipe のテンプレートが評価した後の Workload に対して行われるため、infra や Release パラメーターを通じて届いた値は、レンダリング結果に基づいて判定されます。形式に合わない値は、ノード、Workload 内のフィールドのパス、値を示す TRANSLATION_ERROR でビルドを停止します (例: containers.main.resources.requests.cpu: "lots" is not a quantity: it does not begin with a number)。そうしなければチャートは問題なくビルドされ、インストール時にクラスターに拒否されることになります。空のままの cpu、memory、sizeLimit はマニフェストから省略されるためチェックされません。空のままの拡張リソースの値や永続サイズはそれでも出力されるため、拒否されます。チェックが判定するのは形式のみです。クラスターがその量をスケジュールできるかどうかは、プロバイダーがビルド時に知りうることではありません。

出力ファイルの命名には 2 つの形があります。コントローラーオブジェクトはリリース名と種類にちなんで命名されます: <release name>-deployment.yaml、<release name>-statefulset.yaml、<release name>-daemonset.yaml、<release name>-job.yaml、<release name>-cronjob.yaml。リソースごとのファイルは、それが持つリソースにちなみ、種類を最後にして命名されます: <release name>-<svcName>-service.yaml と <release name>-<volName>-pvc.yaml で、それぞれ entities/workload.md の合成名の慣例に従い、そのリソース自身の metadata.name から取られます。外部名のみで公開される Workload は、持つべきサービスキーがないため <release name>-service.yaml を出力します。

レンダーファクト

この provider は、レンダーするファイルに加えて、すべてのノードについて 4 つのレンダーファクトを報告します。これは、出力した Kubernetes ドキュメントがその Pod、セレクター、ポート、および各ドキュメントの出力先 namespace について何を述べているかを示すものです。コンポーネントにアタッチされた FeatureRecipe は、そのコンポーネント自身のファクトを .context.render_facts で読み取ります。readsCallerRenderFacts: true を設定したものは、.context.used_by の各エントリで、ホストに接続するコンポーネントのファクトも読み取ります。また readsTargetRenderFacts: true を設定したものは、.context.uses の各エントリで、ホストが接続されているコンポーネントのファクトを読み取ります。これにより Feature は、ホストを呼び出すコンポーネント、またはホストが到達するコンポーネントの Pod を、それらのレンダーが実際に出力した内容から指定できます。たとえば、まさにそれらの Pod だけを許可するネットワークポリシーなどです。誰かがラベルを手作業で書き直す必要はありません。以下の名前とエントリが、この provider の契約です。

ファクトエントリの単位各エントリの内容
pod_template_labels出力された Pod テンプレートごと:Deployment、StatefulSet、DaemonSet、ReplicaSet、Job の spec.template、CronJob のジョブテンプレート、およびそれ自体がテンプレートとなる単独の Podテンプレートを持つリソースの kind、name、namespace。labels はテンプレートのラベル
controller_selectors出力された Deployment、StatefulSet、DaemonSet、ReplicaSet、Job、CronJob ごとkind、name、namespace。match_labels はそのセレクターの matchLabels
service_selectors出力された Service ごとname、namespace。selector はトラフィックの送信先となるラベル
container_portsports リストを宣言する Pod テンプレートのコンテナごと(init コンテナを含む)テンプレートを持つリソースの kind、name、namespace。container はコンテナ名。ports はポートごとに 1 エントリで、name、container_port、protocol を持つ

ファクトの読み方:

  • すべてのファクトはリストです。 エントリが 1 つしかない場合でも、テンプレートは常にファクトを range で走査します。単独で読み取れる単一の値はありません。
  • レンダーのたびに 4 つすべて。 この provider がノードをレンダーするたびに各ファクトが報告され、レンダーが該当するものを何も出力しなかった場合は空のリストになります。チャートが ConfigMap しか出力しないコンポーネントは、4 つの空リストを報告します。他の provider のレンダーはこれらの名前を一切報告せず、誰も報告していない名前は何もないものとして読み取られます。
  • どの経路でも、出力された内容から読み取ります。 ファクトは、どのモードで生成されたかにかかわらず、レンダーが出力したドキュメントから得られます。チャートのレンダー済みマニフェスト、合成された Workload のマニフェスト、そして作成者が artifacts: で配置したマニフェストで、後者はそれらのマニフェストが持つ内容をそのまま報告します。ファクトは、この provider がビルドの重複名チェックのために報告するリソース名と同じパスで、同じドキュメントから読み取られます。リソース自身の来歴ラベルはその内容の一部であるため、単独の Pod の labels にはそれらが含まれます。チャートやアーティファクトの Pod テンプレートは、作成者が書いたラベルを保持します。
  • エントリは、コンポーネント自身のレンダーとその Features のレンダーの両方から得られます。 1 つのコンポーネントが複数の呼び出しでレンダーされることがあり(たとえばチャートと artifacts: の配置)、1 つの名前がそれらの呼び出しから得るリストは、呼び出しが実行された順に 1 つに結合されます。.context.used_by と .context.uses では、接続の相手側にあるコンポーネントのファクトに、そのコンポーネントにアタッチされた Features がレンダーした内容も、自身のものの後に結合されます。.context.render_facts はコンポーネント自身のレンダーのみを持ちます。
  • 出力された順序。 エントリは、レンダーがリソースを出力した順序に従います。ラベルマップはコンテキスト上の他のマップと同じくキー付きマップであるため、それを走査するテンプレートはキーをキー順に受け取ります。
  • ドキュメントが省いたものは、エントリも省きます。 generateName で命名されたリソースには name がありません。metadata.namespace を書かないリソースには namespace がなく、空または null で書いたリソースも同様です(どの namespace も指定していないためです)。matchLabels なしで書かれたコントローラー(クラスターが生成するセレクターに依存する Job など)には match_labels がありません。セレクターのない Service には selector がありません。名前やプロトコルのないポートにはそのどちらもありません。それ以外の、空で書かれた部分は空として報告されます。protocol はドキュメントが書いている場合にのみ報告されるため、それを必要とするテンプレートはクラスター自身のデフォルトである TCP を自ら書きます。container_port は、ドキュメントが書いている場合は常に数値です。
  • namespace はドキュメントが書いたものであり、推測ではありません。 これはリソース自身の metadata.namespace です。Pod テンプレートの場合は、それを持つリソースのもので、そこが Pod の実行場所です。Pod テンプレート自体の中に書かれた namespace は読み取られません。合成された Workload は、境界が宣言する namespace を出力するすべてのリソースに書くため、そのエントリはその namespace を持ちます。チャートのエントリは、出力されたドキュメントが書いた内容を持ちます。境界が namespace を宣言している場合は、チャートのテンプレートがそれを投影するか provider がリソースをそこに配置するかにかかわらず(Sourced モードを参照)その namespace を持ちますが、テンプレートが独自の namespace を固定している場合はそちらを持ちます。何も宣言されていない場合は、テンプレートが投影するならリリース namespace である default を持ち、何も書かないなら何も持ちません。何も書かれていない場合、エントリは境界やクラスターのデフォルトではなく namespace を持ちません。そのようなリソースは出力を適用するツールが配置する場所に置かれ、それはビルド実行時にはわからないからです。テンプレートは optional で両者を区別できます。{{ optional . "namespace" "" }} はドキュメントが何も書かなかった場合にのみ空になるため、コンポーネントの Pod の横に何かを配置する Feature は、Pod の namespace が判明しているコンポーネントとそうでないコンポーネントを区別できます。
  • kind と API グループで認識します。 Pod と Service は core グループで、4 つのコントローラーは apps で、Job と CronJob は batch で、グループのどのバージョンでも読み取られます。別グループのカスタムリソースがたまたまこれらの kind 名を持っていても、それとしては読み取られません。セレクターの matchExpressions は報告されず、kind: List ドキュメント内にラップされたリソースや YAML マージキーで書かれた値も報告されません。

ファクトから見えないもの。 ファクトはビルドが出力するドキュメントを記述するもので、クラスターが後から作成するものは含みません。コントローラーが実行時にカスタムリソースから作成する Pod(たとえばオペレーターのデータベースクラスター)はどの出力ドキュメントにも現れないため、構造上存在しません。マニフェストの適用時に mutating admission controller が追加するラベルも同様です。そのような Pod を許可する必要がある Feature は、これらのファクトがない場合に作成者がするのと同じように、カスタムリソース自身のドキュメントからラベルを取得します。

ホストを呼び出すコンポーネントの Pod だけをホストの Pod に許可し、ホスト自身の Pod をホストのコントローラーセレクターで選択する FeatureRecipe:

apiVersion: aggrega.ai/v1beta1
kind: FeatureRecipe
metadata:
name: admit-callers
version: 1.0.0
spec:
capability: helm
implements: example/admit-callers:1.0.0
readsCallerRenderFacts: true
artifacts:
allow-callers.yaml: |
apiVersion: networking.k8s.io/v1
kind: NetworkPolicy
metadata:
name: {{ .context.rendered_name }}-allow-callers
spec:
podSelector:
matchLabels:
{{- range .context.render_facts.controller_selectors }}
{{- range $k, $v := .match_labels }}
{{ $k }}: {{ toJson $v }}
{{- end }}
{{- end }}
policyTypes:
- Ingress
ingress:
- from:
{{- range .context.used_by }}
{{- range .render_facts.pod_template_labels }}
- podSelector:
matchLabels:
{{- range $k, $v := .labels }}
{{ $k }}: {{ toJson $v }}
{{- end }}
{{- end }}
{{- end }}

この provider が Workload を合成したコンポーネント web から呼び出されるホスト api の場合、ポリシーは app: "api" を選択し、web の Pod テンプレートのすべてのラベルを持つ podSelector を許可します。これは、出力された Deployment の spec.template.metadata.labels が持つラベルと同じです。FeatureRecipe がこのキーを設定しているため、そのアタッチメントはすべてのコンポーネントのレンダー後にレンダーされ、ビルドが api と web のどちらに先に到達してもファクトは揃っています。このキーがない場合、.context.used_by 上の render_facts を読むテンプレートは、何もレンダーされる前にビルドを停止させます。

ポリシーの from 内の podSelector はポリシー自身の namespace の Pod にマッチするため、上のポリシーは、適用された namespace に出力された呼び出し元を許可します。エントリが別の namespace を持つ呼び出し元は、その podSelector を、その namespace の kubernetes.io/metadata.name ラベル(Kubernetes がすべての namespace に設定します)に対する namespaceSelector と組み合わせることで許可されます。

Provider 固有の注意点

  • チャートのダウンロードには Helm の組み込みハンドラーのみを使用します。 Helm リポジトリから取得するチャートは、Helm 自身の組み込みの http および https ハンドラーでダウンロードされます。Helm のダウンローダープラグイン(helm コマンド用にインストールされたもの、またはビルドを実行するディレクトリに置かれたもの)が参照されることはないため、そのディレクトリの内容によってチャートの取得方法が変わることはありません。

  • 来歴情報の注入。 ソース指定パスと合成パスは、同じラベルとアノテーションのセットに収束します。ソース指定のレンダリングでは、ポストレンダーの YAML 書き換え(Helm SDK がレンダリングを終えた後)によってこれらを注入するため、チャート作成者が自分のテンプレートに Aggrega のラベルを通す必要はありません。

  • 環境変数の順序 — Secret から読むエントリが先。 合成されたコンテナの env リストには 2 種類のエントリが入ります。as: env で配信される各 attachments エントリは valueFrom.secretKeyRef を通じて Secret から値を読み、各 variables エントリはプレーンな value を持ちます。プロバイダーは Secret から読むエントリをすべて先に書き、プレーンな変数をすべてその後に書きます。各種類の中では記述された順序に従い、envFrom のソースは別途 envFrom の下に列挙します。Kubernetes は env の値に含まれる $(NAME) 参照を、同じコンテナ内でそれより前に列挙されたエントリから展開し、後に列挙されたエントリからは展開しません。そのため、この順序により、シークレット自体は Secret に置いたまま、プレーンな変数が参照によって Secret から読んだ値を組み込めます。

    containers:
    api:
    image: "api:1.0"
    variables:
    DATABASE_URL: "postgres://app:$(DB_PASSWORD)@db:5432/app"
    attachments:
    DB_PASSWORD: { from: db-credentials, as: env }

    レンダリングされたコンテナでは DB_PASSWORD が DATABASE_URL より前に列挙されるため、プロセスはパスワードが埋め込まれた URL を受け取ります。変数はそれより前に記述された任意の変数も参照できるため、variables 内での記述順序には意味があります。init コンテナも同じ順序に従います。1 つの名前を variables エントリとしても、as: env で配信される attachments エントリとしても指定するコンテナは、両方のエントリを書く代わりにビルドを停止させます。そうしなければ、プロセスがどちらの値を受け取るかがこの順序だけで決まってしまうためです(A container gives one environment variable two values(コンテナが 1 つの環境変数に 2 つの値を与えています)を参照)。

  • 名前空間のカスケード — 2 つのモードはリソースへの到達方法が異なります。 どちらもバウンダリのアノテーションカスケードから aggrega.ai/namespace を読み、どのバウンダリも名前空間を宣言していない場合に名前空間を作り出すことはありません。合成モードでは、プロバイダーが metadata.namespace を直接書き、カスケードが値を返さない場合はこのフィールドを完全に省略します。ソース指定モードでは、プロバイダーはその値をチャートのリリース名前空間として渡し(カスケードが値を返さない場合は default)、それを反映するかどうかはチャート自身のテンプレートが決めます。名前空間が宣言されている場合、プロバイダーはさらに、チャートが名前空間なしでレンダリングしたすべての名前空間付きリソースにそれを書き込みます(Sourced modeを参照)。したがって、名前空間が宣言されていれば、両モードともすべての名前空間付きリソースをその名前空間に配置します。ただし、チャート自身が固定した名前空間と、プロバイダーが分類できない kind は除きます。宣言がない場合は両者で異なります。リリース名前空間を反映するチャートは、合成出力では何も書かれないところで、リソースを default に配置します。名前空間を書かないチャートはどの名前空間にも配置しないため、リソースはマニフェストを適用するツールが置く場所に配置されます。標準ライブラリの FeatureRecipes が持つローカルチャートは、代わりに valuesMapping を通じてカスケードの値を直接読みます。こうすることで、どのバウンダリも名前空間を宣言していない場合にフィールドを省略でき、合成出力と一致させられます。リリース名前空間は決して空にならないため、それだけではこれを表現できません。

実例

Sourced モード — ベンダリングされたチャートを指す Recipe:

apiVersion: aggrega.ai/v1beta1
kind: Recipe
metadata:
name: api-server-helm
version: 1.0.0
spec:
capability: helm
implements: core/api-server
source: ./vendor/charts/api-server
valuesMapping: |
image: "{{ .values.image }}"
replicaCount: {{ optional .infra `replicas` 2 }}
service:
type: ClusterIP
port: {{ .values.port }}
env:
LOG_LEVEL: "{{ optional .values `log_level` "info" }}"

Workload モード — インラインの Workload を宣言する Recipe:

apiVersion: aggrega.ai/v1beta1
kind: Recipe
metadata:
name: api-server-workload
version: 1.0.0
spec:
capability: helm
implements: core/api-server
workload: |
apiVersion: aggrega.ai/v1beta1
kind: Workload
replicas: {{ optional .infra `replicas` 2 }}
containers:
api:
image: "{{ .values.image }}"
ports:
web: {{ .values.port }}
services:
svc:
type: ClusterIP
ports:
web: {{ .values.port }}

相互参照