Aggregate
Aggregate エンティティの概念上の役割(Domain 1 — Developer の宣言的なトポロジーの設計図)は architecture/04-entity-taxonomy.md で説明しています。合成パターン(サブシステム、ネストされた aggregate、Zero-Port Convention、Parameter Hoisting)は architecture/06-data-taxonomy-and-composition.md で説明しています。このページでは Aggregate のカタログ作成面、具体的にはカタログ配布向けの再利用可能な Aggregate モジュールの作成について説明します。
Component スコープ:デフォルトの subsystem
Aggregate は、コンポーネントを サブシステム に編成します。サブシステムとは、横断的な関心事(データ層、エッジ層など)のための名前付きのグループで、それぞれ独自のアノテーションのカスケードを持ちます。ほとんどの Aggregates はグループを 1 つしか持たないため、特別な記述は必要ありません。
単一スコープ(デフォルト)。 コンポーネントを spec.components: の直下に記述し、subsystems: ブロックを省略します。
spec: components: api: type: core/server:1.0.0 worker: type: core/worker:1.0.0コンパイラはこれらを合成された default サブシステムにまとめます。ノードの識別子は変わりません。api は api のままで、default.api になることはありません。そのため、この方法で記述した Aggregate は明示的な単一サブシステムの形式と相互に置き換え可能であり、これを参照する際(uses: のターゲットや診断メッセージ)には修飾なしの spec.components.<name> パスを使用します。合成されたスコープはエクスポートされる IR に正確に記録されます(合成サブシステムであることを示すマーカーを持ちます)が、作成者が記述したり読んだりするパスには一切現れません。
複数スコープ。 コンポーネントが異なる横断的なグループに分かれる場合は、subsystems: の下に名前付きのサブシステムを宣言します。各サブシステムは独自のコンポーネントとアノテーションのカスケードを持ち、さらにサブシステムを入れ子にすることもできます。
相互排他性。 spec.components: と spec.subsystems: は Aggregate のルートで相互に排他的です。どちらか一方のみを記述し、両方を記述することはできません。両方を宣言したドキュメントは、読み込み時にエンベロープエラーで停止します。(開発者が明示的に default と名付けたサブシステムは、通常の宣言されたサブシステムであり、修飾された spec.subsystems.default.components.<name> パスで参照されます。合成スコープの省略は、名前ではなく由来に基づいて行われます。)
再利用可能な Aggregate モジュール
Aggregates は、Release がビルドするルートの Aggregate としても、再利用可能なモジュールとしても機能します。親 Aggregate は子 Aggregate をコンポーネントとまったく同じように宣言し、parameters を渡すことができます。密結合を防ぐため、子 Aggregates は exportedComponents: コントラクトを公開し、安定した公開インターフェース名を確立します。親はこのインターフェースを通じてのみモジュールのコンポーネントに到達します。uses: のターゲットはモジュール名、ドット、そのエクスポートされたエイリアスの 1 つからなり、コンパイラはエイリアスが指す内部コンポーネントへエッジを配線します。それ以外の名前 (モジュール内部でのコンポーネント名、またはその中にネストされたモジュールへのパス) でモジュールの内部に到達しようとするターゲットは、モジュールとそれがエクスポートするエイリアスを示してビルドを停止させます。A uses target names a module’s component the module does not export (ターゲットが、モジュールがエクスポートしていないモジュールのコンポーネントを指定している) を参照してください。
明示的な exportedComponents: リストを使う理由。 モジュールの作成者は、そのコンポーネントのうちどれが公開インターフェースを構成し、どれが実装の詳細にとどまるかを決めます。親はリストが公開するものしか指定できないため、公開された各名前が引き続きいずれかのコンポーネントを指している限り、モジュールの内部をリファクタリングしても (コンポーネントの名前変更、1 つのコンポーネントの 2 つへの分割、ワーカーのマネージドサービスへの置き換えなど) どの親も壊れません。リストのコストは公開するコンポーネントごとに 1 エントリであり、インポート側が使うべき名前がコンポーネント自身の名前である場合は、その名前で公開できます (store: store)。同じ規則はコンポジションの内部でも成り立ちます。モジュールは、インポートするモジュールに、そのモジュールのエクスポートされたエイリアスを通じて到達します。Release は 1 つのモジュールの 2 つのコンポーネントを互いに配線できます。その接続はどのモジュールのインターフェースもまたがないためです。
ネストしたモジュールのインターフェースの再エクスポート。 exportedComponents: のエントリは、直接宣言されたコンポーネントではなく、ネストしたサブ Aggregate のエクスポート済みエイリアスを指すこともできます。これは、モジュールがインポートしたモジュールの一部を、自身のインターフェース名のもとで、必要に応じて新しい名前で再公開するものです。そのような再エクスポートされたエイリアスを対象とする uses: エッジは、チェーンを推移的にたどって具体的な内部ノードに解決されます。そのため、モジュールはより深いモジュールを、その内部構成を公開することなく自身の公開インターフェースに組み込めます。また、利用側は対象がどれほど深くネストしているかを知る必要がありません。安定したインターフェースという規律はすべての段階で保たれます。各モジュールは、公開すると選んだものだけを再エクスポートします。どの内部ノードにも解決されない再エクスポート対象は、直接の宙に浮いた対象と同じように明示的に停止し、自身に戻って閉じる再エクスポートチェーンは、際限なくたどられることなく拒否されます。
モジュールの宣言は、Aggregate の宣言と同じようにチェックされます。 モジュールのドキュメントは、それをインポートする構成がビルドされるときにのみ読み取られ、その宣言はその時点から、ネストの深さにかかわらずチェックされます。モジュールのコンポーネント自身の inject: ブロックは、その型の spec.inject 許可リストに従うほか、同じ配信キーを 2 回要求することを禁じるルールと、型が公開していないキーを読み取ることを禁じるルールにも従います。モジュール自身の subsystem の 1 つに記述されたアタッチメントは、その Feature が宣言するソケットのみを指定でき、モジュールが提供するコンポーネントに対して Release が記述するアタッチメントも同様です。
モジュールの subsystem アタッチメントは、そのコンポーネントに及びます。 モジュールが自身の subsystem の 1 つにアタッチした Feature は、Aggregate における subsystem アタッチメントとまったく同様に、モジュールがその subsystem の下に宣言するすべてのコンポーネント(ネストされた subsystem のものを含む)にカスケードします。そして、それらのコンポーネントにのみ及び、インポート側の Aggregate で同じ名前の subsystem の下にあるコンポーネントに及ぶことは決してありません。これはコンポーネント自身のアタッチメントの直後に、外側の subsystem から内側の順に評価されます。両方が書き込むフィールドでは、コンポーネント自身の同名のアタッチメントが優先され、それが省略したフィールドは subsystem の値を保持します。到達した各コンポーネントは、それを Feature の appliesTo に照らしてチェックします。モジュール自身の宣言に関する指摘は、モジュールとそのドキュメント内のキー(たとえば .spec.subsystems.<subsystem>.features.<attachment>)を示すため、修正はインポートする Aggregate ではなく、宣言があるモジュールで行います。
カタログ上の配置
再利用可能な Aggregate モジュールは、aggregate/ 種別ディレクトリの下、その metadata.name が示すパスにセグメントごとに対応して配置され、末端にはバージョンディレクトリが置かれます。
aggrega-catalog/└── aggregate/ └── {module-name}/ # the module's metadata.name, segment for segment └── {version}/ # the module's metadata.version └── aggregate.yaml # The module definitionモジュール名には、ベンダーまたは作成者を表す先頭の {publisher} セグメントを付けられます(標準ライブラリには core、企業には acme など)。公開されている標準ライブラリのモジュールはこの形式で命名されており、core/agenta は aggregate/core/agenta/1.0.0/aggregate.yaml に配置されます。単一のトークンからなる名前は 1 階層浅い aggregate/{module-name}/{version}/aggregate.yaml に配置されます。どちらの形式も正しい形式です。名前は作成者が書くものであり、ディレクトリはそれを反映します。この反映はカタログの慣例であり、コンパイラが検査するものではありません。モジュールは、ファイルの置き場所ではなく、宣言した名前によって見つけられます。
OCI URI: hub.aggrega.ai/aggregate/{module-name}:{version}(小文字化されます)。したがって、core/agenta という名前のモジュールは hub.aggrega.ai/aggregate/core/agenta:1.0.0 に、db-module という名前のモジュールは hub.aggrega.ai/aggregate/db-module:1.0.0 に公開されます。
モジュールパターン
子モジュール(aggregate/child-database-module/1.0.0/aggregate.yaml、hub.aggrega.ai/aggregate/child-database-module:1.0.0 として公開):
apiVersion: aggrega.ai/v1beta1kind: Aggregatemetadata: name: child-database-module version: 1.0.0spec: components: internal-pg-primary: type: core/postgres:1.0.0
exportedComponents: # The Public Contract (Written once by the module author) primary_db: "internal-pg-primary"親 Aggregate:
apiVersion: aggrega.ai/v1beta1kind: Aggregatemetadata: name: parent-app version: 1.0.0spec: aggregates: finance-db-subsystem: type: child-database-module:1.0.0
components: billing-api: type: core/python-worker:1.0.0 uses: databases: - finance-db-subsystem.primary_dbモジュールラベル
Aggregate が再利用可能なモジュールとしてカタログに公開される場合、YAML エンベロープに metadata.labels を持たせることができます。たとえば aggregate.aggrega.ai/tier: infrastructure や aggregate.aggrega.ai/compliance: pci-dss です。これらのラベルはモジュールのアイデンティティを記述し、公開されたモジュールドキュメントに保持されますが、現時点でそれを読み取るコマンドはありません。カタログ検索は Aggregates をインデックス化せず、ビルドグラフはモジュールのラベルもカタログ名も保持しないため、ガバナンスポリシーはコンポーネントをその由来のモジュールによって選択することはできません。
重要な区別。 Aggregate のラベルは、カタログにおける再利用可能なモジュールのアイデンティティを記述します。これらは子のコンポーネントノードへカスケードしません。コンポーネントのラベルは、Domain 2 の Component カタログエンティティからのみ与えられます。開発者が aggregate.aggrega.ai/tier: infrastructure というラベルの付いたモジュールをインポートしても、そのモジュール内の個々のコンポーネントは、自身のカタログで定義されたラベル(例: component.aggrega.ai/type: stateful-server)だけを保持します。Aggregate のラベルが IR ノードの labels 辞書に注入されることはありません。
Composite Aggregates / モジュールパターンの詳しい説明(Components にサブコンポーネントを持たせないというルールを含む)と、subsystems による横断的なグルーピングの仕組みについては、architecture/06-data-taxonomy-and-composition.md §6 を参照してください。型付きの parameters 契約を記述する仕組みについては、vocabulary/data-pillars を参照してください。
型付きパラメータコントラクト
Aggregate の spec.parameters: ブロックは、Release が満たすパラメータの型付きコントラクトを宣言します。各パラメータスロットは、宣言された type、省略可能な description、省略可能な default、省略可能な値空間の制約、および(オブジェクト型のスロットの場合)ネストされた構造を持ちます。コンパイラは解決時、パラメータの補間が実行される前に、Release が指定した各値をコントラクトに照らして検証します。
apiVersion: aggrega.ai/v1beta1kind: Aggregatemetadata: name: web-app version: 1.0.0spec: parameters: region: type: string description: Cloud region the deployment targets enum: [us-east-1, us-west-2, eu-west-1, ap-northeast-1] default_locale: type: string description: Default UI locale presented to end users enum: [en-US, en-GB, fr-FR, ja-JP] default: en-US enable_debug: type: boolean description: Toggle verbose request logging default: false feature_flags: type: object description: Per-feature enablement map valuesType: { type: boolean } default: {} allowed_hosts: type: array description: Hostnames the ingress accepts items: { type: string, format: hostname } min: 1 default: ["web-app.example.com"]
components: web: type: core/web-server:1.0.0 values: default_locale: "{{ .parameters.default_locale }}" region: "{{ .parameters.region }}" debug: {{ .parameters.enable_debug }}各参照のクォートは意図的なものです。巻き上げられた値がどの型で届くかは、クォートによって決まります。templates/parameters-context.md を参照してください。
パラメータスロットの語彙
型付きの parameters: ブロックは、コンパクト形式の語彙を受け付けます。type、description、default、enum、min、max、pattern、minLength、maxLength、format、validate と validateMessage (カスタムチェックとそれが報告するメッセージ)、items (配列用)、properties (オブジェクト用)、valuesType (型付き値のマップ用)、および required: true (スロットごとのマーカー) です。このうち 3 つのキーワード、items、valuesType、および properties 配下の各エントリは、単純な設定値ではなくコントラクトを値として取ります。パラメータスロットでは、そのネストされたコントラクトは周囲のスロットと同じ型付き形式で記述します。valuesType: boolean ではなく valuesType: { type: boolean } です。補間の前に、コンパイラはマージされたパラメータマップをこれらの宣言に照らして直接チェックします。どのスロットも宣言していないパラメータは拒否され、required: true が指定されたスロットを Release も default も埋めない場合はビルドが停止し、指定されたすべての値は、スロットで宣言された type、enum への所属、文字列スロットでは minLength と maxLength の境界、pattern の正規表現および format、そして min と max の境界 (数値スロットでは値、文字列スロットでは長さ、配列スロットでは要素数) に照らしてチェックされます。オブジェクトと配列のスロットは再帰的に処理されます。properties 配下の各エントリと items に対する各要素は同じ方法でチェックされ、properties が名前を挙げていないキーは valuesType コントラクトが管理し、どの宣言も名前を挙げていないネストされたキーは拒否されます。schema: ピラーでこれらのキーワードの綴りが異なる箇所を含む、キーワード語彙の全体については vocabulary/compact-form-authoring.md を参照してください。
以下のキーワードは、Release の値が読まれる前に宣言そのものに対してもチェックされます。そのため、何も制約できないスロットは、どの Release もそれを指定していない場合でもビルドを停止させます。
- 長さの境界は 0 以上です。 パラメータ自身の宣言にある負の
minLengthまたはmaxLengthは、Aggregate の読み込み時に Aggregate のスキーマによって拒否され、そのパラメータとキーが示されます。ネストされたコントラクト(items、propertiesまたはvaluesTypeの配下)の内部では、長さの境界は記述どおりに読まれ、Aggregate の読み込み時にその下限は適用されません。そのため、そこでも 0 以上で記述してください。負のminLengthは何も制約せず、負のmaxLengthはすべての値を拒否します。 minとmaxは何かを制約しなければなりません。 ブール型またはオブジェクト型のスロットでは、この組は何も制約しないため、そこに書かれたminやmaxは Aggregate の読み込み時に、パラメータとキーを示して拒否されます。- パターンはコンパイルできなければなりません。 すべての
patternは、パラメータコントラクトが読まれる際に正規表現としてコンパイルされます(スロット自体でも、任意の深さのネストされたコントラクト内部でも)。コンパイルできないものは、パラメータ、パターン、および理由を示して拒否されます。コントラクトは、その Aggregate に到達するすべてのビルド、プル、Release の検証で読まれます。それが Release 自身の Aggregate であっても、その Aggregate がインポートするモジュールであっても同様です。その後の値チェックでは、指定された各値を同じコンパイル済みの正規表現と照合します。 - フォーマットはコンパイラがチェックするものでなければなりません。
formatには、email、uri、hostname、ipv4、ipv6、uuid、date-time、dateのいずれかを、JSON Schema と同じ綴りで指定します。それ以外の名前(emialのような綴り間違いや、passwordのように JSON Schema が定義していない名前)は、Aggregate の読み込み時に、パラメータを示しサポートされる名前を列挙して拒否されます。スロット自体では Aggregate のスキーマによって、任意の深さのネストされたコントラクト内部ではパラメータコントラクトが読まれる際に拒否されます。その後、指定されたフォーマットを満たさない文字列は、パラメータ、値、およびフォーマットを示して拒否されます。各名前が何をチェックするかはvocabulary/compact-form-authoring.mdにあります。
オブジェクト型および配列型のパラメータ
パラメータスロットは、ネストされたオブジェクトや型付き要素の配列を含め、コンパクト形式がサポートする任意の型を受け付けます。
spec: parameters: database_config: type: object description: Database connection configuration properties: host: { type: string, required: true } port: { type: integer, min: 1, max: 65535, default: 5432 } ssl_mode: { type: string, enum: [disable, require, verify-full], default: require } pool_size: { type: integer, min: 1, max: 100, default: 10 }
metric_labels: type: array description: Custom Prometheus labels to attach to scraped metrics items: type: object properties: name: { type: string, required: true } value: { type: string, required: true }Release はオブジェクト型のパラメータを構造化された YAML で満たします。コンパイラは補間の前に、その構造を宣言されたスキーマに照らして検証します。オブジェクトのフィールドを参照するテンプレートは、標準の Go テンプレート構文を使用します:{{ .parameters.database_config.host }}、{{ .parameters.database_config.port }} など。
パラメータ契約の検証
契約そのものは、読み込まれた時点で最初にチェックされます。これは上記「Parameter slot vocabulary」で説明した長さの上下限と pattern のチェックです。その後、コンパイラはパラメータ処理の中で 3 つのサブステップを実行します。
- デフォルトの補完 —
default:が定義され、Release が値を指定していないスロットには、そのデフォルトが入ります。ネストしたオブジェクトのパラメータでは、親スロットが省略された場合、明示的に空の場合、部分的に記述された場合の 3 通りの記述セマンティクスがあります。親を省略すると子のデフォルトが補完され、親を{}と記述すると明示的な空が保持され (子のデフォルトは抑止されます)、親を空でないマップとして記述すると Release が指定しなかった子だけが補完されます。YAML の例と「各形式をいつ使うか」の判断ガイドについてはtemplates/parameters-context.mdを参照してください。 - 契約の検証 — マージされたマップ内の各値は、Release が指定したものか
default:が補完したものかにかかわらず、宣言されたtype/enum/min/max/pattern/ ネスト構造の制約に対して検証されます。検証に失敗するとビルドが停止し、問題のあるスロット、指定された値、違反した制約を示す明確なエラーが出力されます。default:のない必須パラメータが欠けている場合も、スロット名を示して同様に停止します。 - 補間 — コンパイラは Aggregate のテキスト全体を YAML として読み込む前にテンプレートとして評価し、すべての
{{ .parameters.<slot> }}参照 (通常は component / feature / sub-aggregate のvalues:文字列内にあります) を解決済みの値で置き換えます。テキスト中のそれ以外の{{もテンプレート構文として読まれるため、独自の二重波括弧を含む値 (たとえばフロープラットフォームがエクスポートした定義など) では、独自の二重波括弧を含むテキストで説明しているとおり、各{{を{{"{{"}}と記述します。このパスの後、値テンプレートのサーフェスは補間済みのリテラルを受け取り、テンプレートコンテキストに.parametersは渡されません。
マージされたパラメータマップは、パステンプレートの評価をサポートするため、レンダリングの間ずっと保持されます。Release の境界でオペレーターが記述した directory: および subDirectory: テンプレートは、レンダリング時に閉じた許可リストに基づいて .parameters.<slot> を直接読み取ります。パスの出力には環境ごとの成果物レイアウトのためにリージョンや環境の語彙が必要であり、この非対称な付与によって、そのオペレーターの関心事を Aggregate の values を経由させることなくオペレーターのサーフェス内にとどめます。マップはすべてのレンダリングフェーズが完了するまで読み取り可能であり、解決の対象となったコンパイルからのみ到達できます。開発者が記述した values: を利用する recipe は補間後の文字列を参照し、パステンプレートはレンダリングを通じて生きた .parameters データを参照します。パステンプレートの利用可否マトリクスについては templates/expansion-matrix.md の 3 行目を、パステンプレート変数の許可リストについては path-template-variables.md を参照してください。
より広範なパラメータ引き上げのチェックリスト (Aggregate の宣言 → values での参照 → Release による充足 → Recipe による利用) とピラーをまたぐ仕組みについては、vocabulary/data-pillars.md の §「Parameters」と §「The parameter-hoisting checklist」を参照してください。補間中に公開されるテンプレートコンテキストのフィールドとパステンプレートの例外については、templates/parameters-context.md を参照してください。
uses エッジは Aggregate が宣言する呼び出しです
uses エッジは、あるコンポーネントが別のコンポーネントを呼び出すことを示す Aggregate の宣言です。コンパイラはターゲットが公開する値を呼び出し元に渡しますが、何も制限しません。エッジはそれ自体では呼び出し元を許可することも、他の誰かを拒否することもなく、エッジなしでターゲットのアドレスに到達するワークロードもそのまま到達できます。
コンポーネントを誰が呼び出せるか、またそのコンポーネントが何を呼び出せるかを制限するのはオペレーターの判断であり、Release で環境ごとに行います。Release が標準ライブラリカタログの core/caller-allowlist Feature をコンポーネントにアタッチすると、ビルドは、そのコンポーネントを指す uses エッジを持つコンポーネント、そのコンポーネント自身の Pod、およびアタッチメントが指定するソースのみを許可するネットワークポリシーを書き出します。その送信側の対応物である core/egress-allowlist は、アタッチ先のコンポーネントが、自身の uses エッジが指すコンポーネント、自身の Pod、クラスターの DNS、および Release が列挙するアドレス範囲にのみ到達できるようにします。これにより、Aggregate がエッジとして宣言していない呼び出しは、クラスターのネットワークプラグインがネットワークポリシーを適用する環境であれば、どちらの端でもクラスターによって拒否されうるようになります。したがって、値を注入しない呼び出しも含め、コンポーネントが行うすべての呼び出しについてエッジを書いてください。欠けているエッジは、保護されたコンポーネントが拒否しうる呼び出しです。model-server-caller-allowlist では、前段のゲートウェイを通じてのみ到達できるモデルサーバーを示しています。
接続自身のアタッチメント: uses エントリ上の features
component が冗長な uses: 形式で描く接続はそれ自体が 1 つのエントリであり、target、inject、values と並んで、features: の下に アタッチメント を持つことができます。各アタッチメントは ソケットが宣言するスロット をキーとします。利用側の Component は、ソケットの featuresSchema に、そのソケットを通して配線されるすべての接続が埋められるスロットを列挙します(Topology Sockets を参照)。これにより、1 つの component が到達する component ごとに異なる認証情報を保持できます。たとえば、2 つのモデルを 2 つのキーで呼び出すゲートウェイや、モデルに独自のキーを提示するエージェントです。
spec: parameters: openai_key_secret: { type: string } components: router: type: core/gateway/litellm # its `models` socket declares a `credential` slot values: { model: gpt } # the alias it publishes as its model uses: models: gpt: target: gpt features: credential: type: core/referenced-secret values: origin: "{{ .parameters.openai_key_secret }}" key: api-key plain: target: plain # this connection carries no attachment gpt: type: core/ai-model/openai values: { model: gpt-4o-mini } plain: type: core/ai-model/ollama values: { model: llama3.1 }接続上のアタッチメントは、type(必須)、任意の description、および Feature 用の values を持ちます。uses と inject は持ちません。接続上のアタッチメントは入れ子にならず、その素材が利用側にどう届くかは、inject ブロックではなく利用側 component の Recipe が決めることです。どちらかを記述したドキュメントは、読み込み時にそのキーを示して拒否されます。
ソケットが宣言するスロットのみ。 ソケットの featuresSchema に列挙されていない名前のアタッチメントは、読み込み時にビルドを停止させ、接続、ソケット、component、およびソケットが実際に宣言しているスロットを示します。また、その名前がいずれかのスロットと 1 編集の差しかない場合は、意図された綴りの候補としてそのスロットも示します。埋められたスロットは、各接続上でそのスロット自身の宣言に照らして検査されます。Feature のラベルが満たさない selector はこのエントリで停止し、いずれかの接続で空のままの required スロットは、その接続を示して停止します。スロットを宣言しないソケットは、その接続上でアタッチメントを受け付けません。アドホックなソケット(Component が宣言せずに Aggregate が配線するソケット)もスロットをまったく宣言しないため、同様に受け付けません。サブモジュールが提供する component も同じ規則に従い、検出結果はサブモジュール自身のドキュメントを指します。A connection carries an attachment under a name its socket declares no slot for(接続が、そのソケットがスロットを宣言していない名前のアタッチメントを持っている) を参照してください。
Feature が描く接続はアタッチメントを持ちません。 アタッチされた Feature 自身の uses: ブロックは、component 上でもサブシステム上でも同じ形で記述しますが、ドキュメントの読み込み時に features: を拒否します。そのような接続が必要とする認証情報は、Feature が自身の featuresSchema で宣言するスロットを埋め、Feature と並んでアタッチされます。A Feature’s Own Credential を参照してください。
アタッチメントが取る名前。 各接続アタッチメントは 利用側 component のアタッチメントとなり、<alias>.<slot> と命名されます。これは接続が記述されたエイリアス、ドット、スロットを連ねたもので、上の例では gpt.credential です。ドットはコンパイラが合成する名前のために予約された区切り文字であり、Aggregate 内のエイリアス、スロット、アタッチメント名には含められません。そのため、合成された名前が component 自身の features: ブロックに記述された名前と一致することはありません。Release が component やバウンダリ上でこの名前を記述すると拒否されます(Per-edge connection configuration を参照)。これは Manifest のインスタンスごとの階層がアタッチメントのキーとする名前(Flat URI mapping を参照)であり、診断と IR グラフが報告する名前であり、アタッチメントの FeatureRecipe が .attachment_name として読む値です(Names derived from a connection’s attachment を参照)。
そこからは他のアタッチメントと同様に解決されます。Manifest がその Feature 型を FeatureRecipe に結び付け、その values は Feature のスキーマに照らして検証され(失敗はそれを記述した接続エントリで報告されます)、その FeatureRecipe はアタッチメント自身の values と infra に対してレンダリングされます。component 自身のアタッチメントとは次の 2 点が異なります。
- 利用側 Recipe の
.featuresには含まれません。 この柱は component 自身のブロックに記述されたアタッチメントのみを持つため、自身のアタッチメントを型で.featuresから探す Recipe に接続の認証情報が渡されることはありません。Recipe は接続のアタッチメントを接続自体から、.context.uses.<alias>.features.<slot>で、.featuresと同じ形(解決済みのprovidesを含む)で読みます(A connection’s attachments を参照)。 - 利用側にのみ反映されます。 ターゲットのレンダリング出力は、そこに到達する接続が何を持っていても同じです。
記述されたブロックのグラフ上の写し。 IR グラフは各 component の uses: ブロックを記述どおりに保持し、そこでは接続アタッチメントは type と description を保持し、values は一切保持しません。値は利用側が持つアタッチメント上に一度だけ現れ、Feature が機密と宣言した値はそこで伏せられます。
Release は、ここで宣言されたアタッチメントを infra でサイズ設定したり、到達する接続上に独自のアタッチメントを追加したりできます。Per-edge connection configuration を参照してください。
component またはモジュールを無効にする: active:
component インスタンスとサブ aggregate モジュールは、それぞれ active: トグルを受け付けます。このトグルは、そのエンティティをコンパイルされたトポロジーに含めるかどうかを決定します。省略するとエンティティは存在します。これがデフォルトであり、通常のケースです。
spec: parameters: enable_cache: type: boolean default: false components: api: type: core/server:1.0.0 redis: type: core/redis:1.0.0 active: "{{ .parameters.enable_cache }}" aggregates: reporting: type: my-catalog/reporting-module:1.0.0 active: falseブール値を直接書くか、ブール値に解決される .parameters 上のテンプレートを書きます。トグルが存在する理由はテンプレート形式にあります。これにより Release はパラメータを満たすことでエンティティの有無を決定できるため、1 つの Aggregate で、デプロイする部品が異なる複数の環境をカバーできます。しかも Release が、Aggregate の宣言していないものを宣言する必要はありません。
false のトグルが取り除くもの。 エンティティはグラフが構築される前に刈り込まれ、その刈り込みは連鎖します。component は自身の uses: エッジとアタッチされた Features を一緒に取り除き、モジュールはそれが提供したすべて、つまりその component、それらのエッジ、それらのアタッチメントを一緒に取り除きます。刈り込まれたエンティティがもたらしたものは何もレンダリングされません。刈り込みが及ばないのは、残ったどこかからのそのエンティティへの参照であり、それが次の段落の内容です。
刈り込まれた component をまだ参照している、残った component はビルドを停止させます。 api が redis への uses: エッジを宣言しており、redis が無効にされている場合、ビルドはエッジを消失させずに停止します。消失させると、デプロイ時に api の注入値が何の通知もなく空になってしまうためです。この環境にどちらが属するかを決めてください。ターゲットを再び有効にするか、ペアが一緒に外れるよう同じパラメータでコンシューマーを制御するか、コンシューマーの uses: ブロックからエッジを削除します。
記述されたトグルは boolean に解決されなければならず、空の値は boolean ではありません。 トグルはテンプレートが解決された後に厳密に読み取られ、boolean として解析できないリテラルは、何らかの値にデフォルト設定されることなくビルドを停止させます。注意すべきケースは、値を持たないパラメータを読み取るトグルです。このトグルは何も返さずに解決され、その「何もない」を「存在する」と解釈すると、まさにそのパラメータで制御しようとしたエンティティがデプロイされてしまいます。そのため、active: の後に何も書かないことは、キーを省略することと同じではありません。存在する状態にデフォルト設定されるのは、誰も記述していないトグルだけです。すべての環境が値を持つように spec.parameters でパラメータに default: を与えるか、Release でパラメータを満たしてください。エンティティを無条件に存在させるには、値を空にするのではなく active: キーを削除してください。この停止については、停止条件のリファレンスの「An active: toggle does not resolve to true or false(トグルが true または false に解決されない)」で説明しています。
無効にされた component は、Release から引き続き名前で参照できます。 Release は境界の中でそれを引き続き名指しでき、これは意図的なものです。component を無効にするのはオーサリング上の行為であり、それを設定する Release が同じ編集で書き直されることは想定されていません。
サブシステムとコンポーネントのアノテーション
サブシステムとコンポーネントインスタンスは、どちらも annotations: フィールドを持ちます。Aggregate 上で開発者が記述したアノテーションは、Aggregate 側のアノテーションカスケードを駆動します。サブシステムのアノテーションは、ネストされたすべてのサブシステムと、含まれるすべてのコンポーネントに伝播し、より近いレベルの値がキー単位で上書きします。Manifest の mappings.features.annotations マップは、ビルド時にアノテーションキーを合成 Feature アタッチメントへ変換するバインディングを宣言します。Aggregate-as-Authoring-Surface 不変条件により、これらのアノテーションはバインディングの maps.values パスを経由するルーティングに限定されます。maps.infra パスのみを宣言するバインディングは、Aggregate 側ではなく Release 側から発火します。
値の形
各アノテーションキーは 4 つの形のいずれかを取り、「何も言わない」「値を宣言する」(スカラーまたは構造化オブジェクト)「オプトアウトする」を区別します。
- キーなし — そのスコープはこのアノテーションに値を宣言しません。ネストされたサブシステムと含まれるコンポーネントは、祖先スコープからバインディングを継承します。
- スカラー文字列 — 単一の値です。Manifest のバインディングは合計でちょうど 1 つのパスを宣言する必要があり、スカラーはそのパスへルーティングされます。
- 構造化オブジェクト — サブキーからサブ値へのマップです。オブジェクトの各サブキーは、Manifest バインディングの
mapsを経由して、宣言された柱にある対応する Feature スキーマフィールドへルーティングされます。 - 明示的な YAML
null— そのスコープは、このキーについて継承したバインディングを自身のサブツリーから取り除きます。兄弟のコンポーネントと兄弟のサブシステムは継承を保持し、オプトアウトしたスコープだけがバインディングを失います。
spec: subsystems: data: annotations: feature.myco/db-pool: "shared-pool" # scalar value — propagates to api and worker components: api: type: core/server:1.0.0 # inherits feature.myco/db-pool: "shared-pool" worker: type: core/server:1.0.0 annotations: feature.myco/db-pool: null # opts out for this component only special: type: core/server:1.0.0 annotations: feature.myco/db-pool: "vip-pool" # closer-level override複数フィールドを持つ Features の構造化値
設定可能なフィールドを複数持つ Feature には、構造化アノテーション値が適しています。1 つのアノテーションキーが、1 回の宣言で複数の Feature スキーマフィールドの値を運びます。Aggregate 側は、バインディングマップの柱が values であるサブキーのみを発火します。infra へルーティングされるサブキーは Release 側のアノテーションに属します。
spec: subsystems: data: annotations: feature.myco/db-pool: db_name: "prod-db" read_replicas: 5 components: api: type: core/server:1.0.0 annotations: feature.myco/db-pool: db_name: "api-override" # closer-level override at subkey granularity # read_replicas not listed → inherits 5 from parent analytics: type: core/server:1.0.0 annotations: feature.myco/db-pool: read_replicas: null # per-subkey opt-out構造化値はサブキー単位のディープマージでカスケードします。より近いレベルのサブキーが親のサブキーを上書きし、サブキーに明示的な null を置くと、兄弟のサブキーは残したまま、そのスコープについて継承したサブキーを抑制します。構造化値の詳しい説明 — Release 側の infra サブキーとの両側の合成、サブキー単位の型検証、type が宣言されていないスキーマフィールドに対する緩和されたデフォルトの扱い — については、providers/well-known-annotations.md の §「Structured annotation values」を参照してください。
キーごとの独立性
各アノテーションキーは、それぞれ独立して継承、上書き、オプトアウトされます。annotations.feature.myco/db-pool: null を宣言するコンポーネントは、そのキーだけをオプトアウトします。外側のサブシステムから継承した他のキーは、引き続きそのコンポーネントに伝播します。同じサブシステム内の兄弟コンポーネントは、それぞれのアノテーションマップを独立して保持します。あるコンポーネントのオプトアウトは兄弟に影響しません。
トップレベルのコンポーネントのアノテーション
トップレベルのコンポーネント(サブシステム内ではなく spec.components の直下に宣言されたもの)は、継承されるカスケードを持ちません。その annotations: フィールドは、コンポーネントのスコープに直接値を宣言します。展開時には、宣言された各アノテーションのうち、Manifest が一致するバインディングを持つものから Feature アタッチメントが合成されます。
バインディングに適用される Aggregate 側のカスケード規則、側と柱の区分、そしてバインディングがアノテーションを合成 Feature アタッチメントへ変換するエンドツーエンドの例については、providers/well-known-annotations.md の §「Aggregate-side annotation cascade」を参照してください。
YAML アンカーパターン(defs: ブロック)
Aggregate のスキーマは、ルートレベルにオプションの defs: ブロックを受け付けます。これは YAML 文字列のリストで、標準の YAML アンカー(&anchor)と参照(*anchor)の置き場所としてのみ使われます。このブロックの内容をコンパイラが読むことはありません。このブロックは、作成者がアンカー定義を一か所で宣言し、Aggregate の残りの部分全体からそれを参照できるようにするために存在します。これにより、コンパイラが反復処理するフラットな O(1) の辞書を失うことなく、繰り返される値を DRY に保てます。この仕組みは、Manifest エンティティにある同等の defs: ブロックと同じものです。
apiVersion: aggrega.ai/v1beta1kind: Aggregatemetadata: name: anchored-app version: 1.0.0defs: - &default_log_level "info"spec: components: primary: type: core/compute/api-server:1.0.0 values: log_level: *default_log_level secondary: type: core/compute/python:1.0.0 values: log_level: *default_log_levelアンカーは YAML のパース時に解決されるため、コンパイラが values ブロックを読む時点では *default_log_level は文字列 "info" になっています。defs: ブロックはアンカー定義を置く慣例上の場所です。YAML ではアンカーをどこにでも宣言できますが、一か所にまとめておくと Aggregate の残りの部分が読みやすくなります。このブロックはオプションです。アンカーを必要としない Aggregates では、このブロックを完全に省略します。