FeatureRecipe
FeatureRecipe エンティティの概念上の役割(ドメイン 3 — Feature インターフェースの Wasm プラグイン駆動の実装)は architecture/04-entity-taxonomy.md で説明しています。このページでは、FeatureRecipe のカタログ作成のための記述面を扱います。
カタログ上の配置
FeatureRecipes は、パスの先頭セグメントにプロバイダーを置いて整理されます(Recipes と同じパターンです):
aggrega-catalog/└── feature-recipe/ └── {provider}/ # e.g., `helm`, `compose` └── {feature-recipe-name}/ └── {version}/ └── recipe.yamlOCI URI:hub.aggrega.ai/featurerecipe/{provider}/{name}:{version}(例:hub.aggrega.ai/featurerecipe/helm/k8s-secret-from-parameter:1.0.0)。
記述の契約
FeatureRecipes は implements によって Feature インターフェースにバインドされ、具体的な provider を宣言します。その記述面は、ベースの Recipe が持つ入力種別のすべてに、FeatureRecipe 固有の 2 つのブロックを加えたものです。
- 3 つの入力種別 —
source+valuesMapping(ソース型)、workload(合成型)、artifacts: 形はベースの Recipe と同一です(Recipe Input Composition およびentities/recipe.mdを参照)。これらのいずれかを持つ FeatureRecipe はリソース生成型であり、ベースの component と並んでリソースをレンダリングします。それらのリソースの配置先には、Feature がアタッチされている component と、続いてアタッチ時の名前が含まれ、ターゲット自身のレイアウトが許す 2 つの形式のいずれかを取ります。provider が各コントリビューターに固有の位置を与えるターゲットでは、そのターゲットがコントリビューターを置くディレクトリの下、ホストのディレクトリの隣に{component}--{instance}/ディレクトリとして配置されます。ディレクトリ直下のファイルのみを読むターゲットでは、component 自身のファイルの隣に{component}--{instance}--というファイル名接頭辞として配置されます。コントリビューターを単一のドキュメントに合成する provider では、リソースは代わりにそのドキュメントに取り込まれます。Feature がどのファミリーに属するかを問わず、ServiceMonitorやExternalSecretの CRD はインラインまたは$importのartifacts:として、外部のチャートやモジュールはsource:+valuesMapping:によって、独自のコンピュート(たとえばサイドカーエージェントの Deployment)はworkload:によって記述します。valuesMapping:はベースの Recipe と同じ 3 つの記述モード(インラインのブロックスカラー、ファイルの$import:、MappingLibrary エントリへのライブラリ$import:)を共有します。entities/recipe.mdの「ThevaluesMappingfield — three authoring modes」を参照してください。慣例により、FeatureRecipe はベースの component を変更するか、その隣にリソースを追加するものですが、スキーマは使用できる入力種別を制限しません。コンパイラは FeatureRecipe が宣言したものをすべてレンダリングし、その制約はバインドされた provider の機能のみです。また、ある種別が「変更用途に適切」かどうかについては主張を持たないままです(基盤となる不変条件を参照)。合成(workload:)にはそれをサポートする provider が必要です。そうでない場合、ビルドはレンダリング時に provider の機能に関する診断を出して停止します。 injectMapping(レンダリング前のインターセプト): ベース Recipe がレンダリングされる前に実行される、ネイティブの Go テンプレートブロックです。JSON または YAML の辞書を出力し、コンパイラがそれを呼び出し元の.context.injectメモリパイプにネイティブにディープマージします。これにより、Wasm を使わずに呼び出し元側で環境変数や接続文字列を変更できます。pipeline: レンダリング後の Workload 変更(たとえば JSONPatch による Envoy サイドカーの注入や、シークレットボリュームのマウント)のための、WebAssembly(Wasm)プラグインステップの順次配列です。各ステップのpluginフィールドはPluginエンティティをその URI で指定し、常にプラグイン自身のソケット型でスコープされます(<pluginType>/<name>、任意でバージョン付き。例:parser/yamlやparser/yaml:1.0.0)。ビルドはエンティティを、プラグインの識別情報と設定されたレジストリから特定される、コンテンツアドレス指定された.wasmアーティファクトに解決します。ここでは素の.wasmやアーティファクト参照は受け付けられません。プラグインの作成と参照については Wasm プラグイン開発者ガイドを、Two-Part Plugin Principle(Fetcher / Injector)については architecture/04-entity-taxonomy.md の §「Domain 3: Infrastructure Base」を参照してください。コンパイラは各ステップを宣言順に実行します。指定されたプラグインのゲストエクスポートをレンダリング済みの出力に対してディスパッチし、返された JSON Patch と発行された副作用を適用します。各パイプライン面の実行状態については Status of the Language を参照してください。pipeline:は単独で成立します。FeatureRecipe は入力種別を一切持たずにこれを宣言でき、その場合は自身のリソースを発行せず、その効果はすべて、ビルドがすでにレンダリングしたドキュメントにステップがパッチとして適用するもの、またはその隣に発行するものになります。
FeatureRecipe はこれらのブロックを一切持たないこともできます。効果が持っている uses エッジだけである純粋な配線用の Feature は何もレンダリングせず、その FeatureRecipe は解決を満たすためだけに存在します。すべての component が Recipe に解決されるのと同じように、すべての feature インスタンスは FeatureRecipe に解決されるからです。上記のブロックのうち、ベースの Recipe に対応するものがないフィールドは injectMapping だけです。3 つの入力種別と pipeline はベースの Recipe と共通です。
FeatureRecipe の隣に固定されるものは、Recipe の隣に固定されるものと同じです: artifacts エントリがインポートする各ファイルのダイジェストと、座標が完全に書き出されている各リモート source: のダイジェストが、FeatureRecipe 自身のディレクトリにある entity.lock に記録されます。このファイルは aggrega pin が書き込み、隣にコミットします。ロックにそれらの固定が記録されていない FeatureRecipe に対する pull は、pull がそのステップの実行を求められていない限り、停止してそのステップを示します。インポートされたファイルがダイジェストと一致しなくなった場合、およびソースのダイジェストが Release のロックファイルに記録されたものと食い違う場合(git の ref: で記述されたソースは解決されたコミットで記録され、比較されません)、ビルドは停止します。FeatureRecipe のファイル自体に書き込まれることはありません。このファイルと各停止への対処方法は aggrega pull で説明しています。
ソースフィールドのテンプレート
FeatureRecipe の source: は、Recipe のものと同じ条件のテンプレート対象です。テンプレートはソース解決時に評価され、その結果がビルドで解決されます。どちらの形式も Go テンプレートを受け付けます。汎用文字列形式と、文字列値のサブフィールドがテンプレート評価され、文字列以外のサブフィールドはそのまま渡される構造化オブジェクト形式です。形式の一覧、スキームの扱い、アンカーの解釈は entities/recipe.md の「Source field templating」「Source field scheme inventory」「How a source: path is anchored」で説明されているものと同じです。このセクションでは、アタッチメントで異なる点のみを述べます。
locals: chart_dir: ./charts/exportersource: "{{ .locals.chart_dir }}"相対的な結果が何を基準に解決されるか。 それを宣言した FeatureRecipe ドキュメントを含むディレクトリです。これはアタッチメント自身のファイルであり、コンポーネントのファイルではありません。また、結果はそのディレクトリ内に留まる必要があり、これは Recipe の場合とまったく同じです。そのディレクトリの外に出る結果や絶対パスである結果は、FeatureRecipe と一緒に移動しないファイルを指すため、ビルドを停止させます。転送スキームを持つ結果は、ディレクトリに結合されるのではなくフェッチされます。レジストリから解決された FeatureRecipe は、公開されたアーカイブに含まれ、コンテンツキャッシュに展開されたファイルから読み込まれます。そのため、相対的な結果は、カタログディレクトリ内で FeatureRecipe の隣に解決されるのとまったく同じように公開内容の中で解決され、同じ制限が適用されます。
テンプレートが読み取れるもの。 参照セットは、FeatureRecipe 自身の locals: エントリがチェックされるものと同じです。これは、コンポーネントではなくアタッチメントが解決されることに起因して、Recipe のものと次の 2 点で異なります。
.attachment_nameが利用可能で、Feature がアタッチされているインスタンス名を示します。Recipe のソーステンプレートはこれを拒否します。Recipe のソースはノードに対して解決され、アタッチメントが関与しないためです。.context.instance_idは、アタッチメントではなく、アタッチメントが解決対象としているホストコンポーネントを示します。また.context.rendered_nameは、ホスト自身の provider がホストについて報告する名前を保持します。これはその provider が名前を報告する場合にのみ存在し、報告しない場合はビルドを停止させます。レンダリングされたリソースの命名を参照してください。
.locals は、この FeatureRecipe の他のテンプレートが読み取るセットを保持します。これは自身の解決済みブロックで、その下にホストの Recipe のブロックがあるため、アタッチメントが宣言したキーは同名のホストキーより優先されます。そのセットにないキーを参照すると、キーを空としてレンダリングするのではなく、停止してそのキー名を示します。.provides、.context.inject、.context.uses は、Recipe のソース対象が拒否するのと同じ自己完結性の理由で拒否されます。
境界スコープの FeatureRecipe は代わりに境界を読み取ります。 FeatureRecipe が executionScope: boundary を宣言する Feature は、コンポーネントごとに 1 回ではなく境界に対して 1 回レンダリングされるため、そのソーステンプレートには読み取るホストコンポーネントがありません。ソーステンプレートは .boundary.* を読み取ります。これはその locals: と provides: が読み取るものと同じ柱です。コンポーネントごとの柱(.context、.workload、.attachment_name、.inject)は利用できません。
空の結果。 何も生成しないテンプレートは、アタッチメントをソースなしの状態にします。これはソースなしモードであり、Recipe のソースと同じ解釈です。また、自分で source: "" と書くこととは異なります。
その後 .source が読み取るもの。 source は、Recipe の source がその Recipe 自身のマッピングより前に評価されるのと同様に、valuesMapping: より前に評価されます。そしてその結果が、後に実行されるすべてのテンプレートにおける .source になります。対象は valuesMapping:、omits:、workload: と artifacts: の本体、そして pipeline: のステップです。したがって、.source を読み取る valuesMapping: は、この FeatureRecipe 自身の source を読み取り、アタッチ先のコンポーネントの source を読み取ることはありません。また、この FeatureRecipe が source を宣言していない場合や、そのテンプレートが何も生成しない場合は、何も読み取りません。境界スコープの FeatureRecipe も同じように自身の source を読み取ります。injectMapping: はアタッチメントの source が評価される前に実行されるため、そこでの .source はホストコンポーネントのものです。
injectMapping の排他性
injectMapping フィールドは FeatureRecipes 専用です。基本の Recipe スキーマには意図的に含まれていません。この排他性により、変数のインターセプトは valuesMapping から切り離されます。ベース Recipe の valuesMapping は、FeatureRecipe の injectMapping ブロックが生成した書き換え済みの .context.inject 文字列を、それと知らずに消費するため、両者は分離されたままになります。この仕組みの動作については後述の inject-mapping インターセプトのセクションを、レンダリング前のインターセプトの完全なセマンティクスについては inject mapping に関する architecture/10-compilation-pipeline.md を参照してください。
Inject-mapping のインターセプト:injectMapping の仕組み
呼び出し元が、ターゲットの変更されていない .provides.host とは異なる形の接続文字列を必要とする場合(境界をまたぐ Kubernetes DNS のために名前空間を付加する、マルチリージョンゲートウェイのためにリージョンコードを前置する、DSN に SSL モードのサフィックスを追加するなど)、injectMapping は、ベースの Recipe の valuesMapping が inject パイプを参照するより前に、呼び出し元でその変更を処理します。
injectMapping フィールドは Go の text/template であり、レンダラーはベースの Recipe のレンダリングが実行される前に、inject マッピングの段階でこれを評価します。テンプレートは、任意のメカニズムキー(env、file、arg、またはコンポーネントの Recipe が .context.inject.<name> で読み取るカスタムメカニズム)を持つ JSON または YAML の辞書、または env がデフォルトとなるフラットなマップを出力し、レンダラーはこのオーバーレイを呼び出し元ノードの .context.inject パイプにディープマージします。injectMapping による呼び出し元側のルーティングは inject マッピングの段階で実行され、単純な文字列操作のために Wasm サンドボックスを起動することはありません。Wasm プラグインは、pipeline 配列による AST の構造的な変更のために引き続き確保されています。
各値は toJson を通して書き出します。 レンダラーはテンプレートの出力を YAML として読み込むため、引用符の間にそのまま埋め込んだ値は、二重引用符やバックスラッシュを含んだ時点で、その出力を壊すか、変更された形で読み戻されます。パスワードがその典型です。toJson は値を JSON 文字列として書き出し、YAML はそれを正確に読み戻すため、値はそのすべての文字を保ったまま渡されます:
injectMapping: | env: {{ .values.key }}: {{ .values.origin | toJson }}複数の部分から組み立てる値は、下の例のように、まず組み立ててから toJson を通して一度だけ書き出します。
読み取れない出力はビルドを停止させます。 テンプレートの出力がどちらの形としても読み取れない場合(よくある原因は、中の値によって壊れた引用符付きスカラーです)、そのキーはどれも渡せないため、ビルドは何も渡されなかったかのようにコンポーネントをレンダリングするのではなく、アタッチメントと FeatureRecipe を示して停止します。fatal-halts.md の「An attached Feature’s injectMapping output cannot be read(アタッチされた Feature の injectMapping 出力を読み取れない)」を参照してください。示される理由は、機密と宣言された値に依存する場合は伏せられます。空の出力、または何も渡さない辞書として解析される出力は、何も渡さず、失敗にもなりません。
トップレベルのキーはメカニズムであり、all はメカニズムではありません。 辞書出力の各トップレベルキーは、そのエントリが渡されるメカニズムを示します。env、file、arg、またはそれ以外の任意の名前で、後者はその名前の独立したメカニズムとして渡されます。.context.inject.all はマージ後にそれらのメカニズムから構築され、出力からマージされることはないため、all: の下に書かれたエントリはどこにも届きません。代わりにビルドは停止し、アタッチメント、キー、FeatureRecipe を示して、出力が持てるキーを説明します。fatal-halts.md の「An attached Feature’s injectMapping output writes deliveries under a key nothing delivers(アタッチされた Feature の injectMapping 出力が、何も渡さないキーの下に配信内容を書いている)」を参照してください。そのようなエントリは、コンポーネントが読み取るメカニズムの下に書いてください。
変更は厳密に呼び出し元にローカルです。 FeatureRecipe は、アタッチされたノードの inject パイプのみを変更し、ターゲットの .provides 出力は決して変更しません。ターゲットの .provides.host はクラスタ全体の多数の呼び出し元から参照される可能性があります。呼び出し元側の injectMapping は特定の呼び出し元のパイプにのみマージされるため、ルーティングの変更はそれを要求したエッジにスコープが限定されます。
マッピングが書き換えられるもの。 マッピングがレンダリングされる時点で、すべての inject: ブロックの配信は完了しています。そのため、マッピングの出力は常に、他の何かがすでに書き込んだキーの上にマージされ、誰がキーを書き込んだかによって結果が決まります。呼び出し元自身の inject: ブロック、またはその接続のいずれかの inject: ブロックが配信したキーは、マッピングが書き換えてよいものです。これがインターセプトであり、マッピングの値がその 1 つのエントリを置き換えます。マッピング自身のアタッチメントが inject: ブロックを通じて配信したキーも同様に、そのマッピングが書き換えてよいものです。別の アタッチされた Feature が、自身の inject: ブロックまたは自身の FeatureRecipe の injectMapping を通じてすでに配信したキーは、書き換えられません。最後に実行されたマッピングが呼び出し元の読む値を決めることを許すのではなく、ビルドは両方のアタッチメントを示して停止します。したがって、2 つのルーティング Features はそれぞれ自身のキーを修飾できますが、2 つの Features が 1 つのキーを両方とも配信することはできません。同じ接続のキーを書き換える 2 つのルーティング Features もこれに含まれます。1 つ目はインターセプトであり、2 つ目は 1 つ目の配信と衝突するためです。fatal-halts.md の「Two attached Features deliver one key, the later through its FeatureRecipe’s injectMapping(2 つのアタッチされた Features が 1 つのキーを配信し、後者はその FeatureRecipe の injectMapping を通じて配信)」を参照してください。
結合ゼロのターゲット推論
コンパイラは各ターゲットのカスケードされたアノテーションを呼び出し元の .context.uses パイプに埋め込むため、injectMapping テンプレートは、Ops が Feature の infra にターゲットの識別情報をハードコードすることなく、ルーティングの座標を抽出できます。
- テンプレートは
.context.usesを検索し、開発者が要求した変数を注入した正確なトポロジー上のエッジを見つけます。 - ターゲットのカスケードされた
release_annotations(例:aggrega.ai/namespace)を抽出します。 - 完全修飾ドメイン名(FQDN)または接続文字列を整形します。
- オーバーライド辞書を出力します。
コンパイラはネットワークのセマンティクス(Kubernetes の名前空間、クラウドリージョン、ブリッジプロキシのトポロジー)に依存せず、テンプレートが生成したものを使って単にディープマージを実行します。その後ベースの Recipe の valuesMapping が実行されると、.context.inject.env からインターセプトされ書き換えられた文字列を、開発者のオリジナルであるかのように参照します。
実例:K8s DNS リゾルバー
標準カタログは、これを helm の FeatureRecipe を伴う core/k8s-dns-resolver として提供しています。環境変数名はコンテナ内で一意でなければならないため、target_var(例:API_HOST)は、呼び出し元内の特定の注入契約を表すグローバルに一意な識別子として機能します。.context.uses 内の明示的なエッジをループし、どのエッジが target_var を要求したかを確認することで、テンプレートは正しいターゲットノードを特定し、その名前空間を読み取ります。唯一のパラメータは書き換える変数であり、ターゲットとその名前空間は検出されるもので、決してハードコードされません。
ルーティング Feature のスキーマ(core/k8s-dns-resolver):
infra: { target_var: string # Ops dictates WHICH injected var to rewrite}FeatureRecipe の実装:
injectMapping: | # 1. Grab the atomic base host directly from the flattened pipe, or an # empty value when nothing was injected under target_var {{ $base_host := optional .context.inject.env .infra.target_var "" }}
# 2. Dynamically locate the specific edge that injected this variable {{ $target_edge := dict }} {{ range $alias, $edge := .context.uses }} {{ if hasKey $edge.inject.env $.infra.target_var }} {{ $target_edge = $edge }} {{ end }} {{ end }}
# 3. Read the target's namespace from its cascaded release annotation, # coalescing an absent namespace to "default" {{ $ns := "default" }} {{ if $target_edge.annotations }}{{ if $target_edge.annotations.release }} {{ $raw := optional $target_edge.annotations.release "aggrega.ai/namespace" "" }} {{ if $raw }}{{ $ns = $raw }}{{ end }} {{ end }}{{ end }}
# 4. Qualify the host with the namespace — but only when a target connection # and a base host were actually found, so a target_var that matches no # connection injects nothing instead of a spurious variable. An unset # namespace resolves to "default", where the helm provider deploys an # unannotated workload, so the qualified host always matches the service's # actual location and is never malformed. {{ if and $target_edge $base_host }} {{ $resolved_host := printf "%s.%s" $base_host $ns }}
# 5. Emit the precise override dictionary for the compiler to deep-merge env: {{ .infra.target_var | toJson }}: {{ $resolved_host | toJson }} {{ end }}ルーティング以外のユースケース
injectMapping は境界をまたぐアドレス解決(上記の K8s DNS リゾルバなど)に最もよく使われますが、この呼び出し側での変更は、インフラのレンダリング前に開発者の意図を横取りして整形する必要があるあらゆる場面に適用できます。その範囲を示すパターンをさらに 2 つ紹介します。
動的なセキュリティ整形(SSL アペンダー)。 企業がすべての外部データベース接続に厳格な TLS 検証を義務付けている場合、Feature は開発者が要求した DB_URL を横取りし、必要な SSL モードを付加できます。これにより、アプリケーションは正しいセキュリティパラメータで起動します。
# Inside force-ssl-featureinjectMapping: | {{ $base_url := index .context.inject.env .infra.target_var }} env: {{ .infra.target_var | toJson }}: {{ printf "%s?sslmode=verify-full" $base_url | toJson }}マルチリージョンのゲートウェイ接頭辞付与。 汎用的な API コンポーネントがグローバルにデプロイされている場合、リージョンごとのルーティング Feature は自身の環境境界アノテーションを自律的に参照し、呼び出し元に注入される接続文字列に接頭辞を付けることができます。
# Inside regional-routerinjectMapping: | {{ $base_host := index .context.inject.env .infra.target_var }} {{ $region_code := index .context.annotations.release "cloud.aggrega.ai/region" }} env: {{ .infra.target_var | toJson }}: {{ printf "%s.%s" $region_code $base_host | toJson }}injectMapping の境界。 この仕組みが変更できるのは .context.inject メモリパイプ(Delivery Contract)に限られます。新しいコンテナの追加、ボリュームのマウント、ベースの Recipe の valuesMapping 出力の変更はできません。レンダリングされた AST に構造的な変更(JSON や YAML の配列など)を必要とする変更は、FeatureRecipe の pipeline 配列に置き、WebAssembly プラグインを介して実行します。
pipeline のパッチ対象の境界。 pipeline のステップがパッチを当てられるのは、プロバイダが構造化されたツリーとしてレンダリングする出力だけです。YAML 形式および JSON 形式の出力は構造化されており(JSON で記述された Terraform の .tf.json モジュールを含む)、ステップの JSONPatch は指定された値をその場で編集し、それ以外のバイト(コメント、順序、書式)には一切触れません。ネイティブ HCL の Terraform 設定のように、プロバイダが不透明な本体として出力するものはパッチ対象ではありません。不透明な本体に対するパッチは、構造的に指定できないテキストを変更するのではなく、診断とともにビルドを停止します。したがって、不透明な出力に対して pipeline ステップを記述することは設計上の誤りであり、何もせずに無視されるのではなく、明示的な停止として表面化します。
ベンダリングされた Terraform モジュールの入力はパッチ対象ではなく、このことは明記しておく価値があります。 これらはそのコンポーネントの module ブロックの引数であり、terraform プロバイダが境界の ルート 設定に書き込みます。ネイティブ HCL であるため上記の規則により不透明であり、ステップがパッチを当てるノードの出力ではなく境界全体の成果物です。そのため、pipeline ステップがそれらを指定できる位置は存在せず、ソースとして取り込んだ Terraform モジュールが受け取る値を変更する手段もありません。これらの値は記述される場所、つまりベースの Recipe の valuesMapping: で整形します。
条件付きステップ — when:
pipeline のステップには、省略可能な when: フィールドを指定できます。これはインラインの Go テンプレートで、コンパイラがパイプラインの走査時に、そのステップの with: 本体と同じテンプレートコンテキストと評価器を使って評価します。レンダリングされた結果によって、そのステップを実行するかどうかが決まります。
- 結果が 偽となる値 の場合、そのステップはパススルーとしてスキップされます。ドキュメントセットは変更されないまま次のステップへ渡され、スキップされたステップは何も寄与しません。パッチも、副作用も、実行された記録も残りません。
when:が 空または未指定 の場合、ステップは常に実行されます。
when: と optional: は互いに独立しています。when: はステップを実行するかどうかそのものを決め、optional: は 実行中の ステップの失敗を緩和します。ステップは両方を宣言できます。when: が実行に入るかどうかを制御し、ステップが実際に実行された場合は、その内部での失敗の扱いを optional: が決めます。レンダリングに失敗した when: テンプレートはオーサリングの欠陥であり、optional: に関係なくビルドを停止させます。
レンダリングされた when: のテキストは、共通のブール値テンプレート規則によって判定されます。文字列 true、True、TRUE、0 以外の任意の数値、およびその他の空でない任意の文字列は真となり、文字列 false、False、FALSE、空文字列、および数値の 0 は偽となります。
認証情報 FeatureRecipe パターン
FeatureRecipe が認証情報の Feature(feature.aggrega.ai/kind: secret というラベルを持つもの)を実装する場合、Two-Part Plugin Principle に従うことができます。これは Fetcher プラグイン(ボールト固有の CRD を生成)と Injector プラグイン(シークレットを対象コンテナにマウント)を連結する pipeline で、examples/04-secrets が説明する形です。標準ライブラリの認証情報用 FeatureRecipes は pipeline: を宣言せず、シークレットのリソースを自らレンダリングします。examples/05-credential-features を参照してください。
認証情報 FeatureRecipe は、他のアタッチメントと同じ Resource Generation パスを通じてレンダリングされ、その pipeline: も同じ条件で実行されます。コンパイラは、そのパスで処理すべき作業を持つすべてのアタッチメントを 1 つの順序付きシーケンスとして巡回し、それぞれが宣言したパイプラインを、同じ /own および /host ドキュメントセットのセマンティクスで実行します。アタッチメントがこのシーケンスに加わる理由は 2 つのいずれかです。その FeatureRecipe が入力の種類を宣言しているため独自のリソースを生成する場合、または pipeline: を宣言しているため既に出力されたドキュメントを書き換える場合です。したがって、認証情報のアタッチメントは、運用のアタッチメントとまったく同様に、ホストコンポーネントのレンダリング済みドキュメントに手を加えることができます(シークレットボリュームのマウントや env 参照の追加など)。両者の唯一の違いは、自身が生成したファイルの出力先です。
component 上では、Feature の sensitivity 宣言は、Component の宣言がその Recipe に従うのとまったく同じように、FeatureRecipe の valuesMapping: に従います。 FeatureRecipe が valuesMapping: を持たない source: からレンダリングする場合、ターゲットが受け取る値は Feature が宣言するリーフパスをキーとするため、sensitive: true と宣言されたリーフは、レンダリングされたキーをマークします。FeatureRecipe が valuesMapping: を宣言する場合、キーはそのテンプレート独自に作り出したものであり、それを指す宣言はないため、ビルドはそのようなリーフごとに、アタッチメント、リーフ、FeatureRecipe を示すアドバイザリを 1 件出力します。境界にアタッチされた Feature ではアドバイザリは出力されません。その .values は常に空であり、マークする値を持つ宣言済みリーフが存在しないためです。A declared-sensitive value reaches the target through a values mapping(sensitive と宣言された値が values mapping を通じてターゲットに到達する) を参照してください。
provides: ブロック — コンシューマーへの公開
FeatureRecipe の provides: ブロックは、その公開出力です。アタッチメント自身のスコープ(.values、.infra、FeatureRecipe の完全に解決された .locals、およびホストノードの .context.instance_id と .context.rendered_name)に対して評価される Go テンプレートの、文字列値のマップです。locals が先に解決されるため、provides: のエントリはそれらを読み取り、解決済みの値を受け取ります。locals: ブロックが宣言していないキーを指定すると停止します。これは、アタッチメントが生成したもの(出力されたリソースの名前、生成されたデータキー、クラウド ID)を、コンシューマーが同じ入力からその ID を再導出することなく、コンシューマーに伝える手段です。
コンシューマーはこれを .features.<instance-name>.provides.<key>(クレデンシャルのアタッチメントの場合は .features.<slot>.provides.<key>)で読み取ります。これは uses エッジにおける .context.uses.<alias>.provides と対応しています。アタッチメントがコンシューマーの接続の 1 つに記述されている場合、コンシューマーは同じマップをその接続の下の .context.uses.<alias>.features.<slot>.provides.<key> で読み取り、そのアタッチメントは .features には含まれません(接続のアタッチメントを参照)。アタッチメント自身の inject: ブロックは、その from: 参照を同じマップに対して解決するため、作成者はどちらのチャネルも選択できます。テンプレートでの読み取りには provides、環境変数、ファイル、引数への受け渡しには inject を使います。
# FeatureRecipe: emits a ServiceAccount and publishes its name.provides: name: "{{ .infra.service_account_name }}"# Consuming Recipe: binds the pod to what the attachment published.workload: | serviceAccount: "{{ .features.identity.provides.name }}"この FeatureRecipe が implements する Feature が schema.provides コントラクトを宣言している場合、そのコントラクトは FeatureRecipe に対して強制されます。Feature が宣言するすべてのキーが FeatureRecipe の provides: に存在する必要があり、存在しない場合はビルドが欠落しているキーを示して停止します。追加の公開キーは許可されます。コントラクトは下限であり、上限ではありません。値が検査されることはありません。値はランタイムが解決する不透明で決定的なポインタです。
解決はアタッチメントごとに 1 回、コンシューマーのレンダリング前に行われ、同じ解決済みマップがコンシューマーの読み取り、コントラクトのチェック、アタッチメント自身の Resource Generation に供給されます。そのため、コンシューマーが読み取る内容とアタッチメントが出力する内容が食い違うことはありません。
Provider と implements
spec.capability は必須で、FeatureRecipe の出力をレンダリングする Wasm レンダリングプラグインを持つプロバイダー(helm、helm-chart、compose など)を指定します。その条件は Recipe の spec.capability と同じです(entities/recipe.md を参照)。バージョンの固定は、そのプラグインのどのバージョンでレンダリングするかを選択するもので、FeatureRecipe の名前の一部ではありません。Manifest は capability: "compose:1.2.3" を宣言する FeatureRecipe を compose/<name>:<version> としてマッピングし、名前に固定を書き込んだマッピング値は、何かが検索される前に不正なレシピ参照(E0095)として拒否されます。implements フィールドは FeatureRecipe をその Feature インターフェースに結び付け、完全一致、メジャー互換の範囲、またはバージョンなしのマッチングをサポートします。implements のバージョンマッチングのセマンティクスについては vocabulary/inheritance-and-interface を参照してください。
実行スコープ — spec.executionScope
省略可能な spec.executionScope 列挙型は、Resource Generation のディスパッチモデルを選択します。受け付ける値は 2 つで、フィールドを省略した場合のデフォルトは component です。
component(デフォルト)。 FeatureRecipe の Resource Generation は、アタッチされたコンポーネントインスタンスごとに 1 回実行されます。各呼び出しは.context.*をルートとするコンポーネントごとのテンプレートコンテキストを受け取ります:.context.instance_id、.context.inject、.context.uses、.context.annotationsなどです。そのvaluesMapping:、workload:、artifacts:は.context.used_byも読み取ります。これはusesエントリがホストを指しているコンポーネントで、それぞれの識別情報、ソケット、公開する内容、配置先の名前空間とバウンダリを含みます。ホスト自身がレンダリングするテンプレートからは、これらは見えません。boundary。 Resource Generation は、バウンダリのサブツリー内でいくつのコンポーネントがその feature を消費しているかにかかわらず、アタッチされたバウンダリごとに 1 回 実行されます。各呼び出しは.context.*の代わりに.boundary.*をルートとするバウンダリスコープのテンプレートコンテキストを受け取ります。
前述の injectMapping によるインターセプトは、executionScope にかかわらず 常にコンシューマーごと です。feature を使用する各コンポーネントは、引き続き .context.inject の呼び出し側での書き換えをそれぞれ個別に受けます。バウンダリスコープで重複排除されるのは、Resource Generation ステップ(source/valuesMapping と pipeline 配列)だけです。
したがって、バウンダリスコープの FeatureRecipe のテンプレートは 2 つのスコープで実行されます。 その injectMapping は、アタッチメントが到達する各コンポーネントに対して 1 回ずつ、そのコンポーネントのコンテキストに対して実行されます。これはコンポーネントスコープの FeatureRecipe の injectMapping が読み取るものと同じで、.context.*、.attachment_name、.features、およびアタッチメント自身の .values、.infra、.locals です。その .infra はバウンダリアタッチメントの infra: ブロックであり、その .locals はバウンダリに対して 1 回評価されたブロックです。それ以外に記述するすべてのテンプレート(locals:、provides:、source:、valuesMapping:、artifacts:、およびパイプラインステップの with: と when: を含む)は、後述のバウンダリスコープのコンテキストに対して、バウンダリにつき 1 回実行されます。各テンプレートは実行されるスコープに対してチェックされます。.context.instance_id を読み取る valuesMapping: はビルドを停止させ、それを読み取る injectMapping はそのコンポーネントの識別情報をレンダリングします。.boundary はどのコンポーネントのコンテキストにも設定されないため、FeatureRecipe の executionScope が何であれ、それを読み取る injectMapping は参照を示してビルドを停止させます。
バウンダリスコープのテンプレートコンテキスト
executionScope: boundary の場合、FeatureRecipe の injectMapping 以外のテンプレートは、feature がアタッチされたバウンダリの .boundary.* ビューに対して評価されます。このビューは次を公開します:
.boundary.path— feature がアタッチされた Release バウンダリのパスです。最も外側から内側へ向かうバウンダリ名を/で連結したものです(bridge、bridge/frontend)。これはバウンダリを指すもので、出力が書き込まれるディレクトリではありません。ディレクトリはdirectory:が設定します(.context.instance_idの代わり)。.boundary.assembly_path— ビルドの出力ディレクトリからの相対パスで、アタッチメント自身の出力がアセンブルされるディレクトリです。バウンダリの評価済みのdirectory:とsubDirectory:であり、ビルドがその出力をルーティングするディレクトリです(bridge/compose)。接続のエンドポイントが同じアセンブル済みファイルにレンダリングされる場合に限り、そのエンドポイントのsource_assembly_pathまたはtarget_assembly_pathと等しくなるため、FeatureRecipe はこれらを比較して、自身のファイル内の接続と別のファイルにある接続を区別します。.boundary.boundary_name— Release 内で記述されたバウンダリの名前。.boundary.components— インスタンス ID をキーとし、バウンダリのサブツリー内のすべてのコンポーネント(instance_id、component、resolved_version、boundary_path)を含むマップ。.boundary.internal_uses_edges— 両端点がこのバウンダリのサブツリー内にあるuses:エッジ(compose-bridge パターンはこれらを列挙し、両端点が自身の compose ファイルにアセンブルされ、かつそのファイルの異なるネットワーク上に配置されているエッジを残して、エッジごとのプロキシ設定を導出します)。各エッジは、端点の解決済み provides、注入された環境変数、および各端点の配置を持ちます:source_namespaceとtarget_namespace(その端点に適用されるaggrega.ai/namespaceアノテーションで、端点自身の Release エントリに設定があればそれ、なければそのバウンダリの設定)、source_boundary_pathとtarget_boundary_path(端点を含む Release バウンダリのパス)、そしてsource_assembly_pathとtarget_assembly_path(ビルドの出力ディレクトリ配下で、そのプロバイダーが端点をアセンブルするディレクトリ。バウンダリの評価済みのdirectory:とsubDirectory:から構成されます。bridge/compose)です。アセンブリパスが同じ 2 つの端点は 1 つのアセンブル済みファイルにレンダリングされ、名前空間が適用されない場合、compose プロバイダーはアセンブリパスをその端点のネットワークとして読み取ります。.boundary.outgoing_cross_boundary_uses_edges— ソースがサブツリー内にあり、ターゲットがサブツリー外にあるエッジ。.boundary.incoming_cross_boundary_uses_edges— ターゲットがサブツリー内にあり、ソースがサブツリー外にあるエッジ(イングレス型のアグリゲーターが使用します)。.boundary.cross_boundary_uses_edges— 受信と送信のバウンダリ間エッジの和集合。FeatureRecipe がバウンダリ間の全体ビューを必要とする場合に使います。.boundary.labels— 記述順を保持した、サブツリーのラベルの和集合。.boundary.annotations— バウンダリ自身のアノテーションとカスケード。.boundary.feature_attachments— このバウンダリにアタッチされたすべての feature(バウンダリスコープの FR が必要に応じて兄弟を調べられるようにするため)。
バウンダリスコープの FR における .infra ピラーは、バウンダリにアタッチされた feature の infra: ブロック(そのバウンダリのアタッチメントに対して Release 側で記述された物理的なサイジング)に解決されます。バウンダリスコープの FR では .values は 常に空 です。Release スキーマのピラー分割ルールが Release レベルの Feature アタッチメントでの values: を禁止しているため、バウンダリにアタッチされた feature には射影する値がありません。パラメーター形式のデータを必要とするバウンダリスコープの FR は、.infra(バウンダリ feature の設定に対するオペレーターの記述面)または .boundary.annotations(バウンダリまたはその祖先に記述された、カスケードで解決可能な文字列値)を通じてそれを消費します。.parameters はビューに含まれず、それを読み取るテンプレートはビューが定義するルートを示して停止します。.locals は引き続き FR 自身の locals ブロックです。.steps と .metadata は変わりません。
バウンダリスコープのテンプレートフィールド許可リスト
バウンダリスコープの FR は、injectMapping を除くすべてのテンプレートで、バウンダリスコープのビューで利用可能なフィールドのみを参照できます。executionScope: boundary のときにコンポーネントごと専用のフィールド(例: .context.instance_id、.context.inject、.context.uses)を参照するそのようなテンプレートを記述すると、FeatureRecipe はパース時に検証に失敗し、FR、問題のフィールド、およびバウンダリスコープのビューが定義するフィールドを示すエラーになります。逆方向にも同じルールが適用されます: .boundary.* フィールドを参照するコンポーネントスコープの FR は、同じバリデーターで失敗します。injectMapping は、どちらのスコープでも、それが実行されるコンポーネントのコンテキストに対してチェックされるため、.context.* を読み取ることができ、その中での .boundary への参照は、参照とそのコンテキストが定義するルートを示して停止します。
バリデーターは、パステンプレート変数の許可リストが使うものと同じテンプレート AST の走査を、スコープごとに異なる参照セットで実行します。
重複排除と Resource Generation の出力
executionScope: boundary の場合、コンパイラは Resource Generation をタプル (boundary_path, FR-instance) で重複排除します。同じバウンダリサブツリー内の 2 つのコンポーネントが同じバウンダリアタッチの feature を消費しても、FR の呼び出しは 2 回ではなく 1 回です。同じ feature のバウンダリをまたぐアタッチメントは、バウンダリごとに独立して実行されます。
バウンダリスコープの FR は、(boundary_path, FR-instance) タプルごとに中間でないファイルを 1 セット出力し、その配置先はプロバイダーがバウンダリの出力をどのように結合するかによって決まります。コンポーネントスコープのアタッチメントがコンポーネントも併せて持つのに対し、ここではインスタンス名だけが座標になります。バウンダリスコープの feature はどのコンポーネントでもなくバウンダリにアタッチされるため、囲んでいるバウンダリディレクトリがコンポーネントのセグメントが示す内容をすべてすでに表しており、名前を付けるコンポーネントもありません。
各ドキュメントをバウンダリディレクトリに直接書き込むプロバイダーは、そのターゲットがディレクトリ直下にあるファイルのみを読み取ることを宣言しています。したがって、アタッチメントを配置する囲みディレクトリはなく、インスタンス名は代わりにファイル名のプレフィックスになります: <boundary_directory>/<fr-provider>/<feature-instance>--<file> で、バウンダリ自身のファイルと並びます。ファイル名には頼れる区切り文字がないため、インスタンス名はエンコードされ、エンコードされた座標が含み得ない 2 文字の境界でファイル自身の名前とつながります。そのため、同じファイル名を出力する 2 つのアタッチメントも 2 つのファイルになります。
バウンダリの出力を囲み構造へと構成するプロバイダー(寄与者ごとのチャートを保持する 1 つのチャート、寄与者ごとのモジュールを保持する 1 つのルート設定など)は、すべての寄与者をそれぞれ専用のサブディレクトリに配置し、バウンダリアタッチメントも他と同様に 1 つの寄与者です。その出力は <boundary_directory>/<fr-provider>/<contributors-directory>/<feature-instance>/ に置かれます。ここで <contributors-directory> は、そのターゲットが子ユニットの配置場所を呼ぶ名前です。サブディレクトリはアタッチメントのインスタンス名、つまりバウンダリの features: ブロックで記述した名前を持つため、ビルドが生成するディレクトリは記述した内容から見つけられます。
中間出力は、FR の評価済みパスで、FR 自身の spec.capability のもと、バウンダリの (パス, プロバイダー) ごとのアセンブラーに流れます。これは、core/compose-bridge Feature が、同じアセンブリパスでコンポーネントごとの compose 寄与者と並べてブリッジサービスをマージするために使う仕組みです。このような出力は、そこでバウンダリのコンポーネントからアセンブルされるファイルの一部としてのみ書き込まれます。そのため、いずれのコンポーネントもそのパスに到達しない場合(たとえば、すべてのコンポーネントが subDirectory: によって別の場所に送られる場合)、ビルドは出力をどこにも書き込まないのではなく、バウンダリ、Feature、出力のルーティング先のパス、およびプロバイダーを示して停止します(fatal-halts.md の「A boundary-level Feature’s output reaches no assembled file(バウンダリレベルの Feature の出力がどのアセンブル済みファイルにも到達しない)」を参照)。
カスケードを考慮した provides: の解決
boundary スコープの FR は、(boundary_path, FR-instance) のタプルごとに 1 つの provides: セットを生成し、それを 1 回評価します。FR の provides: テンプレートは boundary スコープのテンプレートコンテキストで評価されます(そのため .boundary.components、.boundary.path、.infra は参照できますが、コンシューマごとのフィールドや .values は参照できません)。provides の値はコンシューマに対して定数です。boundary のサブツリー内のすべてのコンシューマが同じ提供値を参照します。
boundary スコープの FR の provides のコンシューマ側での解決は、どこでもその 1 回の評価を読み取ります。アタッチメントが到達する各コンポーネントは、.features.<instance-name>.provides.<key> でそれを読み取ります。自身の Recipe のテンプレートでも、そのコンポーネントのコンテキストで実行される FeatureRecipe 自身の injectMapping でも同じです。アタッチメントが持つ uses エッジを通じて .context.uses.<feature-alias>.provides.<provided-name> で読み取るコンシューマの Component も同じ値を得ます。コンパイラはそれを、コンシューマが置かれている boundary に対する boundary スコープの FeatureRecipe の provides: に解決し、アタッチメントごとの feature インスタンスの識別情報を持つコンシューマの uses エッジから、boundary スコープの FR の provides: までたどります。コンシューマのアセンブリの前にプレパスがそれらの provides を評価するため、コンシューマのパイプが構築される時点で値が存在します。
コンシューマごとの効果は、injectMapping が読み取る provides: 内のテーブルです。 コンシューマごとに何かを変更する必要があるバウンダリスコープの FeatureRecipe は、バウンダリの接続から、コンシューマをキーとするテーブルを provides: で 1 回計算し、その injectMapping が現在のコンポーネントの行(.context.instance_id をキーとする (index .features .attachment_name).provides)を読み取り、すべてのマッピングが従うルールのもとで、コンシューマ自身のパイプを通じてそれらを配信します(マッピングが書き換えられるものを参照)。コンパイラは FeatureRecipe が書いたテーブルを受け渡すだけで、その中身は何も読み取りません。
compose-bridge パターン
compose-bridge の FeatureRecipe は、バウンダリスコープの FR の代表的なパターンであり、上記の仕組みで記述されたカタログコンテンツです。コンパイラも compose プロバイダーもブリッジのロジックを一切持たないため、カタログは core/compose-bridge Feature を別の方法で実現できます。core/compose-bridge feature は、directory: を共有する 2 つのサブバウンダリ(例: services-net と data-net)を含む親バウンダリにアタッチされます。各サブバウンダリはそれぞれ独自の aggrega.ai/namespace アノテーション(aggrega.ai/namespace: services-net、aggrega.ai/namespace: data-net)を持ち、それぞれが独自のネットワークに配置されます。アノテーションがない場合、両者は compose ファイルのパスにちなんで名付けられた 1 つのネットワークを共有し、ブリッジなしで互いに到達します。その executionScope: boundary により、FR は親バウンダリのアタッチメントごとに 1 回実行されます。
その provides: はブリッジテーブルを 1 回計算します。 .boundary.internal_uses_edges から、両端点が自身の compose ファイルにアセンブルされ(source_assembly_path と target_assembly_path がどちらも .boundary.assembly_path に等しい)、かつそのファイルの異なるネットワーク上にあるエッジを残します。端点のネットワークは、その aggrega.ai/namespace、なければそのアセンブリパスです。2 つの compose ファイルの間のエッジはブリッジされず、そのコンシューマはターゲット自身の名前を保持します。ブリッジされる各エッジには、listen ポート(ターゲット自身のポート。先行するエッジがすでにそのポートで listen している場合は、アタッチメントの portBase(デフォルト 10000)以上で最初に空いているポート)と、アップストリーム(ターゲットが公開するホスト、つまりアタッチメントの providesField が指定する provides フィールド(デフォルト host)と、その port)が割り当てられます。アップストリームはエッジから導出され、手作業で書かれることはありません。同じテーブルから各コンシューマの書き換えも計算します。エッジがホストフィールドから配信する変数は aggrega-gw:<listen port> になります。同じエッジが port からも変数を配信する場合、ホストの変数は aggrega-gw になり、ポートの変数が listen ポートになります。
その injectMapping は各コンシューマの行を配信します。 各コンシューマのコンテキストで実行され、.features.<attachment>.provides にあるテーブルのうちそのコンシューマの行を読み取り、コンシューマ自身の接続が配信した値(例: DB_HOST)の上にそれらを配信します。これはインターセプションです。行を持たないコンシューマは何も受け取りません。コンシューマにアタッチされた別の Feature がそのキーを配信していた場合(その inject: ブロックまたはその injectMapping を通じて)、ビルドはその配信を置き換えるのではなく、両方の Features を名指しして停止します(fatal-halts.md の「Two attached Features deliver one key, the later through its FeatureRecipe’s injectMapping(アタッチされた 2 つの Features が 1 つのキーを配信しており、後者はその FeatureRecipe の injectMapping を通じている)」を参照)。ゲートウェイの listen とコンシューマの書き換えは1 つのテーブルから読み取られるため、portBase で再割り当てされた衝突も含め、構造上エッジごとに一致します。
その valuesMapping はゲートウェイを記述します。 FeatureRecipe 自身の compose フラグメントが aggrega-gw サービスを宣言します。何かがブリッジされる場合、その valuesMapping はブリッジされるエッジごとに nginx の stream server ブロックを 1 つ追加し(listen <port>; set $uN <target-host>:<target-port>; proxy_pass $uN;。各アップストリームが起動時に 1 度ではなく接続時に解決されるよう resolver ディレクティブの下に置かれます。これらの変数の $ は $$ と書かれ、Docker Compose の $ 補間が nginx 用にリテラルの $ を残します)、マウントされた compose config として配信します。これはインラインの content: を持つトップレベルの configs: エントリで、aggrega-gw から参照され、/etc/nginx/nginx.conf にマウントされます(そのため nginx は記述された command: なしでそれを読み込みます)。インラインの configs.content には Docker Compose ≥ 2.23.1 が必要です。また、ゲートウェイの x-aggrega-networks-of の下にブリッジされるすべての端点を指定し、compose プロバイダーがそれをそれらの端点が配置されているネットワークに解決するため、ゲートウェイはブリッジされたエッジがまたがるすべてのネットワーク(コンシューマのネットワークとターゲットのネットワーク)に参加します。実行時にコンシューマは aggrega-gw:<port> に到達でき、ゲートウェイはターゲットへ proxy_pass できます。何もブリッジされない場合でも、フラグメントが宣言するゲートウェイはアイドル状態でレンダリングされます。設定も追加のネットワークも書き換えもありません。
(パス, プロバイダー) ごとの compose アセンブラーは、同じ評価済みパスでゲートウェイをコンポーネントごとのコントリビューターと並べてマージします。結果は、すべてのコンポーネントとブリッジゲートウェイを含む 1 つの docker-compose.yaml です。バウンダリのどのコンポーネントもゲートウェイのファイルにアセンブルされない場合、ビルドはゲートウェイをどこにも書き込まないのではなく停止します。アップストリームはコンパイル時に決定的な compose サービスへのポインタであり、compose の実行時 DNS がそれを解決します(コンパイル時の実行時解決は行いません)。
呼び出し元の後にレンダリングする — spec.readsCallerRenderFacts
省略可能な spec.readsCallerRenderFacts(真偽値、既定値 false)は、この FeatureRecipe のテンプレートが、ホストに接続するコンポーネントがレンダリングした内容、すなわちそれら呼び出し元それぞれのプロバイダが出力について報告するレンダーファクトを読むことを宣言します。プロバイダが何を、どの名前で報告するかはそのプロバイダ自身の契約です。プロバイダが報告できるファクトについては Reporting facts about what a guest emitted で説明しています。
このようなアタッチメントがレンダリングされるタイミング。 ビルドはコンポーネントを固定の順序で 1 つずつレンダリングし、アタッチメントは通常、アタッチ先のコンポーネントの直後にレンダリングされます。ホストに接続し、その順序で後に来るコンポーネントはその時点ではまだレンダリングされていないため、読み取れる出力が存在しません。FeatureRecipe が readsCallerRenderFacts: true を設定するアタッチメントは、代わりにビルド内のすべてのコンポーネントがレンダリングされた後、このキーも readsTargetRenderFacts も設定しないすべてのアタッチメントと共にレンダリングされます。そのため、アタッチメントが評価される前に各呼び出し元のレンダリングは完了しています。出力は本来の場所に同じ名前で配置されます。このキーが変えるのはアタッチメントがレンダリングされるタイミングであり、レンダリングされる内容ではありません。後からのレンダリングにより、順序が 1 つ変わります。FeatureRecipe がホストコンポーネントのドキュメントを書き換える pipeline を持ち、ホストのプロバイダが個別のドキュメントを書き出す場合、それらのステップはアタッチ順ではなく、ホストの他のアタッチメントのパイプラインの後に実行されます。
読み取る内容。 キーを設定すると、.context.used_by の各エントリが .render_facts を持ちます。これはファクト名をキーとする呼び出し元のレンダーファクトです。すべてのレンダーファクトはリストなので、エントリが 1 つだけの場合でも、テンプレートは常にそれを range で反復します。 エントリは呼び出し元自身のレンダリングと、呼び出し元にアタッチされた Features のレンダリングから得られます。1 つの名前についてそれぞれから得られたリストは 1 つに結合され、呼び出し元自身のプロバイダ呼び出しが先に、その後に各 Feature がレンダリングされた順に並びます。呼び出し元の Feature のうち自身もこのキーを設定するものは、すべてのコンポーネントの後にレンダリングされるため、その報告内容はここに含まれません。プロバイダが何も報告しない呼び出し元は空の .render_facts を持つため、誰も報告していない名前は何もない値として読まれます。
artifacts: callers.yaml: | callers: {{- range .context.used_by }} - component: {{ .component_id }} ports: {{- range .render_facts.ports }} - {{ .port }} {{- end }} {{- end }}どのファクト名が存在し、各エントリが何を保持するかは、呼び出し元のプロバイダが文書化した契約です。たとえば helm プロバイダの場合はその render facts で、レンダリングした Pod のラベルを示します。呼び出し元のファクトは、FeatureRecipe の valuesMapping:、workload:、artifacts: が読む接続上にあります。pipeline: ステップの with: と when: はホストに接続するコンポーネントをまったく参照しないため、ステップが読むのはホスト自身のファクトのみです。コンポーネントにアタッチされたすべての FeatureRecipe は、キーを設定するかどうかにかかわらず、同じ形でコンポーネント自身のファクトを .context.render_facts で読みます。両方についてはテンプレートコンテキストで説明しています。
テンプレートがファクトを読むときは必ず宣言してください。 キーを設定しない FeatureRecipe にインラインで書かれたテンプレート(valuesMapping:、workload:、または artifacts: のエントリ)が .context.used_by の下の render_facts を読むと、何もレンダリングされる前にビルドが停止し、その参照と記述されたフィールドが示されます(fatal-halts.md の「A template reads its callers’ render facts without declaring it(テンプレートが宣言なしに呼び出し元のレンダーファクトを読んでいます)」を参照)。このチェックは記述どおりのテンプレートを読むため、テンプレートの実行中に構築される参照や、ファイルやライブラリからインポートされたコンテンツに書かれた参照は検出しません。また、.context.used_by と並んで他のリストから render_facts という名前のフィールドを読むテンプレートや、それと並んで {{ with .context }} の中でホスト自身のファクトを .render_facts として読むテンプレートは、呼び出し元のファクトを読んでいるものとして扱われます。ホスト自身のファクトは .context.render_facts と完全に記述してください。アタッチメントがレンダリングされるタイミングを決めるのはチェックではなくキーです。そのため、テンプレートが呼び出し元のレンダーファクトを読むすべての FeatureRecipe に、読み方にかかわらずこのキーを設定してください。設定のコストは後からのレンダリングだけです。
パイプラインステップが読むのはホスト自身のファクトのみです。 ステップはホストコンポーネント自身のドキュメントを書き換えることがあり、コンポーネント自身の出力は誰が接続しても変わりません。そのため、ステップの with: と when: は、FeatureRecipe がキーを設定するかどうかにかかわらず、ホストに接続するコンポーネントを参照しません。キーが決めるのはアタッチメントのレンダリングのタイミングであり、ステップが参照する内容には関係しません。したがって、インラインで書かれたステップの with: または when: が .context.used_by の下の render_facts を読むと、空の値をレンダリングする代わりに、何もレンダリングされる前に短いコード E0326 でビルドが停止し、その参照とステップのフィールドが示されます。ステップではホスト自身のファクトを .context.render_facts と完全に記述して読み、呼び出し元のファクトは FeatureRecipe の valuesMapping:、workload:、artifacts: で読んでください。このチェックは記述どおりのテンプレートを読み、上記のチェックと同じ制限があります。
スコープ。 このキーは、コンポーネントごとに 1 回レンダリングされる FeatureRecipe(既定値の executionScope: component)に適用されます。executionScope: boundary を宣言する FeatureRecipe は、キーを設定するかどうかにかかわらず常に同じ場所でレンダリングされ、そのリソースを生成するテンプレートは .context ではなく .boundary を読み取ります。
ターゲットの後にレンダリングする — spec.readsTargetRenderFacts
省略可能な spec.readsTargetRenderFacts(boolean、デフォルトは false)は、この FeatureRecipe のテンプレートが、ホストの接続先のコンポーネントがレンダリングしたもの、つまり各ターゲットのプロバイダーが出力について報告するレンダーファクトを読むことを宣言します。これは readsCallerRenderFacts とは接続の反対側を読みます。つまり、uses エントリがホストを指すコンポーネントではなく、ホストの uses エントリが指すコンポーネントを読みます。ファクト自体については、すべて同じように読めます。
どちらのキーでも、アタッチメントはすべてのコンポーネントの後にレンダリングされます。 FeatureRecipe が readsCallerRenderFacts: true、readsTargetRenderFacts: true、またはその両方を設定しているアタッチメントは、前のセクションで説明したとおり、ビルド内のすべてのコンポーネントがレンダリングされた後にレンダリングされます。この後続のレンダリングは 1 回であり、アタッチメントの出力の配置先やパイプラインステップの順序に与える影響は、どちらのキーによってアタッチメントが移動したかにかかわらず同じです。2 つのキーの違いは、アタッチメントのコンテキスト上でどの接続がファクトを持つかだけです。ビルドの順序でホストより後にあるターゲットもその時点ではレンダリング済みなので、それが出力したものを読めます。
読み取る内容。 キーを設定すると、.context.uses の各エントリは .render_facts を持ちます。これはターゲットのレンダーファクトで、ファクト名をキーとし、呼び出し元のエントリと同じ形をしています。すべてのレンダーファクトはリストなので、テンプレートは常にそれを range で反復します。そのエントリは、ターゲット自身のレンダリングと、ターゲットにアタッチされた Features のレンダリングから得られます。ターゲット自身のプロバイダー呼び出しが先で、その後に各 Features がレンダリングされた順に続きます。ターゲットの Feature のうち、それ自体がすべてのコンポーネントの後にレンダリングされるものは含まれません。プロバイダーが何も報告しないターゲットは、空の .render_facts を持ちます。テンプレートは、1 つの接続のファクトをそのエイリアスの下の .context.uses.<alias>.render_facts.<name> で読むか、各接続のファクトを順に読みます。
artifacts: targets.yaml: | targets: {{- range .context.uses }} - component: {{ .target }} ports: {{- range .render_facts.ports }} - {{ .port }} {{- end }} {{- end }}キーを設定しない FeatureRecipe は、ほかに何を設定していても、どの接続にも .render_facts を見ません。どのファクト名が存在するかは、各ターゲットのプロバイダーが文書化した契約です。たとえば helm プロバイダーのものはそのレンダーファクトで、レンダリングした Pod のラベル、コントローラーセレクター、コンテナポートを示します。これは、egress ポリシーがホストの到達できる Pod を正確に選択するために必要なものです。
テンプレートがファクトを読むときは必ず宣言してください。 キーを設定しない FeatureRecipe にインラインで書かれたテンプレート(valuesMapping:、workload:、または artifacts: エントリ)が .context.uses の下の render_facts を読むと、何もレンダリングされる前に、短いコード E0347 でビルドが停止し、参照とそれが書かれたフィールドが示されます(fatal-halts.md の「A template reads its targets’ render facts without declaring it(テンプレートが宣言せずにターゲットのレンダーファクトを読んでいます)」を参照)。readsCallerRenderFacts を設定してもこれは解消されません。このチェックは書かれたとおりのテンプレートを読み、呼び出し元のチェックと同じ制限があります。テンプレートの実行中に組み立てられた参照や、ファイルやライブラリからインポートされた内容に書かれた参照は検出しません。また、.context.uses を少しでも読み、かつ別の値({{ range .context.used_by }} 内の呼び出し元のエントリを含む)から render_facts という名前のフィールドを読むテンプレートは、ターゲットのファクトを読んでいるものとして扱われます。両端のファクトを読むテンプレートは、両方のキーを設定します。
パイプラインステップはホスト自身のファクトだけを読みます。 ステップの with: と when: は、ホスト自身の Recipe が読むのと同じようにホストの接続を読み、FeatureRecipe がキーを設定しているかどうかにかかわらず、ターゲットのレンダーファクトは決して読みません。ステップはホストコンポーネント自身のドキュメントを書き換えることがあり、ホスト自身のレンダリングはターゲットが公開するものを読み、ターゲットが出力したものは読みません。そのため、インラインで書かれたステップの with: や when: が .context.uses の下の render_facts を読むと、空の値をレンダリングするのではなく、何もレンダリングされる前に短いコード E0348 でビルドが停止し、参照とステップのフィールドが示されます。ターゲットのファクトは、FeatureRecipe の valuesMapping:、workload:、または artifacts: で読んでください。
スコープ。 呼び出し元のキーと同様に、コンポーネントごとに 1 回レンダリングされる FeatureRecipe に適用されます。executionScope: boundary を宣言する FeatureRecipe は、キーを設定しているかどうかにかかわらず常に同じ位置でレンダリングされ、.boundary の下で読む接続はレンダーファクトを持ちません。
locals: ブロック
FeatureRecipe.spec.locals: は省略可能な名前付き Go テンプレート文字列のマップで、そのレンダリング結果は同じ FeatureRecipe 内の他のすべてのテンプレートに .locals.* マップとして公開されます。これは Recipe の locals: に相当する FeatureRecipe 専用の仕組みで、派生文字列を一度だけ計算し、再計算せずに injectMapping、valuesMapping、pipeline[].with、provides から参照するための場所です。FeatureRecipe の assertions: はこれらを読み取りません。assertions-block.md に記載のとおり、アサーションの .locals はホストコンポーネントの Recipe のものです。各エントリのレンダリング結果は、先頭と末尾の空白を取り除いて格納されます。このブロックはマップであり、単一のテンプレート本体ではありません。この位置にスカラーを書くとスキーマで拒否されます。
apiVersion: aggrega.ai/v1beta1kind: FeatureRecipemetadata: name: regional-routerspec: implements: core/regional-router:^1.0.0 capability: helm locals: region_prefix: "{{ .infra.region | lower }}" fqdn_suffix: "{{ printf \"%s.svc.cluster.local\" .infra.namespace }}" injectMapping: | env: "{{ .infra.target_var }}": "{{ .locals.region_prefix }}.{{ .infra.target_var | lower }}.{{ .locals.fqdn_suffix }}".locals.* は呼び出しごとのものです。各 FR の呼び出しはそれぞれ自身の locals: ブロックを解決し、その結果はその呼び出しの後続テンプレートにのみ見えます。このブロックは FR の他のオーサリング面のテンプレートが評価される前に解決されるため、それらはすべて解決済みの値を参照します。
各エントリは自己完結したコンテキストに対して評価されます。.context.instance_id、.context.rendered_name、.attachment_name、.values、.infra、および同じブロック内ですでに解決済みのエントリです。これは FR の他のテンプレートが読むコンテキストより意図的に狭くなっています。locals: のエントリは .context.annotations、.context.inject、.context.uses、.provides に到達できず、これらのいずれかを参照すると、その参照を示して停止します。これらのピラーを必要とする派生値は、locals: ではなく、それらを読むテンプレートに置きます。
このコンテキストの名前はそれぞれ異なる問いに答えるもので、locals: のエントリは FeatureRecipe の他のテンプレートとまったく同じようにそれらを読みます。
.context.instance_idは、アタッチメントの解決対象であるホストコンポーネントです。コンパイラが評価するすべてのテンプレート面でホストコンポーネントを意味するため、どのエンティティのブロックを書いていても同じ参照は同じように読まれます。.context.rendered_nameは、ホストコンポーネント自身のプロバイダーが報告するホストコンポーネントの名前です。helmでは release 名であり、ホストの ID を Kubernetes の名前が許容する文字で表したものです。ホストのプロバイダーが名前を報告する場合にのみ存在し、名前を報告しないプロバイダーのホストでこれを読むとビルドが停止します。.attachment_nameは、解決中のアタッチメントインスタンスです。所有エンティティのfeaturesSchemaで埋めるスロット、または付けた自由な名前です。
したがって、出力するリソースの名前を導出する locals: エントリは、artifacts: テンプレートと同様に、ホストとアタッチメントを組み合わせます。
spec: locals: scrape_name: "{{ .context.instance_id }}-{{ .attachment_name }}" # api-scrape_target名前がプラットフォームの受け付けるものである必要があり、かつホストのプロバイダーが名前を報告する場合は、代わりに .context.rendered_name から組み立てます。helm 下の my_api という名前のホストとアタッチメント scrape では、{{ .context.rendered_name }}-{{ .attachment_name }} は my-zuapi-scrape になります。ID を使うと my_api-scrape となり、Kubernetes の名前としては拒否されます。レンダリングされたリソースの命名を参照してください。
locals: エントリ内の .values と .infra は、ホストコンポーネントのものではなく、アタッチメント宣言に記述されたアタッチメント自身のピラーです。
記述順序には意味がある
エントリは記述された順に解決され、エントリはその上で定義された兄弟エントリを読むことができ、その兄弟の解決済みの値を受け取ります。
spec: locals: region_prefix: "{{ .infra.region | lower }}" # defined first bucket: "{{ .locals.region_prefix }}-artifacts" # reads the entry above連鎖は下方向にのみ進みます。あるエントリが別のエントリを読む場合、エントリの順序がビルドの成否を決めます。region_prefix を bucket の下に移すとビルドは停止します。コンパイラは参照を解決するためにブロックを並べ替えることはないため、locals: ブロックの並べ替えは見た目上の変更ではなく、動作の変更です。
ブロックが後で定義するエントリへの参照は、順序の誤りを示して停止します(定義をそれを読む箇所より上に移してください)。ブロックがまったく宣言していないキーへの参照は、そのキーを示して停止します(綴りを修正してください)。このチェックはブロックの別名をたどります。 with .locals の本体が再束縛するドット、または .locals に束縛された変数を通じて到達するキーは、直接の記述とまったく同じ条件で停止し、括弧で囲んだブロックから読むキー({{ (.locals).nope }} または {{ ($.locals).nope }})も同様です。これを逃れる記述は1つだけです。テンプレートのテキストが名前を特定できない結果を返す呼び出しを通じて到達するキー({{ index .locals "nope" }} または {{ (default dict .locals).nope }})です。そのような呼び出しの結果から読むフィールドは停止せず、リテラルテキスト <no value> をレンダリングします。index による読み取りはキーを示して停止します。index は、読むマップがそのキーを保持していない場合、すべてのテンプレート面で停止するためです。errors/fatal-halts.md の「A template indexes a map with a key the map does not hold(テンプレートがマップの保持しないキーでマップをインデックス参照している)」を参照してください。provides: は完全に解決されたブロックを読みます。この FeatureRecipe の locals はその provides より前に解決されるためです。宣言されていないキーを指定する provides: テンプレートは停止します。これらは Recipe の locals: ブロックが従うのと同じ規則です。entities/recipe.md の「locals: ブロック」を参照してください。
スコープごとの動作。 executionScope: component(デフォルト)では、locals: はアタッチされたコンポーネントインスタンスごとに、上記の自己完結したコンテキストに対して評価されます。executionScope: boundary では、locals: はバウンダリのアタッチメントごとに、.boundary.* をルートとするバウンダリスコープのビューに対して評価されます。FeatureRecipe はコンポーネントごとに一度ではなくバウンダリに対して一度実行されるため、コンポーネントごとのフィールド(.context.instance_id、.context.inject、.context.uses)と .attachment_name は利用できません。バウンダリスコープのテンプレートフィールド許可リストは、FR の他のオーサリング面のテンプレートと同じように locals: にも適用されます。アタッチメントが到達する各コンポーネントに対して実行される injectMapping は、その 1 回のバウンダリ評価を自身の .locals として読み取ります。評価の契約(記述順序、下方向のみの兄弟の読み取り、2種類の停止)はどちらのスコープでも同一で、異なるのは周囲のコンテキストの形だけです。
injectMapping のオーバーレイおよび pipeline[].with のマッピングとの違い。 locals: は後続テンプレートのためにコンテキストから見えるマップを生成するもので、出力には寄与しません。injectMapping はコンシューマーの .context.inject パイプに書き込みます(呼び出し側の変更)。pipeline[].with は Wasm プラグインの args ペイロードを供給します。この3つの面は互いに独立しており、FeatureRecipe は通常3つすべてを併用し、locals: が他の2つが参照する共有の派生文字列を保持します。
assertions: ブロック
FeatureRecipe.spec.assertions: は、FeatureRecipe の実装上の不変条件を表す名前付きルールの省略可能なマップです。これは、FeatureRecipe が基盤とする特定の Wasm プラグインパイプライン、チャート、またはメカニズムを前提として成り立つフィールド横断のルールです。各キーは失敗メッセージに表示されるルール識別子であり、各値は Go テンプレートの本体です。Recipe のアサーションと同様に、FeatureRecipe のアサーションは特定の実装の性質です。Feature レベルの契約ルールは、それより前のパイプラインフェーズで独立して適用されます。
spec: implements: core/referenced-secret:^1.0.0 pipeline: - id: fetch_secret plugin: pipeline-step/aws-secrets-manager:1.2.0 function: step assertions: # aws-secrets-manager plugin 1.x requires an explicit region when none is # implied through the Aggregate's infra block. region-supplied-for-secrets-manager: | {{- if not .values.region -}} {{- if not .infra.aws.region -}} {{- fail "aws-secrets-manager plugin 1.x requires either values.region or infra.aws.region to be set" -}} {{- end -}} {{- end -}}上記のルールは aws-secrets-manager プラグイン 1.x に固有のものであり、別の core/referenced-secret FeatureRecipe がバインドされる場合には適用されません。Feature 定義に由来する Feature レベルの契約ルールは、引き続き併せて適用されます。
FeatureRecipe のアサーションは、FeatureRecipe のバインド後、リソース生成の前に評価されます。コンポーネントスコープの FR のテンプレートコンテキストは Recipe のアサーションのコンテキスト(エンティティインスタンスのフィールドに加えて .provides、.locals、.recipe.metadata、.recipe.source)と同じです。境界スコープの FR(executionScope: boundary)では、アサーションは境界スコープのビューに対して評価されます(.boundary.* フィールドは利用でき、コンポーネントごとのフィールドは利用できません)。記述文法の全体と実例については、templates/assertions-block.md を参照してください。
omits: フィールド — レンダリングされたドキュメントをソースから除外する
ほとんどの FeatureRecipes ではこれは必要ありません。これは、source: がそのまま利用するチャート(多くの場合レジストリから取得したもの)であり、そのチャートがアタッチメントが出力してはならないドキュメントをレンダリングする FeatureRecipe のためのものです。たとえば、レンダリングのたびにチャートが新たに生成する Secret や、ホストのコンポーネントやオペレーターがすでに提供しているオブジェクトなどです。omits: は、そのようなドキュメントを FeatureRecipe が生成するものから除外します。FeatureRecipe がソースとする compose ファイルの場合はアタッチメントが寄与してはならない service、volume、config を、ソースとする CloudFormation テンプレートの場合は resource を除外します。
spec: capability: helm implements: core/observability/collector:1.0.0 source: kind: helm-oci-chart url: oci://registry.example.com/charts/collector version: "0.9.1" omits: # The collector chart ships its own ServiceAccount; the host supplies one. - kind: ServiceAccount name: collector - when: "{{ .infra.without_dashboards }}" kind: ConfigMap name: collector-dashboardsこのキーは Recipe でも同じように記述し、Recipe → omits: フィールドがその完全なリファレンスです。各エントリのフィールドが何を選択するか、when: が最初に評価され false の場合はそのエントリが除外されること、適用されるすべてのエントリは何かを除外しなければならず、そうでなければそのエントリを示してビルドが停止すること、ソースは引き続き完全にレンダリングされ、その出力だけがフィルタリングされること、そしてどのプロバイダーがこのキーに従うかが説明されています。FeatureRecipe で異なるのは、テンプレートが評価される場所だけです。
- 各エントリのテンプレートは、この FeatureRecipe の
valuesMapping:が評価されるのと同じコンテキストに対して評価されます。スコープはexecutionScopeが選択するものです。コンポーネントスコープの FeatureRecipe のエントリはアタッチメントごとに 1 回、そのアタッチメントの.valuesと.infraに対して評価されます。境界スコープのものは境界ごとに 1 回、境界スコープのビューと境界アタッチメントの.infraに対して評価されます。アタッチメントのテンプレートが読み取れるものに関する規則は、valuesMapping:に適用されるのと同様にエントリにも適用されます。 - フィルタリングされるのは、この FeatureRecipe 自身の
source:がレンダリングするものだけです。 そのworkload:とartifacts:はフィルタリングされず、ホストのコンポーネントの出力もフィルタリングされません。アタッチメントのエントリが及ぶのは、そのアタッチメント自身のチャート、compose ファイル、CloudFormation テンプレートだけです。両者がまとめられるdocker-compose.yamlでホストが同じキーで宣言する compose service は変更されず、両者がまとめられるスタックでホストが同じ論理 ID で宣言する resource も同様です。ホストがレンダリングするドキュメントを変更するには、ホストの Recipe がエントリを宣言するか、pipeline:ステップでパッチを当てます。
エントリによる停止では、ノード、プロバイダー、この FeatureRecipe、および omits: リスト内でのエントリの位置が示されます。境界スコープの FeatureRecipe の場合は、メッセージの上の行にアタッチメントとその境界が示されます。
Recipe で記述したこのキーの実例(取得したチャートが生成する Secret の除外、およびエントリがない場合と何にも一致しないエントリがある場合の停止)については、ai-gateway-own-webhook-certificate を参照してください。