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

Release

Release エンティティの概念上の役割(Domain 4 — Aggregate を Manifest に結び付け、コンポーネントを物理的な境界にマッピングするデプロイメントルーター)は architecture/04-entity-taxonomy.md で説明しています。時間的な順序付けの仕組み(境界ごとの syncWave)、Dynamic Addressing Polyfill、Parameter Hoisting パターンは architecture/12-day-two-lifecycles.md で説明しています。このページでは Release の記述方法を扱います。

Release の役割

Release は aggregate を manifest に結び付け、コンポーネントを物理的なデプロイ境界(例: aws-eks-production)にマッピングします。Release はコンパイルの唯一のエントリポイントです: aggrega build --release release.yaml。

Release は、物理的な実体を厳密に parameters ブロックにのみ注入することで抽象的な aggregate の契約を満たし、物理的なサイジング(CPU やポートなど)は並列の名前空間 infra を通じて注入します。

すべての Release は、その Manifest を指定する manifest: フィールドを宣言します(ただし Release が extends: を使う場合は、親の manifest ポインタを継承します)。aggrega build CLI はこのフィールドを直接読み取ります。--manifest という CLI フラグは存在しないため、依存関係の指定は Release 自体とともに Git にコミットされた状態に保たれ、デプロイ履歴を Release 自身の Git 履歴から監査できます。

aggregate: フィールドと manifest: フィールドは、言語の他の部分が参照を解決するのと同じく、アイデンティティまたは相対パスのファイルによって解決されます。release からの相対的なファイル名の語幹として解決されることはありません。./ または ../ で始まる値は明示的なローカルファイルであり、Release からの相対パスで直接読み込まれます。裸のトークンはアイデンティティ、つまり参照先エンティティの metadata.name です。manifest: のアイデンティティは、Release 自身のディレクトリを走査して解決されます(Manifest はデプロイ側のオペレーター設定であるため、カタログやレジストリの階層を持ちません)。aggregate: のアイデンティティは、Release のディレクトリ、次にカタログ、次にレジストリという完全なカスケードを通じて解決されます。そのため Release は公開済みの Aggregate をアイデンティティで指定でき、同じ公開モジュールは、Release のトップレベルの spec.aggregate であっても別の Aggregate 内のサブ aggregate であっても同じように解決されます。このアイデンティティまたはパスのモデルにより、共有された Aggregate が参照をファイル名に結合することなく多数の Release バリアントを支えることができ、また公開済みの Aggregate を名前で直接デプロイできます。

パスはワークスペース内にとどまります。 ./ または ../ で始まる値はワークスペースが保持するファイルを指し、Release が書くその他のすべてのパス(後述する extends: や parameters の $import:)も同様です。書かれたとおりにワークスペースの外へ出るパス、または途中のシンボリックリンクによってワークスペースの外へ運ばれるパスは、それが指すファイルから何かが読み込まれる前に拒否されます。ワークスペースの外に置かれた Aggregate をデプロイするには、それをアイデンティティで指定し、それを保持するディレクトリをワークスペース設定のカタログディレクトリとして列挙します。Manifest、extends: が指定する Release、および parameters ファイルは Release の隣で読み込まれ、名前で検索されることはないため、ワークスペース内に置きます。コマンドラインで指定した Release、またはワークスペース設定が指定する Release がワークスペースの外にある場合、それ自体が独立したルートとなります。その Release が書くすべてのパス、およびその extends: チェーンがたどる Release が書くすべてのパスは、その Release を保持するディレクトリ内のファイルを指す必要があり、そのディレクトリの外へ出るパスやリンクによって外へ運ばれるパスは同じように拒否されます。そのような Release が指定するものはその隣に置くか、両方を保持するワークスペースでビルドしてください。errors/fatal-halts.md の §“A reference to another file leads out of the directory it must stay inside(別のファイルへの参照が、とどまるべきディレクトリの外へ出ています)” を参照してください。

Release はコンパイル済みアーティファクトの出力先を決定します。プロバイダーのディスパッチは Release が指す Manifest の役割です(役割の分担については Manifest と Release: 関心の分離 を参照してください)。

環境メタデータ

すべての Release のメタデータブロックは environment: フィールドを受け付けます。これは Release のデプロイ先となる環境を識別する自由形式の文字列です(典型的な値: production、staging、dev)。このフィールドは情報提供用であり、列挙値、スキーマレベルのパターン、type: string 以外のエンティティ間検証はいずれも持ちません。コンパイラはその値を、helm プロバイダがレンダリングするすべての Kubernetes マニフェストに、Aggrega の他の来歴ラベル群とともに aggrega.ai/environment ラベルとして出力します。その値が有効な Kubernetes ラベル値であれば記述どおりに出力し、そうでなければ有効な値に書き換えて出力したうえで、正確な値を aggrega.ai/environment アノテーションとして保持します(たとえば eu/prod には eu-prod というラベルが付きます)。helm-chart プロバイダは、サブチャートに配置する $import: で読み込んだ各アーティファクトに同じラベルを追加しますが、サブチャート自身のテンプレートは作成者が記述した内容をそのまま保持します。compose プロバイダは、出力する各サービスに同じ値を aggrega.ai/environment ラベルとして付与します。

environment: の記述を方向付ける実用的なパターンは 5 つあります。

  1. OTel/FinOps のコスト配分。 クラウドのコストダッシュボード(AWS Cost Explorer、Datadog Cloud Cost Management、CloudHealth)は、Kubernetes の Pod を環境でタグフィルタリングします。aggrega.ai/environment: production ラベルは Helm プロバイダのラベル注入によって Pod ラベルに伝わり、コストレポートはリソースごとの手動タグ付けなしに aggrega.ai/environment で支出をグループ化します。

  2. OTel のトレースとログのフィルタリング。 オブザーバビリティダッシュボード(Datadog、New Relic、Honeycomb、Grafana Tempo)は、テレメトリを環境ラベルでフィルタリングします。aggrega.ai/environment: staging により、オペレーターは名前空間の慣例やチャート名でフィルタリングすることなく、ログクエリやトレース検索を staging に絞り込めます。レンダリングされる範囲全体で単一の正規ラベルとなります。

  3. Kubernetes オペレーターによるターゲティング。 GitOps コントローラー(ArgoCD、Flux)やポリシーオペレーター(Kyverno、OPA Gatekeeper)は、環境固有のポリシーのために環境ラベルでリソースをフィルタリングすることがあります(例:「本番環境専用のリソースには approved-image-source ラベルが必要」)。aggrega.ai/environment ラベルは、名前空間の慣例や命名パターンとは別の安定したセレクターを提供します。

  4. マルチリージョンの本番環境の区別。 production-us-east Release と production-eu-west Release を並行して運用するチームは、どちらも metadata.environment: production であれば、リージョンをまたいで同じ aggrega.ai/environment: production ラベルを得ます。別のリージョンラベルと組み合わせることで、リージョン横断のコスト集計(「本番環境の総支出」)とリージョンごとのドリルダウンが可能になります。

  5. コンプライアンスのスコープ設定。 SOC 2、PCI、HIPAA のエビデンス収集は、環境ごとにスコープが設定されます(本番環境のみの監査など)。aggrega.ai/environment ラベルは、コンプライアンスのエビデンス収集ツール(Vanta、Drata)が監査スコープでリソースをフィルタリングするために使用します。

スキーマはすべての Release に environment: を要求します。値は情報提供用であり、コンパイラがこれを読み取るのは aggrega.ai/environment ラベルを書き込むためだけです。

スキーマレベルの制約

2 つの構造的な保証が、Single Source of Truth としての Aggregate を保護します。

  • values: は禁止されています。 Single Source of Truth としての Aggregate を保護するため、Release スキーマは values: ブロックを機械的に禁止しています。Operator は Release から、どの Component や Feature に対しても values を宣言できません。この禁止は uses エッジにも及びます。Release のエッジごとの uses エントリは infra と、その接続に書き込むアタッチメントを持ち、それらのアタッチメントも infra を持ちます。values を持つことはありません(開発者向けのエッジごとの値と、接続上のアタッチメントの値は Aggregate に残ります)。Developer 向けの値の環境ごとの差異は Parameter Hoisting を通じて流れます。Developer が Aggregate で型付きの parameters.* フィールドを公開し、Component の values テンプレートがそれを参照し、Release がその環境向けにパラメータを充足します。スキーマレベルでの禁止の明示的な記述については architecture/06-data-taxonomy-and-composition.md §8 Constraint 4 を参照してください。Release の uses エッジのサーフェス(設定および接続できる内容)は、後述のエッジごとの接続設定で説明しています。
  • extends + aggregate: は拒否されます。 追跡不能な「aggregate を変更する」Releases を防ぐため、Release が extends を使用する場合、aggregate ポインタの宣言は Release スキーマによって拒否されます。子 release は、親とまったく同じ Developer Intent に対応しなければなりません。ただし manifest は任意となり、「Late Binding」が可能になります。これにより Operator は物理トポロジ全体を継承しつつ、Manifest だけを的確に差し替えることができます。

parameters: ブロック

Release は、Aggregate が宣言する型付きのパラメータ契約を満たします。spec.parameters: が記述面です。これは YAML マップで、そのキーは Aggregate の parameters.* 宣言に一致し、その値は環境ごとの充足値を与えます。

# Aggregate declares the typed contract
apiVersion: aggrega.ai/v1beta1
kind: Aggregate
metadata:
name: my-app
version: 1.0.0
spec:
parameters:
db_size: { type: string, required: true }
timeout_seconds: { type: integer, default: 30 }
region: { type: string, enum: [us-east-1, eu-west-1], required: true }
# Release fulfills the contract for this environment
apiVersion: aggrega.ai/v1beta1
kind: Release
metadata:
name: prod-release
version: 1.0.0
environment: production
spec:
aggregate: my-app
manifest: prod-manifest
parameters:
db_size: "100Gi"
timeout_seconds: 60
region: "us-east-1"

各値はパラメータ契約レイヤーで Aggregate が宣言したスキーマのチェックを受け、Release が必須パラメータを省略した場合(E0165、parameter-missing)や、スロットの契約が拒否する値を与えた場合(E0164、parameter-contract-violation)、ビルドは停止します。default: 付きで宣言されたパラメータは、Release がそのスロットを省略するとデフォルト値を受け取ります。型付きの契約が唯一の記述語彙です。

2 つの記述モード — 内容の形によるディスパッチ。 parameters: は、インラインの YAML マップ(モード 1、上記)か、ローカルファイルを指す単一の $import: キー(モード 2)のいずれかを受け付けます:

spec:
aggregate: my-app
manifest: prod-manifest
parameters:
$import: ./prod-parameters.yaml

相対パスの $import: は、コマンドをどこから実行しても、それを記述した Release を含むディレクトリを基準に解決されます。そのため、コマンドラインとエディタは同じファイルを読みます。絶対パスはそれ自体の場所を指します。いずれの場合もワークスペース内のファイル、またはワークスペース外で指定された Release の場合はそれを含むディレクトリ内のファイルを指す必要があります。この箇所では 2 つのモードは相互に排他的であり、インポートできるのは単一のファイルのみです。複数ファイルによるパラメータの階層化は Release の extends: チェーンが担います。親 Release がパラメータの基本セットを提供し、子が環境ごとに拡張・上書きします。このパターンについては、後述の Composite Release / extends: の継承を参照してください。

パラメータと infra の境界。 パラメータは、Aggregate が宣言する型付きスロットとして表現された Developer の認知的意図を運び、Release がそれを満たします。Release 上の infra: は、特定のコンポーネントや Feature アタッチメントに付与される Operator の物理的なサイジング(レプリカ数、CPU/メモリの上限、ストレージクラス)を運びます。パラメータは .parameters.X を介して Aggregate の values: テンプレートに流れ、infra: は .infra.X を介して Recipe の valuesMapping: テンプレートに流れます。データの柱の分類については architecture/06-data-taxonomy-and-composition.md §3 を、パイプラインを通じたパラメータのライフサイクルについては templates/parameters-context.md を参照してください。

境界とデフォルトスコープ

Release はコンポーネントを境界(boundary)にまとめます。境界は物理的なデプロイ単位であり、それぞれが独自の出力ディレクトリとアノテーションのカスケードを持ちます。単一境界のケースが一般的であるため、特別な手続きは必要ありません。

単一スコープ(デフォルト)。 コンポーネントを spec.components: の直下に記述し、boundaries: ブロックを省略します。コンパイラはそれらを合成された default 境界にまとめ、その出力はフラットになります。成果物は dist/ の直下に配置され(プロバイダーごとに、後述の安全な subDirectory デフォルトにより dist/compose/、dist/helm/、…)、パスに境界名のセグメントは含まれません。これは最もシンプルなデプロイであり、境界に名前を付けずに、フラットな Compose または単一クラスターのターゲットに対して aggrega build を実行します。

spec:
aggregate: aggregate
manifest: manifest
components:
db:
infra:
engine_version: "11.4"
web:
infra:
port: 8080

複数スコープ。 Release が複数の物理的なグループ(別々のクラスター、リージョン、または同期ウェーブ)にまたがる場合は、boundaries: の下に名前付きの境界を宣言します。各境界は独自の directory:、アノテーションのカスケード、syncWave: を持ち、コンポーネントはその境界内で指定されます。

相互排他性。 spec.components: と spec.boundaries: は Release のルートにおいて相互排他です。Release はどちらか一方を記述し、両方を記述することはありません。両方を宣言したドキュメントは、読み込み時にエンベロープエラーで停止します。トップレベルの components は、境界の components と同じコンポーネントごとのオペレーター向けの形(infra:、annotations:、uses:)を持ちます。

default という名前で宣言された境界。 フラットな出力は名前ではなく、合成されたデフォルトの性質です。boundaries: の下で default という名前の境界を明示的に宣言した Release では、それは通常の名前付き境界となります。その出力は、他の宣言された境界とまったく同じく、directory:(デフォルトは dist/boundaries/default/)に従います。

デフォルトスコープのパターンについては、architecture/06-data-taxonomy-and-composition.md §7 を参照してください。

空間的分離と出力パス

各 boundary は、コンパイルされた成果物の物理的な出力先 directory を宣言します。boundary 内の component は、component ごとの subDirectory で上書きできます。コンパイラは両者を結合して最終的な成果物のパスを算出し、どのプラットフォームでもスラッシュ区切りの形式にします: Final_Path = Clean(Join(Evaluated(directory), Evaluated(subDirectory)))。

  • 1 つのディレクトリに 1 つの表記。 評価されたパスは一度正規化されるため、out/a、out//a、./out/a、out/a/ は同じ 1 つのディレクトリです。正規化後のパスが同じディレクトリになり、同じ provider でレンダリングされる boundary 同士は、同一のパスを書いた boundary 同士とまったく同じようにまとめて組み立てられます。
  • パスは出力ルートの配下に留まります。 出力ルートの外へ出るパス(..、../escape、a/../..)、絶対パス、またはディレクトリをまったく指さないパス(空、または正規化すると出力ルートそのものになるもの)は、何かが書き込まれる前にビルドを停止させます。メッセージには Release、boundary、問題のあるフィールド(directory: または subDirectory:)、およびその評価結果の値が示されます。この値はテンプレートの結果であることが多いためです。
  • 安全なデフォルト。 subDirectory が省略されているか空の場合、コンパイラは自動的に subDirectory: "{{ .capability }}" を適用します。これにより、レンダリング capability ごとの成果物(Helm、Helm-chart、Compose、Terraform、CloudFormation)がそれぞれ専用のサブフォルダに配置され、下流の CI/CD ツールで異なる成果物が衝突するのを防ぎます。明示的に書かれた subDirectory: "" は省略された場合とまったく同じに扱われるため、このデフォルトも適用されます。
  • フラットな上書き。 サブディレクトリを完全に無効にする(すべての成果物を directory の直下に置く)には、subDirectory: "." を設定します。空文字列に評価される subDirectory テンプレート(たとえば sub を "" に設定した "{{ .parameters.sub }}")でも同様に無効になります。
  • テンプレート変数。 directory は {{ .capability }}、{{ .boundary_name }}、{{ .parameters.X }}、{{ .manifest.recipe_name }}、および外側の boundary からデータをカスケードするための {{ .parent_boundary.* }} を使って評価されます。subDirectory は同じ変数セットに加えて {{ .component_id }}(component ごとの上書きのみ)を使って評価されます。コンパイラはパステンプレートを missingkey=error で評価するため、宣言されていない変数を参照すると、正確な診断とともにビルドが停止します。コンテキストごとの対応表と親 boundary のカスケード規則については、パステンプレート変数を参照してください。

boundary の annotation は、含まれるすべての component へ下方向にカスケードします。infra は、それを対象とする component に厳密に局所化されたままです。再帰的な boundaries マップでは任意の入れ子(boundary の中の boundary の中の boundary)が可能で、annotation のカスケードと infra の局所性という不変条件はすべての階層で保たれます。

実例:

apiVersion: aggrega.ai/v1beta1
kind: Release
metadata:
name: spatial-release
version: 1.0.0
environment: production
spec:
aggregate: spatial-app
manifest: prod-manifest
boundaries:
eu-prod:
directory: "deploy/eu-prod"
# Scenario A: Safe Default. Compiler automatically applies `subDirectory: "{{ .capability }}"`.
annotations:
"aggrega.ai/namespace": "finance-frontend" # Merges downwards as annotations
components:
api-server:
infra: { replicas: 5 } # Strictly local
aws-rds:
# Scenario B: Bespoke Enterprise Naming.
subDirectory: provisioning
postgres-db:
# Scenario C: The Flat Directory Override.
subDirectory: "." # not "", which takes the default

この仕組みでカスケードされた annotation は、下流の Recipe テンプレートで .context.annotations.release を通じて参照できます。レンダラーがそれらをどのように利用するかについては、Recipe の作成とテンプレート展開マトリクスを参照してください。

構造化された annotation 値。 Manifest のバインディングが 1 つの annotation キーに対して複数の infra-pillar ルーティングパスを宣言している場合、Release 側の annotation 値は、複数の Feature スキーマフィールドの値を 1 つの宣言で運ぶ構造化オブジェクトにできます:

boundaries:
prod:
annotations:
feature.myco/db-pool:
pool_size: 20
max_connections: 100
components:
api:
annotations:
feature.myco/db-pool:
max_connections: 200 # closer-level override
# pool_size not listed → inherits 20 from boundary

構造化された値は、サブキーごとのディープマージでカスケードし、より近い階層のサブキーが親のサブキーを上書きします。サブキーごとの null は 1 つのサブキーだけを除外し、兄弟のサブキーはそのまま残ります。Release 側が適用するのは、バインディングマップの pillar が infra であるサブキーのみです。values にルーティングされるサブキーは Aggregate 側の annotation に属します。構造化された値の詳しい解説(両側にまたがる合成、サブキーごとの型検証、緩和されたデフォルトの規律)については、providers/well-known-annotations.md の §「Structured annotation values」を参照してください。

よく知られた annotation。 任意のキーに加えて、Aggrega の標準ライブラリは aggrega.ai/ および feature.aggrega.ai/ 名前空間の下に一連のよく知られた annotation を定義しており、配置、ネットワーク、セキュリティ、可観測性のカテゴリに分類されています。Release の boundary に annotation を追加する作成者は、完全な対応表と provider ごとの利用規則について providers/well-known-annotations.md を参照してください。このページには、どの provider がそれぞれのよく知られたキーを適用し、キーが存在するときにどのような動作を出力するかが記載されています。

エッジごとの接続設定

boundary 内のコンポーネントは、Component のカタログの usesSchema が宣言するソケットの範囲内で、トポロジーのエッジを設定または配線する uses: ブロックを持つことができます。これはオペレーターが接続ごとに操作できる面であり、開発者が作成したアーキテクチャの所有権を開発者が保持できるよう範囲が限定されています。

  • 既存のエッジを設定する。 開発者がすでに宣言したエッジに、エッジごとの infra を設定します。エントリは開発者のエイリアスを指定して infra を与えます。ターゲットは、開発者が配線したものと同じターゲットを指定するか、省略します。infra はソケットの infraSchema に照らして検証されます。
  • 未バインドのソケットを配線する。 Component の usesSchema が宣言しているものの開発者が配線しなかったソケットに、既存のコンポーネントを指すエッジを作成します。作成したエッジにもエッジごとの infra を持たせることができます。
  • 接続にアタッチする。 エントリの features: の下に、ソケットが featuresSchema で宣言するスロット(開発者の接続エントリが埋めるのと同じスロット)をキーとしてアタッチメントを記述します。各アタッチメントは type、省略可能な description、infra を持ち、values は決して持ちません。開発者が同じ接続ですでに埋めたスロットの下では、エントリはそのアタッチメントのサイズを決めます。type と values は Aggregate から来るため、infra のみを書きます(ここに type を書く場合は Aggregate のものと一致しなければならず、一致しなければこのエントリでビルドが停止し、両方の名前が示されます)。開発者が空のままにしたスロットの下では、アタッチメントは Release 自身のものとなり、type が必須です。いずれの場合も、開発者のものとまったく同様に、埋めた内容はスロットの selector に従い、required スロットの充足にも数えられます。

この面は create-not-retarget(作成はできるが付け替えはできない)です。Release は未バインドのソケットにエッジを追加できますが、開発者がすでに宣言したエッジの向きを変えることはできません。開発者のエッジとは異なるターゲットを指定するエッジごとのエントリはビルドを停止させます。同じターゲットを指定する(または省略する)エントリは、そのエッジを設定します。また Release は、エッジ上やそこで書くアタッチメント上で values を宣言すること(開発者向けの値は Aggregate に留まります)、usesSchema が宣言していないソケットをバインドすること、存在しないコンポーネントにエッジを向けることもできず、いずれも致命的な停止となります。すべてのエッジを描いた後に存在しない接続に infra や features を設定するエントリも同様です。ただし、消費側のコンポーネントが active: false で無効化されている場合は除きます。errors/fatal-halts.md の §「When building the topology」を参照してください。

さらに 3 つの停止が、接続のアタッチメントをその接続に留めます。

  • ソケットがスロットを宣言していない名前 は、Aggregate の接続エントリの場合とまったく同様に、Release 内のこのエントリで停止し、ソケットが宣言するスロットと、そのうち名前から 1 編集の距離にあるものを示します。
  • Release だけが作るアタッチメントを type なしで書いた場合 は、接続エントリで停止し、スロットを示します。Release が作るアタッチメントは values を持たないため、values が何も必須としない Feature に適しています。スキーマが値を必須とするものは、同じエントリで値の欠落により停止します。呼び出し元のロケーターを持つ標準ライブラリの認証情報 Features は、values で何も必須としません。いずれもロケーターを infra でも受け取ります(後述)。
  • 合成された名前を接続以外の場所に書いた場合 は停止します。接続のアタッチメントは、消費側コンポーネントの <alias>.<slot> という名前のアタッチメントになります(Aggregate の接続エントリを参照)。また、コンポーネントエントリ自身の features: のキーも boundary のキーもドットを許容します。コンポーネントエントリがその名前を書いた場合、または boundary がその名前を書き、それがその接続を持つコンポーネント(その boundary 内やその中にネストされた boundary 内に配置されたコンポーネント、ルーティングされたサブモジュールのものを含む)に届く場合、両方の表記を示して停止し、届いたコンポーネントごとに 1 回報告されます。ソケットのスロットは各接続で埋められ、より広いスコープからカスケードするアタッチメントによって埋められることはありません。
spec:
components:
router:
uses:
models:
# Size the attachment the Aggregate declared on the "gpt" connection: infra only.
gpt:
features:
credential:
infra: { rotation: hourly }
# Attach on a connection the developer left without one: the type is required.
plain:
features:
credential:
type: core/generated-secret

Release が配線する接続上の認証情報は、シークレットを infra で指定します。 Release が配線する接続には Aggregate 内のエントリがないため、そこで認証情報の values を書くものはなく、Release はどこにも values を書きません。そのため、呼び出し元のロケーターを持つ標準ライブラリの各認証情報 Feature(core/referenced-secret、core/referenced-secret-set、core/secret-value、core/secret-provided)は、ロケーターを values だけでなく infra でも受け付けます。origin、または core/referenced-secret-set では entries を、両方の柱で同じ形状、同じ sensitive: true 宣言で受け付けます。どの実現も、ロケーターを持つ方の柱を読みます。

spec:
components:
router:
uses:
models:
gpt:
target: gpt # wire the socket the developer left unbound
features:
credential:
type: core/referenced-secret
infra:
origin: openai-team-a # the secret the operator names

ロケーターはアタッチメントごとにちょうど 1 つの柱に書きます。両方に持つアタッチメント(同じスロットに対する Aggregate の values と Release の infra)、またはどちらにも持たないアタッチメントは、Feature 自身のアサーション(E0033)で停止し、Feature、アタッチメント、コンポーネントを示して、どちらのケースであったかを伝えます。この規則はコンパイラではなく、それらの Features のカタログエンティティに属します。コンパイラは、あらゆる Feature のアサーションを評価するのと同じようにそれらのアサーションを評価します。ロケーター以外のフィールドは元の柱のままです。key は values のリーフのままなので、Release だけが作るアタッチメントは Feature のデフォルトのデータキー value を読みます。values: の禁止は変わりません。オペレーターのロケーターは infra です。

core/secret-provided だけは接続に適合しません。これはアタッチメント自身の inject: ブロックが配信するために値を公開しますが、接続のアタッチメントはどちらのドキュメントでも inject: ブロックを持たないため、接続上ではそれを配信する inject: ブロックがありません。接続では core/referenced-secret または core/secret-value を使用してください。

spec:
aggregate: spatial-app
manifest: prod-manifest
boundaries:
eu-prod:
components:
api-server:
uses:
databases:
# Configure the developer-declared edge "primary": add per-edge infra.
# The target matches what the Aggregate wired (or is omitted) — a configure, not a retarget.
primary:
infra: { storage_class: fast-ssd }
caches:
# Wire an edge into the declared-but-unbound "caches" socket to an existing component.
main:
target: redis-prod
infra: { storage_class: standard }

解決されたエッジごとの infra は、消費側コンポーネントのレンダーコンテキストの .context.uses.<alias>.infra.<key> に流れます。ターゲットコンポーネントのコンテキストには決して現れないため、ターゲットのレンダー出力は、そこへのエッジを設定する消費側に対して不変です。接続上のアタッチメントも消費側コンポーネントに、そのアタッチメントの 1 つとして置かれます。その infra は同じスロットに対する Aggregate の values とマージされ、その FeatureRecipe は両方に対してレンダリングされます。消費側コンポーネントの Recipe はそれを接続の下の .context.uses.<alias>.features.<slot> で読み、その Workload はスロットと並べて接続を指定することでそれを配信します。接続が持つ認証情報の配信を参照してください。

aggregates: フィールド — ネストされたサブモジュールを境界へルーティングする

Aggregate が spec.aggregates: でネストされたサブモジュールを宣言している場合、Release は対象の境界の中で components: と並べて aggregates: を宣言し、各サブモジュールのコンポーネントがどの境界に配置されるかを決定します。

# Aggregate declares two sub-aggregates
apiVersion: aggrega.ai/v1beta1
kind: Aggregate
metadata:
name: platform
version: 1.0.0
spec:
aggregates:
finance:
type: finance-module:1.2.0
analytics:
type: analytics-module:2.0.0
components:
gateway:
type: core/ingress
---
# Release routes each sub-aggregate into a specific boundary
apiVersion: aggrega.ai/v1beta1
kind: Release
metadata:
name: prod-release
version: 1.0.0
environment: production
spec:
aggregate: platform
manifest: prod-manifest
boundaries:
eu-prod:
directory: "deploy/eu-prod"
aggregates:
finance: {}
components:
gateway: {}
us-prod:
directory: "deploy/us-prod"
aggregates:
analytics: {}

Aggregate.spec.aggregates: に列挙されたすべてのサブ Aggregate を、ちょうど 1 つの境界に配置します。

ルーティングはコンポーネントを配置します。ルーティングされたサブモジュールのすべてのコンポーネントは、それをルーティングする境界に配置され、その境界の directory、subDirectory、syncWave とアノテーションのカスケードを受け取ります。これは components: の下で直接指定されたコンポーネントが受け取るのと同じコンテキストであり、出力されるアーティファクトに付与される aggrega.ai/boundary-path の来歴情報も含みます。したがって、サブモジュールをルーティングすることと、そのコンポーネントのそれぞれを修飾されたドット区切りパスで空の本体とともに指定することは、同一のアーティファクトを生成します。ルーティングはそれを短く表す方法であり、サブモジュールの内容を知らずに表す唯一の方法です。

コンポーネントはちょうど 1 つの境界に属し、ドキュメントがコンポーネントを二重に配置するとビルドは停止します。たとえば、同じサブモジュールを 2 つの境界にルーティングした場合、サブモジュールを 1 つの境界にルーティングしながらそのコンポーネントの 1 つを別の境界で指定した場合、あるいはコンポーネントを直接とルーティングエントリ経由の両方で指定した場合です。どちらを残すかは作成者の判断であるため、診断は両方の箇所を示します。サブモジュールをある境界にルーティングし、その同じ境界の下でそのコンポーネントの 1 つを指定することは競合ではありません。ルーティングがコンポーネントを配置し、指定されたエントリがそれを設定します。

Release がどこにも配置しないサブ Aggregate はビルドを停止させます。 配置は両方の書き方にわたって読み取られるため、ビルドが停止するのはどちらもサブモジュールに届かない場合だけです。つまり、どの境界も aggregates: の下でそれをルーティングせず、どの境界も components: の下で修飾されたドット区切りパスによってそのコンポーネントを指定していない場合です。どちらの書き方も単独で配置を行い、すべてのコンポーネントが個別に指定されているサブモジュールにはルーティングエントリは不要です。修正箇所は、そのサブモジュールをインポートした Aggregate の aggregates: ブロックです。直接インポートされたものであれば Release がデプロイする Aggregate、ネストされたものであればインポート元のサブモジュール自身のドキュメントです。診断はそのエントリを、インポート元のドキュメントが記述しているキーで示すため、ネストされたサブモジュールではドット区切りパスではなくローカル名として表示されます。

2 つのケースは意図的に停止しません。コンポーネントを提供しないサブモジュールには配置するものがありません。active: トグルが false に解決されるサブモジュールは合成されていないため、配置すべきコンポーネントが存在しません。

部分的な配置はこのルールでは停止しません。サブモジュールは、そのコンポーネントのいずれかが境界に届いた時点で配置済みとなるため、その 1 つを指定すればサブモジュールの条件は満たされます。しかし、残りを省略してよいわけではありません。境界が指定しなかった各コンポーネントは何によっても配置されず、後述のコンポーネントのルールがそれぞれのキーで報告します。そのため、部分的に配置されたサブモジュールは、サブモジュール単位ではなく、取り残したコンポーネントごとに 1 回ずつビルドを停止させます。サブモジュール全体を 1 行で配置する書き方は、ルーティングエントリとすべてのコンポーネントの指定の 2 つです。その中間の書き方は、指定したものだけを配置し、それ以上は配置しません。

Release がどこにも配置しないコンポーネントも、一段内側でビルドを停止させます。 上のルールはサブモジュールが境界に届いたかを問い、こちらは合成に含まれるすべてのコンポーネントについて同じことを問います。コンポーネントは、その境界の components: の下で指定されるか、境界がルーティングするサブモジュールの中にあることで境界に届きます。どちらにも該当しないコンポーネントは Release が宣言するすべての境界の外でレンダリングされ、directory、subDirectory、syncWave、アノテーションのカスケード、コンポーネントごとの infra: をどこからも受け取りません。そのため、境界の設定が届かなかったアーティファクトを出力するのではなく、ビルドを停止してそのコンポーネントを示します。

2 つのルールは、コンポーネントにサブモジュールがあるかどうかだけでなく、そのサブモジュールの状態を問うことで領域を分担します。Release がどこにも配置しなかったサブモジュールのコンポーネントはサブモジュールのルールに任され、そのルールはその 1 つの作成上の誤りを、モジュールが持つコンポーネントごとにではなく、aggregates: エントリで 1 回だけ報告します。Release が部分的に配置したサブモジュールのコンポーネントはこのルールの対象です。サブモジュールのルールはそのようなモジュールを配置済みと見なし、何も報告しないためです。そのため、境界が指定しなかった各コンポーネントは、それを宣言するドキュメント内のそれぞれのキーで、ここで報告されます。したがって、サブモジュールを部分的に配置すると、指定するつもりだったものが正確に指定され、指定しなかった各コンポーネントについて通知されます。

そして、デプロイされる Aggregate が持たないコンポーネントを指定する境界エントリはビルドを停止させます。 上の 2 つのルールは配置をコンポーネントの側から、つまり何かがそれを配置したかを読み取ります。こちらは Release の側から、名前が解決されるかを読み取ります。何にも解決されないエントリは何も配置しないため、その subDirectory、アノテーション、コンポーネントごとの infra: と uses: は存在しないコンポーネントを設定することになります。そのため、エントリが届かなかったデプロイメントを出力するのではなく、ビルドを停止します。両方の書き方が検査されます。境界の components: の下の名前は、合成完了後にコンポーネントが持つ id として読み取られ、ルーティングエントリの components: の下の名前は、そのサブモジュール内でコンポーネントが持つローカル名として読み取られます。診断はエントリが指した id を報告しますが、ルーティングの書き方ではこれはファイル内の名前とは異なります。ファイルはローカル部分を記述し、サブモジュールがその接頭辞を補うためです。

名前が拒否されるのは何にも解決されない場合であり、その形が理由になることはありません。一段内側のモジュールのコンポーネントはそのモジュールの接頭辞を持つため、ドット区切りの名前はごく普通のものです。active: トグルが false に解決されるコンポーネントも引き続き指定できます。コンポーネントを無効にしても、それを設定する Release を編集する必要はありません。

サブシステムは修飾パスに何も加えないため、境界は Aggregate がコンポーネントをどのようにグループ化していても、その素の名前でコンポーネントを指定します。 id を修飾するのはサブモジュールの合成だけです。デプロイされる Aggregate のコンポーネントは、作成者がトップレベルに書いても data という名前のサブシステムの中に書いても store です。一段内側のモジュールのコンポーネントは data.store であり、そこでの data はサブシステムのものではなくモジュールの接頭辞です。したがって、data という名前のサブシステムにあるコンポーネントに対して data.store と記述した境界エントリは何も指しません。エントリ自体が上のルールで停止し、対象のコンポーネントもどの境界にも届きません。エントリを store に修正すれば両方が解決します。

したがって、サブモジュールの配置には boundaries: が必要です。単一スコープの形式にはルーティングの手段がなく(aggregates: は境界のキーであり、spec: のキーではありません)、トップレベルの components: マップは修飾されていない名前しか受け付けないため、サブモジュールをインポートする Aggregate をデプロイする Release は boundaries: を宣言します。

再帰的なルーティング。 aggregates: は再帰的です。境界の aggregates: の下の各エントリは、深くネストされたモジュール合成のために、それ自体がネストされた aggregates: マップを宣言できます。

Aggregate ごとのルーティングブロック。 ルーティングエントリが受け付けるキーはちょうど 2 つで、それ以外はありません。そのサブモジュールの個々のコンポーネントを設定する components: と、さらに深くネストされたモジュールのためのネストされた aggregates: です。annotations: は境界に属し、コンポーネントごとの infra: はルーティングエントリ自身の components: の下のエントリに属します。

ルーティングエントリの中では、コンポーネントはそのサブモジュール内で持つ名前(data.consumer ではなく consumer)をキーとします。そこではそれが唯一の名前だからです。修飾されたドット区切りパスは、境界自身の components: マップが同じコンポーネントを指定する方法です。2 つの書き方は互換ではなく、ルーティングエントリはドット区切りのキーを拒否します。

boundaries:
eu-prod:
directory: "deploy/eu-prod"
annotations:
aggrega.ai/namespace: "finance-zone"
aggregates:
finance:
components:
ledger: # the component's name inside the finance module
infra:
replicas: 3
aggregates:
reporting: {} # a module nested inside finance

サブ Aggregate 自身のコンポーネントと Features は Release で再宣言されません。Release はそれらを再記述するのではなくルーティングし、1 つを指定するのはそれを設定する場合に限られます。

時間的な順序付け — boundary ごとの syncWave

Release 内の各 boundary は、任意で整数の syncWave: フィールドを宣言でき、これにより Operator は Developer の Aggregate に触れることなくデプロイ順序を明示的に制御できます。wave 番号は boundary 自体のプロパティであり、boundary のサブツリーに含まれるすべての component は、成果物の出力時にその boundary の wave 値を継承します。

apiVersion: aggrega.ai/v1beta1
kind: Release
metadata:
name: prod-release
version: 1.0.0
environment: production
spec:
aggregate: my-app
manifest: prod-manifest
boundaries:
infra:
directory: "deploy/infra"
syncWave: 0
components:
core-vpc: {}
postgres-db: {}
migrations:
directory: "deploy/migrations"
syncWave: 1
components:
db-migration-task: {}
apps:
directory: "deploy/apps"
syncWave: 2
components:
web-server: {}
ai-agent: {}

wave 値のセマンティクス。 syncWave: は符号付き整数(正、ゼロ、または負)です。フィールドを省略した場合のデフォルトは 0 です。wave 値は親 boundary から継承されません。デフォルト以外の wave を必要とする各 boundary は、明示的に宣言します。Components は所属する boundary の wave を上書きできません(wave は空間的な単位のプロパティであり、個々の component のプロパティではありません)。

provider ごとの出力。 コンパイラは、boundary の wave 値を provider ネイティブの形式でレンダリング結果に出力します。以下ではそのうち 3 つの形式を詳しく説明します。terraform を含むすべての標準ライブラリ provider で wave が何をするかは、providers/reference-matrix.md の「What a boundary’s syncWave does on each provider」に表としてまとめています。

  • Kubernetes(helm / helm-chart プロバイダ)。 wave が 0 でない場合、helm プロバイダが boundary のためにレンダリングするすべての Kubernetes リソースは、GitOps 標準の argocd.argoproj.io/sync-wave: "<N>" アノテーションを持ちます。Helm フックはさらに helm.sh/hook-weight: "<N>" アノテーションを持ち、同じ wave 値が Helm 自身の pre/post-install の順序付けも決定します。ArgoCD は sync-wave アノテーションを、Helm はフックの weight を読み取り、それぞれがそれに従ってリソースの適用順序を決めます。helm-chart プロバイダはソースチャートのテンプレートを作成者が記述したとおりにコピーするため、サブチャート自身のリソースが wave を持つのは、それらのテンプレートが wave を記述している場合だけです。helm-chart プロバイダが追加する $import: で読み込んだアーティファクトは argocd.argoproj.io/sync-wave を持ち、helm.sh/hook-weight は持ちません(providers/helm-chart.md を参照)。
  • Compose。 boundary のレンダリング先となる compose ファイル内のすべてのサービスは、depends_on を通じて、同じファイルに寄与した直前の wave のサービスを待機します。対象が healthcheck を宣言している場合は対象のヘルス状態で、宣言していない場合は対象の起動でゲートされます。したがって wave が順序付けるのは 1 つのファイル内のサービスだけで、その外側には及びません。別々の docker-compose.yaml ファイルにレンダリングされる boundary は別々の compose プロジェクトであり、それらの順序付けは operator の責任範囲です。uses: エッジは、wave と並行して引き続きエッジごとの順序を表現します。providers/compose.md を参照してください。
  • CloudFormation。 組み立てられたスタックテンプレート内のすべてのリソースは、DependsOn を通じて、同じスタックに寄与した直前の wave のリソースに依存します。そのため wave は、リソースが作成される順序と、その逆として削除される順序を決定します。これは準備完了状態に基づく順序付けではありません。スタックテンプレートには、リソースが利用可能であるという概念がありません。フラグメント自身の DependsOn は置き換えられず、拡張されます。別のスタックに組み立てられる Components は対象外であり、2 つのスタック間の順序付けは operator の責任範囲です。providers/cloudformation.md を参照してください。

wave の記述単位とデプロイ可能な単位。 boundary は wave の記述単位です。デプロイ可能な単位は、component の出力先となるアセンブリパスです。デフォルトでは boundary と 1:1 ですが、directory: を共有する 2 つの兄弟 boundary は 1 つの組み立て済み出力(1 つの Chart.yaml、1 つの docker-compose.yaml)にまとめられます。その場合、組み立て済み出力には複数の wave のリソースが含まれることがあります。それを読み取る ArgoCD Application は、Application 内で各リソースを、そのリソースが持つ sync-wave アノテーションに従って順序付けます。対象となるのは、helm では非ゼロの wave でレンダリングされたすべてのリソース、helm-chart では $import: で読み込んだアーティファクトのみで、サブチャート自身のテンプレートは作成者が記述した内容を保持します。パスをまたぐ Application 間の順序付けは、operator の CI の責任範囲です。

ユースケース。 ある boundary の起動が別の boundary の事前の完了に依存する場合、wave による順序付けが重要になります。典型的なパターンは、wave 0 の infra boundary(VPC + データベース)、wave 1 の migrations boundary(スキーマ移行ジョブ)、wave 2 の apps boundary(移行済みスキーマを使用するアプリケーション)です。明示的な wave がない場合、3 つすべてが同時にデプロイされ、アプリケーションは移行の完了を待つ間クラッシュループに陥ります。

DAG 実行モデル、時間的な順序付けを Aggregate ではなく Release に置く理由、wave の記述単位とデプロイ可能な単位の区別など、アーキテクチャ全体の枠組みについては architecture/12-day-two-lifecycles.md §1 を参照してください。

Feature のアタッチ

Release は、Features を boundary スコープ(広範なポリシー)とコンポーネント固有のスコープ(精密なターゲティング)の両方でアタッチでき、その実行は architecture/10-compilation-pipeline.md で定義される 5 層オニオンモデルに従います。Release で宣言された Features は type、infra、uses を提供します。values は宣言できません(上記の「Schema-Level Constraints」を参照してください)。

boundary にアタッチされた Feature は任意に選んだインスタンス名をキーとし、その名前を . や .. にすることはできません。各コントリビューターに専用のディレクトリを与えるプロバイダー(terraform では modules/ 配下、helm-chart では charts/ 配下)では、boundary レベルの Feature のファイルはインスタンス名のみを名前とするディレクトリに書き出されますが、これらの名前はいずれも独立したディレクトリになりません。ビルドは Release、boundary、インスタンスを示して停止します。audit.v2 のように単にドットを含むだけの名前は通常の名前です。

features: は、Aggregate と同様に、Release の唯一のアタッチ面であり、両方のスコープで使われます。クレデンシャルは feature.aggrega.ai/kind: secret ラベルを持つ Feature であるため、Operator がアタッチするクレデンシャルも他の Feature と同じく features: の下にアタッチされ、接続上のものとまったく同じように infra でシークレットを指定します(Per-edge connection configuration を参照してください)。対象は、Aggregate がクレデンシャルなしのままにしたコンポーネント、または Aggregate がシークレットを指定せずに宣言したアタッチのサイジングです。どのスコープにも 2 つ目のアタッチ用キーワードはありません。それを宣言したドキュメントは、予期しないプロパティを示すエンベロープエラーによりロード時に拒否されます。

boundary 全体にアタッチされた feature は uses: ブロックを持つことができ、そのブロックは boundary にルーティングされたすべてのコンポーネントに投影されます。各コンポーネントは feature が指定したターゲットへの依存エッジを得て、それらのターゲットの provides を注入されます。これにより、共有された依存関係(「この boundary のすべてのコンポーネントは共有キャッシュ/コレクター/メッセージバスと通信する」)を、各コンポーネントに同じ uses: エッジを繰り返す代わりに boundary で一度だけ表現できます。Aggregate 内のサブシステムレベルの Feature アタッチも、同じように uses: をサブシステムのコンポーネント全体に投影します。uses は値ではなくトポロジーの配線宣言であるため、Release 上で許可されます。この投影は、アタッチされた Feature の実行スコープとは独立しています。FeatureRecipe が boundary ごとに一度レンダリングされる Feature でも uses: はコンポーネントごとに投影され、共有リソース自体は一度だけレンダリングされます。

単一のコンポーネントにアタッチされた feature も同じ uses: ブロックを持ち、その 1 つのコンポーネントから同じエッジを配線します。コンポーネントは指定された各ターゲットへの依存エッジを得て、それらのターゲットの provides を注入され、エッジは boundary 全体の形式とまったく同じようにアタッチを起点として記録します。この 2 つは 2 つの範囲を持つ 1 つの宣言です。boundary にアタッチすればその中のすべてのコンポーネントを配線し、コンポーネントにアタッチすればその 1 つを配線します。どちらを選ぶかは到達範囲の問題であり、配線が何をするかの問題ではありません。どちらもコンピュートを作成しません。ターゲットは Aggregate が宣言したコンポーネントをすでに指していなければならず、そうでないものはビルドを停止させます。Feature が引く接続は独自のアタッチを持ちません。そのエントリは target と inject を受け取り、そこにある features: キーは Release のロード時に拒否されます。

boundaries:
cluster:
directory: ./dist/cluster
components:
api:
features:
shared_backend:
type: core/shared-backend
uses:
backend:
primary:
target: db # a component of the assembled graph
inject:
env:
- in: DB_HOST
from: host # db's `host` provides reaches api as DB_HOST
db: {}

ターゲットの書き方。 エッジのターゲットは組み立てられたグラフのコンポーネントを指すため、ターゲットがルーティングされたサブモジュールに属する場合は常に、修飾されたドット区切りのパス(store ではなく data.store)で書きます。これは、アタッチ自体がルーティングエントリの下にあり、その components: キーがモジュールローカルである場合にも当てはまります。キーはアタッチがどのコンポーネントにあるかを示し、ターゲットはエッジがどのコンポーネントに到達するかを示し、グラフ全体で通用する名前は後者だけです。モジュールローカルな名前で書かれたターゲットはどのコンポーネントにも一致せず、宙に浮いたエッジが生じさせるのと同じ診断で停止します。

複合 Release と extends: による継承

Release は、基底 Release を指す spec.extends: を宣言でき、その基底 Release のオーサリング面を継承します。

参照は、宣言する Release と同じ場所を基準としたファイルへのパスです — ./base-release.yaml、または ../shared/base-release.yaml。Release はデプロイ側のものでありカタログにインデックスされないため、extends: の参照がカタログを通じて解決されることはありません。受け付ける形式は相対パスのみです。レジストリ座標として書かれた参照は拒否され、裸の名前も同様に拒否されます。いずれの場合も診断には相対パス形式が示されます。Manifest の extends: は近い存在ですが読み方が異なります。相対パス、または Release と同じ場所にある Manifest の裸の metadata.name を受け付けます。そのため両者の形式は互換ではなく、Manifest では解決される裸の名前もここでは解決されません。チェーンの各リンクも同じように読まれます。別のディレクトリに置かれた親 Release は、指定した Release がどこにあっても、自身と同じ場所を基準としたパスで自身の親を指定します。これは、その parameters の $import: が自身と同じ場所を基準に解決されるのとまったく同じです。パスは、Release が書くすべてのパスと同様にワークスペース内の Release を指す必要があります。ワークスペース外で指定された Release の場合は、その Release を含むディレクトリ内を指す必要があり、そのチェーンのすべてのリンクがこれに従います。外へ出るパスや、リンクによって外へ出されるパスは、それが指すファイルが読み込まれる前に拒否されます。

コンパイラは Release の読み込み時にチェーンをたどり、すでにチェーン内にあるファイルへ戻るチェーン、深さの上限を超えるチェーン、何も指さない参照を拒否したうえで、チェーンを単一の解決済み Release に畳み込みます。

継承したものは、キーごとに置き換えられます。 分割できない一つのもの(スカラー、リスト、テンプレート)に達するまで、最下層に至るまで自分の値が優先され、そうした値はそのまま受け取るか丸ごと置き換えます。継承したものを削除するには、それを null と書きます。これは拡張する Component、Feature、Manifest が従うのと同じ規則であり、一つを知っていればすべてを知っていることになります。

Release に当てはめると次のとおりです。boundaries はバウンダリ名ごと、バウンダリはキーごとに合成されます。components はコンポーネント名ごと、infra は深く、features はインスタンス名ごと、次にピラーごとに合成されます。コンポーネントの uses はソケットごと、次に接続ごとに合成され、子が書いた target は継承したものを置き換え、接続の infra はキーごとに合成され、その features はコンポーネント自身の features と同じ規則でスロットごと、次にピラーごとに合成されます。directory、subDirectory、syncWave、および Aggregate と Manifest のポインタは置き換えられるスカラーです。

継承されないものが二つあります。

  • アイデンティティと来歴。 metadata フィールドは継承されません。知っておくべきは metadata.environment です。これはすべての Release に必須であり、本質的に Release ごとのものであるため、子は親の環境ではなく自身の環境を来歴ラベルに付けてレンダリングされます。
  • Aggregate ポインタは上書きできず、継承されます。 子は aggregate: を宣言できません(スキーマは一つのドキュメント内の extends: と aggregate: を拒否します)。そのため、子は基底と同じ Developer Intent をデプロイします。

子は manifest: を省略して基底のものを継承することも、Late Binding のために上書きすることもできます。

チェーン全体で一つのルーティング形状。 boundaries: と components: は単一の Release 内で相互に排他的であり、これはチェーン全体でも成り立ちます。名前付きバウンダリを宣言する基底とトップレベルのコンポーネントを宣言する子の組み合わせは拒否され、診断には両方のファイルと両方のキーが示されます。ルーティング形状を一つ選び、最後までそれを使ってください。

ローカル開発のブリッジパターン。 代表的なユースケースは、開発者がチームの本番 Aggregate を、Aggregate をフォークしたりバウンダリのトポロジーを複製したりせずにローカルで実行することです。チームは本番 Release を公開し、ローカル Release はそれを extends: して Manifest ポインタだけを上書きし、クラウド向けの Recipes をローカル向けの同等物に差し替えます。

# production Release (committed; the source of truth for prod deployments)
apiVersion: aggrega.ai/v1beta1
kind: Release
metadata:
name: prod-release
environment: production
version: "1.0.0"
spec:
aggregate: my-app
manifest: prod-manifest
parameters:
region: us-east-1
db_size: 100Gi
out_dir: prod
boundaries:
prod:
# A directory is a TEMPLATE, not a fixed path. Writing it against a
# parameter is what lets a child render somewhere else without
# restating the boundary topology.
directory: deploy/{{ .parameters.out_dir }}
components:
api: { infra: { replicas: 5 } }
db: {}
---
# Local Release (developer-side; inherits everything, swaps the Manifest)
apiVersion: aggrega.ai/v1beta1
kind: Release
metadata:
name: local-release
environment: local
version: "1.0.0"
spec:
extends: ./prod-release.yaml
manifest: local-manifest # surgically overrides for local
parameters:
region: dev-local
db_size: 1Gi
out_dir: local # the inherited directory resolves here instead

local-release は基底のバウンダリトポロジー、Feature のアタッチメント、コンポーネントの上書きを継承します。開発者は local-release.yaml を一つ保持して aggrega build --release local-release.yaml を実行するだけで、本番の設定を複製する必要はありません。

directory: はパラメータを使って書きます。 ディレクトリは他のスカラーと同様に継承されるため、テンプレート変数を含まないディレクトリを継承した子は基底と同じパスにレンダリングされ、コマンドラインオプションでリダイレクトすることもできません。それが意図どおりであれば(たとえば Recipes だけを差し替えて出力を比較する場合)正当な使い方なので、ビルドは拒否せずにそれを報告して続行します。上記のようにディレクトリをパラメータを使って書けば、トポロジーを一か所に保ちつつ、各 Release の出力をそれぞれ独自の場所に送れます。

複数ファイルによるパラメータのレイヤリング。 Release の継承は、複数ファイルによるパラメータのレイヤリングを行う場所です。基底 Release が共通のパラメータセットを提供し、環境ごとの子が基底を extends: して異なるスロットを上書きします。

# base-release.yaml — common parameters
spec:
aggregate: my-app
parameters:
timeout_seconds: 30
feature_flags: { dark_mode: true }
---
# prod-release.yaml
spec:
extends: ./base-release.yaml
manifest: prod-manifest
parameters:
feature_flags: { dark_mode: false } # override one nested key
---
# staging-release.yaml
spec:
extends: ./base-release.yaml
manifest: staging-manifest

各子には、基底から継承したパラメータと自身のパラメータがマージされて見えます。マップ値のパラメータは子のキーを優先してディープマージされ、スカラー値のパラメータは子が置き換えます。子が null と書いたキーは、空の値に設定されるのではなく削除されます。

基底がパラメータをインポートしても、子は個々のキーを上書きできます。 上記の parameters: で説明した二つのオーサリングモード(インライン、または単一の $import:)は、チェーンではなく一つのドキュメントに関する規則です。チェーン上の各 Release はどちらか一方のモードを宣言し、それぞれのインポートはチェーンが畳み込まれる前に、その Release を含むディレクトリを基準に解決されます。そのため、共有ファイルをインポートする基底と、いくつかのキーをインラインで書く子は、二つのインラインブロックの場合とまったく同じようにキーごとに合成されます。

# base-release.yaml — parameters arrive from a shared file beside it
spec:
aggregate: my-app
parameters:
$import: ./shared-params.yaml # tier: prod, region: eu
---
# local-release.yaml — overrides one key, inherits the rest
spec:
extends: ./base-release.yaml
manifest: local-manifest
parameters:
tier: local # region stays eu, from the imported file

エラーモード。 循環する extends: チェーン、存在しない親ポインタ、子側での aggregate: の宣言はいずれも、問題の Release とスキーマレベルの違反を示す明示的な診断とともにワークスペースの読み込みを停止させます。エラーごとのメッセージ形式については errors/fatal-halts.md を参照してください。