パステンプレート変数
Release バウンダリの directory: フィールドと subDirectory: フィールドは、ビルド時に評価される Go テンプレートです。これらは、レンダリングされたアーティファクトがディスク上のどこに配置されるかを制御し、ひいてはどのアーティファクトがまとめてアセンブルされるかを決定します。同じ (path, provider) タプルに評価される 2 つのバウンダリはアセンブラを共有し、マージされた 1 つの出力(1 つの Chart.yaml、1 つの docker-compose.yaml)を生成します。このページは、これらのテンプレートが参照できる変数、厳格な評価セマンティクス、およびバウンダリが親から継承できるようにするカスケード規則についてのオーサリングリファレンスです。
空間的な分離と (path, provider) ごとのディスパッチの概念的な解説については、architecture/16-recipe-input-composition.md を参照してください。エンティティレベルでの Release のオーサリングについては、entities/release.md を参照してください。プロバイダー側への影響については、providers/architecture.md および各プロバイダーのページで説明しています。
厳密な評価: missingkey=error
パステンプレートは Go の missingkey=error モードで評価されます。宣言されていないフィールドへの参照、設定されていない parameters.X キーへの参照、あるいは {{ .parmaeters.region }} のようなタイプミスは、空文字列を黙ってパスに出力するのではなく、明示的なエラーになります。
この厳密さは、コンパイラの他の部分とは非対称です。valuesMapping、injectMapping、その他の値レンダリング箇所は、Helm/Sprig の慣例に従って missingkey=zero を使用します。パスの出力は構造的に異なります。空文字列を生成する値レンダリングテンプレートはマニフェストのフィールドに出力され、その影響は限定的です。一方、空文字列を生成するパステンプレートはディレクトリレイアウトに出力され、その影響は限定されません(衝突、アセンブリの破損、存在しないはずのパス)。厳密なパステンプレートの仕組みは、こうした失敗をデプロイ時ではなくビルド時に表面化させるために存在します。
パース時の許可リスト検証
実行時の厳格さに加えて、パステンプレートはパース時に、閉じた変数名の許可リストに対して検証されます。許可リストにない変数名を参照すると、レンダリング処理が始まる前にビルドが停止し、問題のあるフィールドとそれが現れる境界を示す診断が出力されます。
許可リストは設計上閉じています。.context.inject、.values、.locals などのサーフェスは、意図的にパステンプレートに公開されていません。パスの出力は構造上の関心事であり、値のレンダリングの関心事ではありません。アセンブリのパスをコンポーネントごとの値に結び付けると、パスのグラフがデータに依存するようになり、決定論的な出力という不変条件が損なわれます。
変数マトリクス
| 変数 | directory: | subDirectory: | 説明 |
|---|---|---|---|
{{ .capability }} | はい | はい | このパスに出力されるアーティファクトについて、寄与するコンポーネントの Recipe が宣言するレンダリング機能(helm、helm-chart、compose、terraform、cloudformation)。 |
{{ .boundary_name }} | はい | はい | Release 内で記述されたバウンダリの名前(例: production、eu-prod)。 |
{{ .parameters.X }} | はい | はい | Aggregate で宣言され、Release によって充足される任意の型付きパラメータ。厳格なアクセスで、.parameters.unknown を参照するとビルドが停止します。 |
{{ .manifest.recipe_name }} | はい | はい | 寄与するコンポーネントについて Manifest を通じて解決された Recipe 名。Recipe ごとのアーティファクトを Recipe ごとのサブフォルダに振り分けるのに便利です。 |
{{ .parent_boundary.* }} | はい | はい | 外側のバウンダリの評価済みの値へのカスケードアクセス。後述の親バウンダリのカスケードを参照してください。 |
{{ .component_id }} | — | はい | 寄与するコンポーネントのインスタンス ID。境界にアタッチされ、その FeatureRecipe が境界ごとに 1 回実行される(executionScope: boundary)Feature の場合は、そのアタッチメントのリソースが aggrega.ai/component-id ラベルに持つ合成 ID です — 境界 app のアタッチメント shared なら bfr--app--shared で、アタッチメントのプロバイダーが名前の長さを制限する場合は短縮されます — そのため、アタッチメントの出力はそのラベルにちなんだ名前のディレクトリに置かれます。directory: は境界ごとのプロパティであるため、subDirectory: でのみ使用できます — ディレクトリ文字列は、コンポーネントごとのルーティングが行われる前に、境界ごとに 1 回計算されます。 |
directory: フィールドのデフォルトは、boundaries/ の後にバウンダリパス(バウンダリツリーから導出される、ビルド時に安定した識別子)を続けたものです。バウンダリを宣言せずにコンポーネントを列挙する Release は、ディレクトリセグメントを一切付けずにそれらを書き出します。subDirectory: フィールドのデフォルトは {{ .capability }} であり、各機能のアーティファクトはバウンダリのディレクトリ配下にある専用のサブフォルダに配置されます。これは省略した場合も、subDirectory: "" と記述した場合も同じで、後者は省略したものとまったく同じに解釈されます。subDirectory: "." を設定するか、空文字列に評価されるテンプレートを記述すると、このグループ化はフラットになります。
これらのテンプレートが決定しないもの: artifacts: の配置
出力パスのうち 1 つのセグメントは、パステンプレートが設定するものではありません。Recipe の artifacts: ブロックが指定するファイルは、subDirectory: の評価結果の内側で、それを宣言したコンポーネントの名前を付けたディレクトリの下に書き出されます。このセグメントは固定で常に存在します。これは、各寄与元を専用のチャートやモジュールに入れ子にするのではなく、寄与元のファイルを並べて書き出すターゲットの場合です。
理由は、何がファイルに名前を付けるかにあります。ターゲットがレンダリングまたは合成するマニフェストは、ターゲットがその属するコンポーネントから名前を付けるため、すでにそのコンポーネントを識別しています。一方、アーティファクトは作成者が記述したキー(app-config.yaml、netpol.yaml)で名前が付けられ、そのキーはコンポーネントについて何も示しません。それを宣言する Recipe は、どのコンポーネントが自身にバインドされるかを知らないからです。1 つのバウンダリ内で 1 つの Recipe にバインドされた 2 つのコンポーネントは同じパスに書き出すことになり、Recipe の作成者にも Release の作成者にも、それらを分けるための手段がありません。
追加されるのはディレクトリのみです。ファイル名は記述されたキーのままなので、作成者が出力で読み返すファイルには、自分が書いた名前が付いています。
subDirectory: で引き続きできること、および両者の組み合わせ方。 subDirectory: は、寄与元が出力するすべてのファイル(レンダリングされたマニフェスト、合成されたマニフェスト、アーティファクトのすべて)を移動します。そのため、単一コンポーネントのマニフェスト一式を対象に動作する下流ツールのために 1 つのコンポーネントに専用のディレクトリを与える場合や、複数のコンポーネントを 1 つの共有フォルダに振り分ける場合に使う手段です。artifacts: セグメントは、その評価結果の下に適用されます。したがって、Recipe が artifacts: を宣言するコンポーネントに subDirectory: "{{ .capability }}/{{ .component_id }}" を記述すると、コンポーネント名が 2 回現れます。アーティファクトは <capability>/<component>/<component>/<key> に配置され、そのコンポーネントのレンダリングされたマニフェストは <capability>/<component>/<key> に配置されます。コンポーネントの出力全体をまとめたい場合にこのオーバーライドを使い、アーティファクトを分けるだけでよい場合は指定しないでください。それはデフォルトですでに行われています。
.capability はコンポーネントごとに解決され、バウンダリの directory: は 2 つの異なる目的で評価されます。子バウンダリに .parent_boundary.directory を公開するバウンダリ単位の評価は、コンポーネントがバインドされる前に実行されるため、そこでは .capability は空です。寄与元のアーティファクトが実際に配置される場所を決めるコンポーネント単位の評価は、そのコンポーネントの機能を保持します。したがって、directory: "d-{{ .capability }}" を記述した親は、カスケードには d- を公開する一方、自身のアーティファクトは d-compose の下に配置されます。
親境界のカスケード
ネストされた境界は、直近の親境界の評価済みパスと、その親境界自身のカスケード解決済みデータを公開する .parent_boundary ビューを受け取ります。カスケードは 1 階層のみです。境界の .parent_boundary は直接の親であり、祖父母ではありません。さらに上位に到達するには、親境界自身がそのテンプレート内で .parent_boundary を使用し、値をツリーの下方へ明示的に伝播させます。
.parent_boundary で利用できるフィールド:
| フィールド | 説明 |
|---|---|
.parent_boundary.directory | 親境界の評価済み directory: の値(テンプレート適用後)。 |
.parent_boundary.boundary_name | 親境界の記述された名前。 |
.parent_boundary.parameters | 親境界が参照したものと同じ .parameters.* マップ(パラメータ値は Release 全体で共通ですが、対称性のためにこのエイリアスが提供されています)。 |
.parent_boundary.annotations | 親境界のカスケード解決済みアノテーション。 |
標準的なパターンは、directory: を一度だけ記述する親境界と、directory: "{{ .parent_boundary.directory }}" を宣言して成果物を親の下にルーティングする子境界の組み合わせです。これにより子が親のアセンブリパスにまとめられ、すべての子のコントリビューターを含む 1 つのマージ済み出力が生成されます。core/compose-bridge Feature はまさにこれに依拠しています。ブリッジ feature を保持する親境界、親の directory: を共有する 2 つの子境界(例: services-net と data-net)、そしてすべてのコンポーネントとブリッジサービスを含む 1 つのマージ済み docker-compose.yaml です。
逆の形も可能です。子で .parent_boundary.directory を省略する(または異なるパスに評価させる)と、各子がそれぞれ独自のアセンブリを持ちます。どちらの形も第一級のものとしてサポートされています。
レイアウトの実例
レイアウト 1 — デフォルトのバウンダリごとの分離
spec: boundaries: api-prod: directory: "deploy/api-prod" components: api: {} cache: {} data-prod: directory: "deploy/data-prod" components: db: {}各バウンダリは異なる directory: に評価されるため、それぞれが独自のアセンブリを持ちます。
deploy/api-prod/<capability>/...deploy/data-prod/<capability>/...デフォルトの subDirectory: "{{ .capability }}" は、各バウンダリのディレクトリ内でケイパビリティごとに成果物を分離します。バウンダリが 2 つあれば、ケイパビリティごとに 2 つのアセンブリ出力が生成され、マージは行われません。
レイアウト 2 — 共有の親ディレクトリによるアセンブリの集約
spec: boundaries: cluster: directory: "deploy/cluster" annotations: aggrega.ai/chart-name: "cluster-umbrella" features: bridge: type: core/compose-bridge:1.0.0 boundaries: services-net: directory: "{{ .parent_boundary.directory }}" annotations: { aggrega.ai/namespace: services } components: api: {} data-net: directory: "{{ .parent_boundary.directory }}" annotations: { aggrega.ai/namespace: data } components: db: {}両方の子バウンダリは directory: を deploy/cluster(親のディレクトリ)に評価するため、すべてのコントリビューターが 1 つのアセンブリパスでマージされます。デフォルトの subDirectory: "{{ .capability }}" では、両方の子の compose コントリビューターが deploy/cluster/compose/ に配置され、マージされた 1 つの docker-compose.yaml を生成します。親にアタッチされた compose-bridge Feature は 1 回だけ実行され(バウンダリスコープのディスパッチ)、同じマージ済みファイルにブリッジサービスを追加します。
親の aggrega.ai/chart-name: "cluster-umbrella" アノテーションは両方の子にカスケードします。バウンダリが helm-chart のコントリビューターも保持している場合、両方の子の helm-chart サブチャートは cluster-umbrella という名前の 1 つのアンブレラの下に構成されます。1 つのパスにあるコントリビューター間で chart-name の値が一致しない場合、ビルドは停止します。
レイアウト 3 — subDirectory: とパラメーターによるコンポーネントごとのルーティング
spec: parameters: region: "eu-west-1" boundaries: eu-prod: directory: "deploy/{{ .parameters.region }}" components: api: subDirectory: "{{ .capability }}/{{ .component_id }}" db: subDirectory: "{{ .capability }}/{{ .component_id }}" ingress: subDirectory: "shared"バウンダリの directory: は deploy/eu-west-1 に評価されます(パラメーター置換)。コンポーネントごとの subDirectory: のオーバーライドにより、各コントリビューターはコンポーネントごとのサブフォルダーにルーティングされます。ingress コンポーネントは、横断的な成果物のためにフラットな shared サブフォルダーへオーバーライドしています。
deploy/eu-west-1/<capability>/api/...deploy/eu-west-1/<capability>/db/...deploy/eu-west-1/shared/...このパターンは、単一コンポーネントのマニフェストを処理する下流ツールのために、コンポーネントごとの成果物ディレクトリを必要とする企業に適しています。コンポーネントの Recipe が artifacts: も宣言している場合は、この構成を選ぶ前に上記のこれらのテンプレートが決定しないことを参照してください。それらのファイルはすでにコンポーネントのセグメントを持つため、このオーバーライドによって 2 つ目のセグメントが追加されます。
診断
パステンプレートの機能は、次の各状況でビルドを停止します。errors/fatal-halts.md では、これらをここに示す名前で説明しています。そのページには各停止が出力するメッセージが引用されているので、ビルド出力をそのテキストと照合してください。
- Path-template references a variable outside the allowlist(パステンプレートが許可リスト外の変数を参照しています) — パース時:パステンプレートが許可リストにない変数を参照しています。
- Path collision(パスの衝突) — アセンブリ時:2 つのバウンダリのコントリビューターが同じパスに評価されましたが、そのパスのコントリビューター間で一様でなければならないプロパティが一致していません。
- Instance-ID collision(インスタンス ID の衝突) — アセンブリ時:同じ
(path, provider)タプルに評価される 2 つのバウンダリが、同一のインスタンス ID を持つコンポーネントを提供しています。 - Chart-name mismatch(チャート名の不一致) — アセンブリ時:マージされた helm-chart アセンブリが、カスケード解決された
aggrega.ai/chart-nameアノテーションが競合するコントリビューターを受け取りました。 - Missing template key(テンプレートキーの欠落) — パステンプレートが、値に解決されないオープンな変数配下のフィールドを参照しています(例:Release が
regionを省略している場合の{{ .parameters.region }}、または親を持たないトップレベルのバウンダリでの.parent_boundaryのキー)。missingkey=errorにより、バウンダリ、テンプレートのフィールド(directory:かsubDirectory:か)、欠落しているキーを明示したメッセージが出力されます。.parametersと.parent_boundaryはオープンであり、そのキーは作成者が記述するデータです。一方、.manifestはキーを宣言しているため、.manifest配下でキーを打ち間違えると、代わりにパース時に未知の参照として拒否され、診断には.manifestが定義するキーが一覧表示されます。
相互参照
entities/release.md— Release のオーサリング。空間的な分離とdirectory:/subDirectory:フィールドを含みます。providers/architecture.md— プロバイダのディスパッチと、(path, provider)ごとのアセンブリモデル。providers/compose.md— compose 側の(path, provider)ごとの出力。マージされたパスのシナリオを含みます。providers/helm-chart.md— helm-chart のアンブレラ構成と、マージされたパスに対する chart-name のカスケード規則。entities/featurerecipe.md— 境界スコープの FeatureRecipes(core/compose-bridgeFeature は、ここで説明しているマージされたパスのアセンブリモデルに依存しています)。errors/fatal-halts.md— 上記で列挙したパスディスパッチの停止を含む、診断の完全なカタログ。