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

テンプレート展開マトリクス

テンプレート展開リファレンス — 完全なマトリクス

Aggrega DSL は、YAML エンティティ内の複数の場所で Go の text/template による展開(Sprig ライブラリを事前登録済み)をサポートします。各場所で利用できる参照の集合は決まっており、それはコンパイルの進行に伴ってデータがいつ確定するかによって決まります。このページは、どこで何を参照できるかについてのリファレンスです。

1. パイプラインのタイミングツリー(データが確定するタイミング)

どの参照が利用できるかを理解するには、各データがいつ解決されるかを理解する必要があります。以下のステージは実行順に並んでおり、それぞれが行う処理にちなんで名付けられています。このページの以降の部分では、その名前でステージを参照します。

Resolution — resolver and syntax validator
├── .parameters → Interpolated into the Aggregate's text; the merged map
│ then stays readable to path templates only
├── .values → schema-validated against the Component's pillar schema, concrete
├── .infra → Release-merged into target components/features, concrete
└── Catalog entities → Resolved (extends merged, pillar schemas composed, usesSchema extracted)
Topology construction
├── .context.instance_id → Node identity, written as a name (e.g., "data-layer-zdmain-db")
└── .context.labels → From Catalog + label-transform mutations
Graph finalization
├── .context.annotations.release → Cascaded from boundary hierarchy
├── .context.annotations.catalog → From Component metadata.annotations
├── .context.annotations.aggregate → Cascaded from subsystem hierarchy
└── feature_values_mapping → 5-Tier Onion Model normalized
Rendering begins. Provides evaluation — locals preamble, then provides
├── .context.rendered_name → Asked of each node's provider before the preamble; present only where
│ that provider derives a name for the node's output
├── .locals (per node) → Block resolved in author order; an entry reads earlier siblings
└── .provides (all nodes) → Self-contained templates evaluated (any order), reading .locals
Inject hydration — self-inject resolution
└── component.inject → value: literals expanded, from: own provides resolved
Inject hydration — uses-inject resolution
└── uses[].inject → from: target provides resolved
Inject mapping — injectMapping interception
└── .context.inject → Fully populated pipe, intercepted by FeatureRecipe injectMappings
Base rendering
└── Full template context → Everything available
The plugin pipeline — post-render mutation
└── Full template context + .steps → Inter-step pipeline outputs available

2. テンプレート展開マトリクス

DSL 内で Go テンプレート式が評価されるすべての場所と、それぞれで利用できる参照の正確な一覧です。

#Locationエンティティ評価されるステージ利用できる参照
1Aggregate YAML 文字列内の {{ .parameters.X }}Aggregate解決(補間).parameters のみ。その他のデータはまだ解決されていません。
2Release YAML 文字列内の {{ .parameters.X }}Release評価されないなし。Release の文字列は記述どおりに読まれます。infra: の下、アノテーション内、または parameters: の値として書かれた {{ .parameters.X }} は、そのリテラルテキストのまま宛先に届きます。Release はパラメータ値を提供し(インラインの parameters: マップと $import: で読み込まれた値が、マージされたパラメータマップにまとめられます)、Aggregate の文字列がそれを読み(#1)、パステンプレートも同様に読みます(#3)。
3directory / subDirectory テンプレートRelease の境界レンダリング(パス評価).capability、.boundary_name、.parameters.X、.manifest.recipe_name、.parent_boundary.*、および .component_id(subDirectory: のみ。directory: テンプレートはこれを拒否します)。
4Component の inject value: 文字列Aggregate のコンポーネント自己 inject の解決.values、.infra、.context.instance_id、.context.labels、.context.annotations.*(3 つのバケットすべて)、.metadata.*(release_name、release_version、environment、aggregate_name)。禁止: .context.inject(循環。パイプが構築中のため)、.context.uses(コンポーネント間の接続には代わりに uses[].inject を使用します)。このテンプレートは Aggregate のテキスト内にあり、そのテキストは #1 のパラメータ補間が先に読むため、この段階に届くようにエスケープして記述します — value: '{{"{{"}} .metadata.release_name }}'。そのまま記述すると、補間がそれを評価して停止します。Aggregate のテキストは .parameters 以外のルートを定義しないためです。
5source フィールドの文字列(トップレベルの文字列、または構造化された source: マップの文字列値のサブフィールド)Recipe / FeatureRecipeソース解決ソースが何を指すかで決まる 2 つのサーフェス。 リモート座標(レジストリ、チャートリポジトリ、または git リポジトリを指す構造化ブロックの version、chart、ref、module_subdir)は、aggrega pull がアーティファクトを解決して固定する際に評価されます。利用できるのは .values、.infra、.locals と静的文字列のみで、Aggrega 独自のヘルパー(optional、capitalizedWords、index)は使えますが Sprig の関数は使えず、.context ルートもありません。そこで評価される .locals のエントリは、それらのフィールドが直接または別のエントリを介して読むものです(いずれかのフィールドが特定のエントリを指さない形で .locals を読む場合は全エントリ)。どのフィールドも読まないエントリはレンダリングに委ねられます。ワークスペース内のパスを指すソースは、エンティティのレンダリング時に評価されます。利用できるのは .context.instance_id、.values、.infra、.locals(宣言元エンティティの解決済みブロック全体)、静的文字列です。そこでは FeatureRecipe のソースはさらに .attachment_name を読み(解決対象はアタッチメントであるため)、その .context.instance_id はホストコンポーネントを指し、あわせてホストコンポーネントの報告名である .context.rendered_name も利用できます(#9 を参照)。境界スコープの FeatureRecipe は .boundary.* を読み、コンポーネント単位のピラーは一切読みません。両方で禁止: .context.inject、.context.uses、.provides(自己完結性の不変条件。ワークスペースソースのサーフェスは宣言元エンティティ自身の locals とコンテキストを共有するため、両者は同じ参照を許可・拒否し、リモート座標はそのコンテキストのサブセットを読みます。ソース解決は、トポロジーパイプがハイドレートされる前、かつチャート、モジュール、アーティファクト本体が読み込まれる前に完了しなければなりません)。
6Recipe の provides テンプレートRecipeprovides の評価.context.instance_id、.context.rendered_name(ノードの provider がそのノードのためにレンダリングする出力に付ける名前。作成者が提供したソースから、または provider が合成するワークロードから得られます。そのような名前を報告しない provider のノードでこれを読むと停止します。レンダリングされたリソースの命名を参照)、.values、.infra、.locals(ノードの解決済みブロック全体。locals はこのステージのプリアンブルで provides より先に解決されます)、静的文字列。禁止: その他すべてのルート。.context.inject、.context.uses(ノード間)、.context.annotations.*、.context.labels、.context.metadata、.metadata.*(配置・デプロイに結合)、および .attachment_name(基底 Recipe の provides 評価中はアタッチメントを解決しないため)。このチェックは肯定的な許可リストであり、provides コンテキストが公開していないルートを参照すると停止します(自己完結性の不変条件。トポロジカルソートなしでの並列評価を可能にします)。locals ブロックが宣言していないキーを指す .locals.<key> も停止します。このピラーはキー付きのオープンなマップであり、ルートのチェックだけでは監視できないためです。
7Recipe の valuesMapping(インライン、ファイルの $import:、またはライブラリの $import:)Recipe基底レンダリング完全なテンプレートコンテキスト: .values、.infra、.context.*(instance_id、rendered_name、labels、annotations、inject、uses)、.locals、.provides、.features、.metadata。インラインで記述された .context.rendered_name の参照は、#6 と同様に、そのような名前を報告しない provider のノードで停止します。$import: で読み込まれた本体内の参照はチェックされず、そのようなノードでは空としてレンダリングされます。
8FeatureRecipe の injectMappingFeatureRecipeinject マッピング完全なテンプレートコンテキスト: .values、.infra、.context.*(.context.inject(インターセプト対象のパイプ)と .context.uses を含む)。ここでは .context.used_by は空です。マッピングの出力はホスト自身の配信パイプに入るためです。.context.render_facts は存在しません。マッピングはホストのレンダリング前に実行されるためです。.context.rendered_name は #9 と同様にホストコンポーネントの報告名です。これを読むマッピングはチェックされず、名前を報告しない provider のホストでは空としてレンダリングされます。FeatureRecipe の executionScope にかかわらずコンテキストは同じです。境界スコープの FeatureRecipe のマッピングは、アタッチメントが到達する各コンポーネントについて 1 回ずつ実行され、そのコンポーネントの .context.* を読み、.features.<attachment>.provides と .locals は 1 回の境界評価の結果として読みます。禁止: .boundary。どのコンポーネントのコンテキストもこれを持たないため、参照するとビルドが停止します。
9FeatureRecipe の valuesMapping(およびその workload: と artifacts:)FeatureRecipe基底レンダリング完全なテンプレートコンテキスト + .attachment_name、.inject(アタッチメントが inject: ブロックを記述している場合の、アタッチメント自身の inject: エントリ)、.context.render_facts(ホストの provider がホストのレンダリングについて報告した内容)、および .context.used_by(ホストを使用するコンポーネント。FeatureRecipe が readsCallerRenderFacts: true を設定している場合、それぞれが自身のレンダリングファクトを持ちます)。FeatureRecipe が readsTargetRenderFacts: true を設定している場合、.context.uses の各接続はターゲットのレンダリングファクトを .render_facts に持ちます。.context.instance_id と .context.rendered_name は、ホストコンポーネントの識別子と、ホスト自身の provider がそれについて報告する名前です。これはホストの Recipe が読むのと同じ値であり、FeatureRecipe の locals: と provides: でも同様です。インラインで記述された .context.rendered_name の参照は、そのような名前を報告しない provider のホストで停止します。.source は FeatureRecipe 自身の評価済みの source: であり、ホストコンポーネントのものになることはなく、FeatureRecipe が宣言していない場合は何も保持しません。
10パイプラインの with: ブロックRecipe / FeatureRecipeプラグインパイプライン完全なテンプレートコンテキスト + .steps(先行するパイプラインステップからのステップ間出力)。ここでは .context.used_by は空で、.context.uses のどの接続もターゲットのレンダリングファクトを持ちません。ステップはホスト自身のドキュメントを書き換える場合があるためです。アタッチされた FeatureRecipe のステップは、#9 と同様に、ホスト自身のレンダリングファクトである .context.render_facts を読みます。
11Recipe の workload: 本体(インラインか $import: で読み込まれたかを問わず、内部のすべてのテンプレート化されたフィールド)Recipe基底レンダリング完全なテンプレートコンテキスト。 Workload 本体内のすべてのフィールド(replicas、containers.<name>.image、containers.<name>.variables.<KEY>、containers.<name>.ports.<port>、services.<name>.ports.<port>、volumes.<name>.*、health.*)は、Workload 文字列全体を処理する同一のテンプレート評価の一部です。Workload の内容は、完全なテンプレートコンテキストに対して一度だけ評価される単一の Go テンプレートであり、内部のフィールドレベルのテンプレートは別の評価ではなく同じ評価の中で解決されます。

自己完結性に関する注記。 source 文字列(#5)は provides の自己完結性不変条件(#6)を共有します。どちらのサーフェスも .context.inject と .context.uses の参照を拒否します。ソース解決は .context.inject を埋める inject ハイドレーションより前に、また解決済みのソースを下流の何かが消費するより前に実行されます。そのため、この規則とその根拠は両方のサーフェスに及びます。両者が異なるのは provides ピラーです。ワークスペースの source は宣言元エンティティの locals とコンテキストを共有し、リモート座標はそのサブセットを読み取るため、どちらも .provides を拒否します。一方、provides はそれ自体が解決対象のサーフェスです。どちらも .locals を読み取ります。この規則は FeatureRecipe の source にも Recipe の場合と同じ条件で適用され、それぞれそのエンティティ自身の locals サーフェスに照らしてチェックされます。

Workload 本体のテンプレートに関する注記(#11)。 Workload 本体は 1 つのテンプレート文字列であり、レンダラーはこれを全体として評価してから、その結果を Workload ドキュメントとしてパースします。内部のフィールドレベルのテンプレート(こちらの replicas: {{ .infra.replicas | default 1 }}、あちらの containers.app.variables 内の LOG_LEVEL: "{{ .values.log_level }}")は個別のテンプレート評価箇所ではなく、Workload を生成する単一のベースレンダリング評価にすべて参加します。Workload 内部のフィールドに個別の利用可能性規則は必要ありません。Workload 全体に対する規則(#11)が内部のすべてのフィールドレベルのテンプレートをカバーします。

Workload 本体内での判別を考慮したフォールバック。 上記の replicas: {{ .infra.replicas | default 1 }} の例は、「作成者が replicas を設定していない」場合と「作成者が replicas を 0 に設定した」場合を混同します。default はどちらの場合にも発動します。Release がゼロへのスケール(Knative / KEDA で一般的なパターン)を表すために正当に infra.replicas: 0 と記述した場合、| default 1 の形式はその意図を暗黙に上書きしてしまいます。判別を考慮した形は replicas: {{ optional .infra "replicas" 1 }} です。optional はキーの有無をチェックし、キーが設定されていれば記述された値(記述されたゼロを含む)を返し、キーが存在しない場合にのみ 1 にフォールバックします。完全なセマンティクスと、どちらを優先すべきかのガイダンスについては sprig-functions.md を参照してください。

3. 禁止される参照とその根拠

Location禁止される参照根拠
Component inject value:(#4).context.injectその時点で inject パイプは構築中です。自己 inject の value: テンプレートは、自身が寄与するパイプから読み取ることはできません。
Component inject value:(#4).context.usesコンポーネント間の配線は uses[].inject に置きます。コンポーネントの自己 inject の value: テンプレートは、そのコンポーネント自身のデータに閉じたままです。
Recipe provides(#6).context.injectprovides テンプレートは任意の順序で評価され、ノード自身のデータ(.values、.infra、.locals、.context.instance_id、.context.rendered_name)のみに閉じています。inject パイプは inject ハイドレーションまで埋められず、inject ハイドレーションはすべてのノードの provides が評価された後に実行されます。
Recipe provides(#6).attachment_nameベースの Recipe の provides パスはアタッチメントを解決しないため、名前は空でレンダリングされることになります。このルートは空のまま渡されるのではなく、拒否されます。
source (#5).providesどちらのソースサーフェスも provides ピラーを持ちません。ワークスペースソースのサーフェスは宣言元エンティティ自身の locals とコンテキストを共有しますが、そこには provides ピラーがなく、リモート座標はそのコンテキストのサブセットを読み取ります。locals は provides より先に解決されるため、provides: は .locals を読み取れます。ソーステンプレートは provides を遡って参照するのではなく、同じ locals を読み取ります。
Recipe locals(#6 のプリアンブル).provideslocals は provides より前に解決されるため、local が評価される時点ではノード自身の provides はまだ存在しません。provides も公開する値を必要とする local は、その値を .values / .infra から直接計算し、provides のエントリがその local を読み取ります。
Recipe locals(#6 のプリアンブル).context.rendered_nameRecipe の locals はその source テンプレート(#5)とコンテキストを共有し、そのサーフェスは名前を提供しません。ノードがソースを提供するかどうか(これは source テンプレートが決定します)は、名前が依存する要素の 1 つだからです。この参照は unknown-root 診断で停止し、その診断は .context がそこで定義するものとして .context.instance_id を挙げます。代わりに、provides エントリ、またはベースレンダリング段階のテンプレートでこのキーを読み取ってください。
Recipe provides(#6).context.uses.context.uses は他のノードの provides を参照し、provides の評価はそれらを任意の順序で実行します。provides テンプレートは自己完結したままであるため、評価は順序に依存しません。
FeatureRecipe の locals、provides、source(#5)およびインラインのレンダーテンプレート(#9、#10)。プロバイダーが名前を報告しないホスト上の場合.context.rendered_nameFeature のアタッチメントでは、このキーはホストコンポーネントの報告された名前を保持します。アーティファクトセットのみを配置するホストや、そのような名前を導出しないプロバイダーを通じてレンダリングするホストには、保持すべき名前がありません。この参照は unknown-root 診断で停止し、その診断は .context がそこで定義するものの中に .context.instance_id を挙げます。代わりに ID を読み取ってください。そのようなホストでは、ホスト自身のリソースはこの ID に基づいて命名されます。
source (#5).context.injectソース解決は .context.inject を埋める inject ハイドレーションより前に実行されます。ソース URI が評価される時点では、パイプはまだ埋められていません。
source (#5).context.usesソース解決は、下流の何かが宣言元エンティティのチャート、モジュール、またはアーティファクト本体を読み込む前に完了する必要があります。ノード間の参照を許可すると、ソース解決がトポロジーの反復順序に結合されてしまいますが、ソース解決は意図的にそれを避けています。
Parameters(パステンプレート以外のすべての箇所)補間後のあらゆる値テンプレートサーフェス補間は記述された YAML 内のすべての {{ .parameters.X }} 参照を消費し、解決済みの値をその位置に書き込みます。そのため、値テンプレートサーフェスはパラメーターピラーではなく解決済みのリテラルを受け取ります。オペレーターが記述するパステンプレートは唯一の例外であり、.parameters.X を直接読み取ります。

4. 自己 inject の解決パス

自己 inject の解決は inject ハイドレーションの前半であり、すべてのノードの provides が評価された後に実行されます。コンポーネントがコンポーネントレベルの inject: ブロックを宣言している場合、コンパイラはそこでそれを評価します。

  1. リテラルの value: 文字列: 値に Go テンプレート式が含まれている場合、コンパイラはマトリクスの行 #4 のコンテキスト(.values、.infra、.context.instance_id、.metadata.* など)を使ってそれを評価します。記述は行 #4 に示すとおりエスケープします。プレーンな文字列はそのまま渡されます。
  2. from: 参照: コンパイラは、その時点で解決済みのノード自身の provides ディクショナリでキーを検索します。キーが存在しない場合、コンパイラは invalid-inject-key エラーでビルドを停止します。
  3. 衝突チェック: .context.inject パイプにマージする前に、コンパイラは、inject ハイドレーションの後半が解決する uses-inject のキーとどのキーも衝突しないことを検証します。衝突があると duplicate-delivery-key エラーでビルドが停止します。

結果の文字列は、それらの uses-inject の解決結果とともに、.context.inject.env、.context.inject.file、.context.inject.arg(および任意のカスタムメカニズム)にマージされます。inject マッピング(injectMapping)が実行される時点で、パイプには両方のソースから得た、開発者が記述したすべての inject 値が含まれています。