Component
Component エンティティの概念上の役割(Domain 2 における抽象的な計算ノードのインターフェース)は architecture/04-entity-taxonomy.md で説明しています。このページでは Component のオーサリング面を扱います。具体的には、Architect が運用上のベースオントロジーの上に認知的アイデンティティを重ねるために使う Semantic Label Taxonomy、データの柱のための schema: 宣言、トポロジーソケットとアタッチメントスロットのための宣言的なテーブルである usesSchema と featuresSchema、存在の必須指定、extends: による継承の仕組み、そしてフィールド横断のルールブロックである assertions: です。
セマンティックラベル分類体系(標準ライブラリの慣例)
基本型が純粋にクラウドネイティブである場合、アーキテクチャの運用上および認知上のインテリジェンスは、すべてセマンティックなダックタイピングによって重ねられます。
コアの Go コンパイラはこれらのラベルを解釈しません。コンパイラはラベルの意味を解釈せずに、フラットな中間表現 (IR) グラフを構築します。これらのラベルは 標準ライブラリの慣例 を表し、Domain 2 で Platform Architect が記述する不変の「遺伝子マーカー」です。これらは、Wasm ポリシーバリデータと物理的な Ops Recipes がアーキテクチャを統制するために使う、明示的なセマンティックフックを提供します。
(A) 汎用クラウドレイヤー これらのラベルは普遍的な振る舞いを記述し、ポリシーエンジンや生成された L7 プロキシが、AI フレームワークをネイティブに理解しなくても標準的なエンタープライズアーキテクチャを統制できるようにします。
| ラベルプレフィックス | 許容される値(慣例) | Platform Ops が必要とする理由(ポリシーフック) |
|---|---|---|
tool.aggrega.ai/impact | read-only, mutating | ポリシーエンジンが最小権限の AuthZ を評価できるようにします。変更を伴うツールは、厳格な承認ゲートのサイドカーのアタッチを要求するポリシーを自動的にトリガーできます。 |
datastore.aggrega.ai/engine | relational、document、kv、vector、graph、semantic-memory、search(値の集合は、充実していくカタログに合わせて安定化中) | ポリシーエンジンがノード間の型安全性を強制できるようにします(例: エージェントが SQL ペイロードを Vector DB に送信しようとするのを防ぐ)。 |
gateway.aggrega.ai/intelligence | semantic, l4-mesh | ルーターが物理的にサポートできる機能を規定します(例: フォールバックチェーンのように、リクエストが指定するモデルに基づいてルーティングする Feature が、標準的な TCP メッシュにアタッチされるのを防ぐ)。 |
dataplane.aggrega.ai/request-mirroring | full-rate, sampled | ライブトラフィックを第二の宛先へコピーする Feature が、そもそもコピーできるプロキシを選択し、一致するすべてのリクエストをコピーするプロキシと、コピーするリクエストの割合を設定できるプロキシとを区別できるようにします。 |
dataplane.aggrega.ai/caller-identity | client-certificate, injected-header | 元の呼び出し元をプロキシの背後のサービスに識別させる必要がある Feature が、その ID を伝達できる component を選択し、どの 仕組みがそれを伝達するか(クライアント自身の TLS 証明書の詳細を転送するのか、呼び出し元を認証した後にプロキシ自身が組み立てるヘッダーなのか)を読み取れるようにします。 |
dataplane.aggrega.ai/content-masking | entity-recognition, pattern-list | 機密テキストをマスクする Feature が、ルーティングするチャットおよび補完ペイロード内でそのテキストがさらに先へ送られる前にプレースホルダーへ置き換えられる component を選択できるようにします。値は忠実度を示します。entity-recognition の場合、component は設定で指定されたパターンへの一致に加え、呼び出す認識サービスが検出するエンティティ型も置き換えます。pattern-list の場合、設定で指定されたパターンへの一致のみを置き換え、認識サービスは呼び出しません。 |
dataplane.aggrega.ai/prompt-guard | pattern-list, classifier | モデルのプロンプトを審査する Feature が、ルーティングするチャットおよび補完ペイロードを検査し、その内容に基づいてリクエストを拒否できる component を選択できるようにします。値は忠実度を示します。pattern-list の場合、照合は設定で指定されたパターンに対して行われ、対象は任意の HTTP ボディではなくモデルペイロードです。classifier の場合、判定は component が呼び出す検出サービスを通じて得られる学習済みテキスト分類器によるもので、設定で指定されたしきい値に対して行われます。 |
dataplane.aggrega.ai/upstream-tls | trust-anchor | プロキシに通信相手の確認を要求する Feature が、Release が提供するトラストアンカーに対してアップストリームの証明書を検証できる component を選択できるようにします。 |
dataplane.aggrega.ai/upstream-pinning | public-key | アップストリームが提示できる鍵を固定する Feature が、提示された証明書が Release の提供する公開鍵のいずれかを含まない限りアップストリームを拒否できる component を選択できるようにします。upstream-tls とは異なる主張です。ピンは証明書がどの鍵でなければならないかを示し、アンカーは証明書が何を述べていなければならないかを示します。 |
dataplane.aggrega.ai/period-budget | cost, tokens | 一定期間にトラフィックが消費できる量を制限する Feature が、その期間に計上した量が設定で定められた上限を超えた時点でモデルリクエストを拒否できる component を選択できるようにします。値は計上する対象を示します。cost はトラフィックのコストで、component がモデルごとに保持する表から価格を算出します。tokens は各モデルの応答が報告する読み取り、書き込み、またはその両方のトークンで、component はこれを計上し、価格は算出しません。 |
dataplane.aggrega.ai/concurrency-cap | total, per-target | component が同時に扱うリクエスト数を制限する Feature が、設定で定められた上限を超えたリクエストを保留または拒否できる component を選択できるようにします。値は 1 つの上限が計上する対象を示します。total は component が転送するすべてのリクエストを 1 つの上限で数えます。per-target は送信先の各アップストリームターゲットへ処理中のリクエストを数え、ターゲットごとに上限を持ち、合計には上限を持ちません。 |
dataplane.aggrega.ai/ キーは component の種類ではなくトラフィック経路上の位置を示すため、プロキシ、イングレスゲートウェイ、サービスメッシュは、それぞれ独自の語彙を必要とせず、
1 つの語彙で自らを記述できます。このファミリーの 2 つの性質は、どちらも
逆に解釈しやすいため、注意深く読む価値があります。
- 値が表すのは忠実度であり、単に機能の有無ではありません。 2 つの component がどちらもリクエストをミラーリングでき、それでも Feature が気にする点で異なることがあります。 そのため区別は値に載り、Feature は必要な忠実度を選択します。 より強い忠実度を提供する component は、より強い値のみを持ち、それ以外の値は持ちません。
- 値が主張するのは製品ができることであり、デプロイメントが
有効にしたことでは決してありません。 この 2 つは似て読めますが、component の性質であるのは
前者だけです。アップストリーム証明書を検証できるプロキシは、
特定のデプロイメントがその検証を有効にするかどうかにかかわらず
upstream-tls: trust-anchorを持ちます。ラベルは、何かが設定される前に Feature が 選択の基準とするものだからです。
これらの軸のいずれかで記述すべきものがない component は、最も弱い値ではなく、 その軸に値を持ちません。これは分類体系の他の部分と同じです。値がないことは、その component ではその軸に対象がないことを意味するため、その軸に何らかの値を要求する Feature は 正しくアタッチされません。
(B) 特化 AI レイヤー(認知的アイデンティティ) これらのラベルはワークロードの 認知的 アイデンティティを記述し、アーキテクチャが最新の AI フレームワークを保護できるようにします。
| ラベルプレフィックス | 許容される値(慣例) | Platform Ops が必要とする理由(ポリシーフック) |
|---|---|---|
model.aggrega.ai/capability | generative, embedding, transcription | usesSchema セレクタ文字列(静的解析中に Go コンパイラがネイティブに評価)で使われ、開発者が生成テキストのペイロードを誤って埋め込みエンドポイントへルーティングしないことを保証します。 |
model.aggrega.ai/api | openai, anthropic, gemini, native | component が公開するアドレスでどのモデル API が応答するかを示します。OpenAI API(ベンダー自身のもの、またはサーバーによるその実装)の場合は openai、Anthropic の Messages API(ベンダー自身のもの、またはサーバーによるその実装)の場合は anthropic、Google の Gemini API の場合は gemini、それらのいずれでもない製品独自の API の場合は native です。すべてのモデル component がこれを持ち、モデル API を提供できるゲートウェイも持ちます。そのため、component.aggrega.ai/category in (ai-model, gateway), model.aggrega.ai/api を選択するソケットはモデルまたはそのようなゲートウェイを受け入れ、いずれも提供できないゲートウェイは拒否します。一方、model.aggrega.ai/api=anthropic のように 1 つの値を指定するソケットは、その API を提供するものだけを受け入れます。これは製品が提供するものを示し、ある Release が配線するものではありません。モデルが自身のソケットに配線されるゲートウェイは、何も配線されていなくてもこれを持ちます。このラベルはセレクタが照合する文字列であり、アドレスで実際に何が応答するかを確認するものはありません。 |
agent.aggrega.ai/autonomy | autonomous, copilot | 認知ループの実行リスクを識別し、完全自律型エージェントに人間による承認機能をポリシーで義務付けられるようにします。 |
(C) 横断的要素(ガバナンス、状態、ハードウェア) これらは、ゼロトラスト検証とハードウェアルーティングを駆動する、エンタープライズの基盤となるタグです。
| ラベルプレフィックス | 許容される値(慣例) | Platform Ops が必要とする理由(ポリシーフック) |
|---|---|---|
component.aggrega.ai/hosting | self-hosted, managed, external, mixed | component の基盤リソースを誰が運用するか (信頼境界の軸) を記録します。ポリシーエンジンはこれを読んでデータ流出リスクを算出します (例: managed のサードパーティ API へルーティングされた内部データは、オペレーターの境界を離れます)。横断的であり、同じ値がマネージドデータベース、マネージドモデル API、自己運用の推論サーバーのいずれも同様に記述します。mixed は、Recipes が複数の運用形態にまたがるコンポーネントを示します。たとえば、Helm と Compose の Recipes ではセルフホストで運用され、RDS の Recipes ではマネージドで運用されるデータストアです。このため Release の運用形態は、その Manifest が選択する Recipe に従います。 |
compliance.aggrega.ai/data-class | public, internal, restricted | コンポーネントが保持するデータのクラスです。コンパイラはこれを文字列としてビルドグラフに運ぶだけで、順位付けは一切行いません。オペレーターが ir-verdict ロールにアタッチするポリシーが、自身の設定でクラスの順序を定め、コンパイラが列挙するルートに沿ってラベルを読み取ります。たとえば、restricted のコンポーネントが、ルート上に機密解除を行う Feature がアタッチされないまま別のクラスのコンポーネントに到達するビルドを停止させます (policy-data-class-route)。標準ライブラリの Component はこれを持ちません。クラスは環境がコンポーネントをどう使うかについての表明であり、環境自身の Component (たとえば extends による特殊化) が持ちます。 |
compliance.aggrega.ai/contains-pii | true, false | GDPR/CCPA の対象となるワークロードを明示的にフラグ付けします。オペレーターがアタッチするポリシーはこれを読み取り、そのようなワークロードのトラフィックが通るルートに特定の Features を要求できます。たとえば、モデルトラフィックを送る AI ゲートウェイ上の core/data-masking で、これは policy-data-class-route がデータクラスについて確認する形です。標準ライブラリの Component はこれを持ちません。データクラスと同様に、環境が自身のコンポーネントについて行う表明です。 |
hardware.aggrega.ai/accelerator | gpu, tpu, npu | DevOps が Release ファイルで使用します。components: {} マップを介して、これらのコンポーネントを物理的なハードウェアプールの境界(例:GPU 対応クラスター)に明示的にルーティングします。一方、ガバナンスの判定ロールは、GPU ラベル付きのコンポーネントが GPU 非対応の境界に配置されないことを強制できます。 |
state.aggrega.ai/retention | retain, delete | AOT 削除ギャップを解決します。 開発者が Aggregate からデータベースを削除すると、GitOps オーケストレーターは物理的にディスクを削除します。Recipe の pipeline: ステップは retain ラベルを読み取り、レンダリングされたアーティファクトにオーケストレーターネイティブの保護 (例: helm.sh/resource-policy: keep) を追加できます。 |
state.aggrega.ai/backup-tier | mission-critical, standard, ephemeral | SOC2 可用性フック。 リソースに対して自動スナップショット/ボリュームバックアップの設定を物理的に生成するかどうかを Ops の FeatureRecipe に伝えます。 |
(D) 動的なビジネスコンテキスト (カスケードするアノテーション) labels が不変のカタログ DNA を定義するのに対し、動的なビジネスコンテキスト (SOC2 監査のスコープや FinOps のコスト追跡など) は、誰がアプリケーションをデプロイし、どこで実行するかによって変わります。これらは、開発者の subsystems、Ops の Release 境界、または annotation-transform ロールにアタッチされたガバナンスプラグインによって動的に注入される アノテーション で管理されます。
| アノテーションのプレフィックス | 許容される値(慣例) | Platform Ops が必要とする理由(ポリシーフック) |
|---|---|---|
business.aggrega.ai/cost-center | 例:finance、ai-research | クラウド課金ダッシュボード向けに、最終的に生成されるアーティファクトへ物理的なタグ(例:AWS タグや K8s ラベル)を注入するために Wasm レンダリングプラグインが必要とします。 |
business.aggrega.ai/owner | 例:team-alpha@corp.com | インシデント対応のルーティング。インフラストラクチャが人間のチームに対応付けられることを保証します。 |
compliance.aggrega.ai/frameworks | 例:soc2, hipaa | SOC2 スコープトリガー。 環境の Release を介して注入されます。Wasm プラグインはこの文字列を読み取り、アプリケーションが本番のコンプライアンス境界に入ると、厳格な監査ログ用サイドカーを自動生成し、デバッグポートを無効化します。 |
このタクソノミーはカタログの慣例であり、コンパイラの規則ではありません。企業はこれを無視することも、削除することも、独自のラベル語彙(mycompany.com/custom-trait)を考案することもできます。Wasm プラグインは、企業が記述したラベルキーであれば何でも評価します。
スキーマのオーサリング
Component スキーマ (およびその対となる Feature。feature.aggrega.ai/kind: secret というラベルが付いた認証情報の Features を含みます) は、開発者が記述する values の検証コントラクトを spec.schema: ブロックで宣言します。このブロックは JSON Schema 2020-12 を受け付け、コンパクト形式の YAML 省略記法 (デフォルト。約 15 個のキーワードを持ち、コンパイル時に機械的に JSON Schema へ変換されます) と完全な JSON Schema YAML (冗長形式) のどちらでも記述できます。また、複数の Components で共有される SchemaLibrary のエントリーに対しては、$ref: によるドキュメント間参照を使用できます。
- インラインのコンパクト形式 (デフォルトのオーサリング手段): Component YAML の中にコンパクト形式のリーフを直接記述する、埋め込み YAML ブロックです。カタログのスキーマ内容の大部分を、完全な JSON Schema のごく一部の行数で表現できます。キーワードの語彙とオーサリングの慣例については
vocabulary/compact-form-authoring.mdを参照してください。 - インラインの JSON Schema YAML: 冗長形式です。コンパクト形式が直接扱わない JSON Schema 2020-12 のキーワード (
$dynamicRef、深いunevaluatedProperties、複雑なnot:の組み合わせ) がスキーマに必要な場合に適しています。コンパクト形式と JSON Schema は、$jsonschema:エスケープハッチを使用して、単一のschema:ブロック内の任意のノード境界で混在させることができます。 - ドキュメント間参照 (SchemaLibrary エントリーへの
$ref:): SchemaLibrary エントリーを識別子 (Datastores#/schemas/MariaDBValuesなど) で指す、JSON Schema ネイティブの$ref:です。数百行に及び、複数の Components で再利用されるエンタープライズのスキーマは SchemaLibrary エンティティに置かれ、利用側の Component は内容をインライン化せずにエントリーを参照します。ライブラリエンティティと解決のセマンティクスについてはentities/schemalibrary.mdとvocabulary/cross-document-ref.mdを参照してください。
上記の 3 つの形式はピラーの内容を記述するもので、何も拡張しない Component で使用できます。extends: を宣言する Component はピラーの内容を一切記述しません。リテラルのマーカー schema: inherited を書き、ベースが記述したとおりのピラーブロックをそのまま受け取ります。このような Component で schema: が取る値はこのマーカーのみです。後述の「Catalog Authoring: Extending Base Components」を参照してください。
コンパイラは schema: ブロックを解決し (コンパクト形式の展開、$ref: URL の参照解決、SchemaLibrary のライブラリ間チェーンの適用)、Component の検証パスにおいて、得られた JSON Schema を usesSchema と featuresSchema から導出される自動生成のベース (後述のセクションを参照) と統合します。検証は解決済みのスキーマに対して実行され、オーサリングの経路は下流のパイプライン段階からは見えません。
記述されたインスタンスは、ビルド時にこの解決済みスキーマに対して検証されます。コンポーネントインスタンスの開発者が記述した values と Operator が解決した infra、および Feature のアタッチメント上の values/infra は、宣言されたピラーに適合する必要があります。型の誤った値、範囲外の数値、宣言された format を満たさない文字列、必須フィールドの欠落、または (closed として検証される values の場合) 宣言されていないプロパティがあると、デプロイ時に壊れたマニフェストを生成するのではなく、記述元の箇所でビルドが停止します。コンパイラがチェックしない format (email、uri、hostname、ipv4、ipv6、uuid、date-time、date 以外のもの。password も含みます) をスキーマで指定したピラーは、カタログの読み込み時にサポートされる名前の一覧とともに拒否されます。各名前が何をチェックするかについては vocabulary/compact-form-authoring.md を参照してください。ベースを extends: する Component のインスタンスは、拡張する Component がそのまま継承するベースのピラーブロックに対して検証されます。そのため、ベースのインスタンスとそれを拡張するもののインスタンスは、同じピラーのコントラクトに従います。診断とピラーごとのルール (infra が Component とプロバイダーのキーの和集合に対してどのように検証されるかを含む) については、errors/fatal-halts.md の §「Authored values or infra do not conform to the declared schema (記述された values または infra が宣言されたスキーマに適合しません)」を参照してください。
宣言されたデフォルトはレンダリングされるピラーに反映されます。 検証に加えて、values フィールド (または infra フィールド) に宣言された default: は、作成者が省略したすべてのキーについて、ビルド時にレンダリングされるピラーに埋め込まれます。そのため、{{ .values.charset }} を読む Recipe テンプレートは、空の値ではなくスキーマで宣言された utf8mb4 を受け取ります。作成者が指定した値が常に優先され、ネストされたオブジェクトは省略された子ごとに埋め込まれます。反映は検証と同じスキーマ解決を使用するため、SchemaLibrary へのドキュメント間 $ref: を通じて到達するデフォルトも反映されます。ピラー全体の参照 (values: {$ref: "BaseComponents#/schemas/BaseModelParameter"}) と、ベースとフレーバーの形 (ベースの $ref: と、それぞれ独自のデフォルトを持つ兄弟の properties) の両方が対象です。ドキュメント内のローカルな #/$defs/ 参照の中、または allOf / oneOf / anyOf の分岐の下でのみ宣言されたデフォルトは反映されません。標準ライブラリは、反映の対象となるドキュメント間 $ref: によってピラーを構成しています。
values ピラー
Component スキーマは、所有者によって 3 つのピラーを分離します。values は Developer が Aggregate で記入し (認知的な意図: データベース名、バージョン、文字セット)、infra は Operator が Release で記入し (運用上のサイジング: コンピュート、ストレージ、HA)、provides は Recipe が設定します (公開 API コントラクト: ホスト、ポート、プロトコル)。Developer が infra を目にすることはなく、Operator が values を目にすることもありません。Recipes はベースのレンダリング時に両方のピラーを消費し、抽象的なピラーを対象プロバイダーが期待する具体的な形にマッピングします。このセクションでは、values ピラーの記述面を扱います。より広範なピラーの分類体系とピラー間のカスケードの規律については、vocabulary/data-pillars.md を参照してください。
values は Developer の認知的な意図、つまりアプリケーションのサイジングや実行方法ではなく、アプリケーションが何であり何をするかを記述する選択を保持します。データベース名、文字セット、エンジンのバージョン、ログレベル、機能フラグ、そしてアプリケーションのバージョン間で変わるものの環境間では安定しているアプリケーション層の設定項目が、典型的な values の内容です。Operator が values: を上書きすることはありません(architecture/06-data-taxonomy-and-composition.md §8 Constraint 4 に従い、Release スキーマは values: ブロックを機械的に拒否します)。環境ごとの差異は Parameter Hoisting を通じて流れます。Aggregate が型付きの parameters.* を公開し、Component の values テンプレートがそれらを参照し、Release がパラメーターを満たします。
# Component schema declares the values shape:apiVersion: aggrega.ai/v1beta1kind: Componentmetadata: name: core/datastore/mariadb version: 1.0.0 labels: component.aggrega.ai/type: stateful-serverspec: schema: values: database_name: { type: string, required: true } charset: { type: string, default: utf8mb4, enum: [utf8mb4, latin1, ascii] } engine_version: { type: string, default: "10.11" } log_level: { type: string, default: info, enum: [debug, info, warn, error] }# Aggregate fragment — the developer fills values:components: customer-db: type: core/datastore/mariadb values: database_name: customers charset: utf8mb4 engine_version: "{{ .parameters.mariadb_version }}" # Parameter Hoisting log_level: infoRecipe 側での消費。 Recipes は、valuesMapping:、provides:、assertions: およびその他のテンプレート面で、.values.<field> を介して解決済みの値を読み取ります。テンプレートごとの利用可否マトリクスについては entities/recipe.md を参照してください。コンパイラは、同じ Component ノードにおける Component の values スキーマと Feature アタッチメントの values: スキーマを統合するため、解決済みのテンプレートコンテキストには該当するすべてのフィールドが含まれます。
ピラー間の規律。 values は、Developer が Aggregate で記述する唯一のピラーです。厳密に開発者向けのフィールドはここに属します。運用上の設定項目(レプリカ数、CPU/メモリの上下限)は Release に置かれるよう Component の infra ピラーに属し、公開出力(ホスト、ポート)は Recipe の provides に属します。これらを混在させると所有権の不変条件が崩れます。意図的なピラー間の受け渡しが正当化される稀なケースについては、vocabulary/data-pillars.md の「Cross-pillar mechanics」を参照してください。
infra ピラー
Component スキーマは、所有者ごとに 3 つのピラーを分離します。values は Developer が Aggregate で記入し (認知的な意図: データベース名、バージョン、文字セット)、infra は Operator が Release で記入し (運用上のサイジング: コンピュート、ストレージ、HA。データストアのバックアップはここでサイジングするのではなく、Operator が Release でアタッチする core/backup Feature です)、provides は Recipe が設定します (公開 API 契約: ホスト、ポート、プロトコル)。Developer が infra を目にすることはなく、Operator が values を目にすることもありません。Recipes はベースレンダリング中に両方を消費し、抽象的なピラーを対象プロバイダーが期待する具体的な形にマッピングします。
標準ライブラリ内のすべての機能に依存しない Component にわたって、3 つの infra の慣例が重要になります。プロバイダー固有の設定のためのオープン構造体のエスケープハッチ、アップストリームのアーティファクトバージョンに対する任意のオーバーライド、そして高可用性フィールドのための意図ベースの語彙です。正規のリファレンス Component は標準ライブラリカタログ内の core/datastore/mariadb で、公式の mariadb イメージを実行するか MariaDB カスタムリソースを mariadb-operator コントローラーに渡す Helm Recipes、AWS RDS に対する Terraform Recipes、同じ RDS に対する CloudFormation Recipes、ローカルコンテナに対する Compose Recipes によって実装できます。その infra ブロックは 1 つ目と 3 つ目のパターンを示しています。
infra.overrides
汎用の infra フィールド (compute、storage、ha) は、プロバイダーをまたいで運用上のサイジングの大部分をカバーします。残りの部分は本質的にプロバイダー固有です。Kubernetes の Recipe には nodeSelector が、RDS の Terraform Recipe には instance_class が、CloudFormation の RDS Recipe には DBInstanceClass が、Compose の Recipe には image のオーバーライドが必要です。Component スキーマは、スキーマを肥大化させずにこれらの設定を通過させるため、真にオープンなマップをエスケープハッチとして公開します。
infra: # ... universal fields ...
# Provider-specific overrides. Accepts any nested structure. # Each Recipe documents which keys it reads. overrides: type: object additionalProperties: true # genuinely open map: arbitrary nested structure permittedadditionalProperties: true を伴う明示的な type: object によって、オープンマップのセマンティクスを選択します。コンパイラはこの構造をそのまま受け渡し、Recipe のテンプレート本体は自身が認識するキーを読み取り、残りは無視します。各 Recipe はヘッダーコメントでオーバーライドキーの体系を文書化するため、特定の Component × Recipe の組み合わせ向けに Release を記述する Operator は、その Recipe がどの設定を公開しているかを把握できます。
overrides を使用する Release の断片:
components: main-db: infra: compute: { cpu: "2", memory: 8Gi } storage: { size: 40Gi, type: balanced-csi } overrides: nodeSelector: kubernetes.io/hostname: cluster1-worker1 service_type: LoadBalancer metrics: enabled: true image: repository: bitnamilegacy/mysqld-exporterDeveloper が overrides を目にすることはありません。これは Operator の領域である Release に置かれます。
infra.source_version
Recipe の source フィールドは、特定のバージョンのアップストリームアーティファクト(Helm チャート 25.0.8、Terraform モジュール 4.2.0、OCI イメージタグ)を参照します。Recipe 内にバージョンをハードコードすると、カタログのメンテナーは互換性のあるアップストリームのバージョンが上がるたびに新しい Recipe を公開しなければなりません。Component スキーマは任意のオーバーライドを公開します。
infra: source_version: type: string description: | Source artifact version. A Recipe versions its artifact from this key where its source resolution reads it, and is unaffected where it does not. Changing from the version a Recipe was authored against does not guarantee value mapping compatibility.Recipe は source ブロック内の optional ヘルパーを通じてこれを読み取るため、
ピン留めがない場合は Recipe の作成時に想定されたバージョンにフォールバックします。
source: kind: helm-oci-chart url: oci://registry-1.docker.io/bitnamicharts/mariadb version: "{{ optional .infra `source_version` `25.0.8` }}"Recipe の source 文字列 (および構造化された source: マップの文字列値のサブフィールド) は Go テンプレートとして評価されます。上記の version のようなリモート座標は、aggrega pull がアーティファクトを固定するときに、.context ルートなしで .values、.infra、.locals に対して評価されます。ワークスペース内のパスを指す source は、エンティティのレンダリング時に、Recipe の locals と同じ自己完結したコンテキスト (.context.instance_id、.values、.infra、およびノードの解決済み .locals 全体) に対して評価されます。どちらでも .context.inject、.context.uses、.provides は禁止されています。このコンテキストに .infra が含まれていることが上記のオーバーライドを機能させており、.locals によって Recipe はソースの断片を一度計算してここで読み戻せます。ソーステンプレートが自ノードの provides を読むことはありません。そのピラーはコンテキストに含まれず、それにアクセスしようとするテンプレートはビルドを停止させます。これは今後の作業を待つ欠落ではなく、このサーフェスの固定された性質です。完全な利用可能性のルールについては Template Expansion Matrix の行 #5 を参照してください。infra.source_version を Recipe のデフォルトから変更しても、Recipe の valuesMapping が新しいアップストリームバージョンとワイヤー互換であることは保証されません。Component スキーマの source_version 宣言にある description がその警告を記載しています。
infra.ha.*
高可用性フィールドは、メカニズムの語彙ではなく意図の語彙を使用します。
infra: ha: enabled: { type: boolean, default: false } read_replicas: { type: integer, min: 0, default: 0 }infra.ha.enabled は「この Component を高可用にする」ことを、infra.ha.read_replicas は「読み取り専用のコピーを N 個欲しい」ことを表します。その意図が自身のプロバイダー上で何になるかは、各 Recipe が決めます。core/datastore/mariadb の標準ライブラリの Recipes を、Manifest がマッピングするときの名前で示します。
| Recipe | ha.enabled: true のマッピング先 | ha.read_replicas: N のマッピング先 |
|---|---|---|
helm/mariadb (公式の mariadb イメージ上の StatefulSet) | サーバーを 1 つだけ実行するため、キーを示してビルドが停止します | サーバーを 1 つだけ実行するため、N が 0 より大きいとビルドが停止します |
helm/mariadb-cluster (mariadb-operator コントローラーが調整する MariaDB カスタムリソース) | 自動フェイルオーバーを有効にします (replication.primary.autoFailover: true)。読み取りレプリカへフェイルオーバーするため、N が 0 だとビルドが停止します | spec.replicas を N + 1 に設定してレプリケーションを有効にします。provides.host は <name>-primary Service になります |
terraform/mariadb-rds (AWS RDS) | プライマリの aws_db_instance に multi_az = true を設定 | N 個の個別の aws_db_instance リードレプリカリソースを作成 |
terraform/mariadb-rds-module、terraform/mariadb-rds-terraform-aws-modules (モジュール経由の AWS RDS) | multi_az = true をモジュールに渡します | インスタンスを 1 つだけプロビジョニングするため、N が 0 より大きいとビルドが停止します |
cloudformation/mariadb-rds (AWS RDS) | AWS::RDS::DBInstance に MultiAZ: true を設定 | インスタンスを 1 つだけプロビジョニングするため、N が 0 より大きいとビルドが停止します |
compose/mariadb (ローカル開発コンテナ) | サーバーを 1 つだけ実行するため、キーを示してビルドが停止します | サーバーを 1 つだけ実行するため、N が 0 より大きいとビルドが停止します |
メカニズムの語彙 (infra.primary.replicas) は、あるプロバイダー (Kubernetes の Pod は StatefulSet のレプリカ) では自然に読めますが、それ以外ではカテゴリーエラーになります。RDS にはプライマリ上の「レプリカ」という概念がなく、CloudFormation は RDS と同様であり、Compose には水平レプリカの抽象化がまったくありません。意図の語彙は翻訳できます。どのプロバイダーにも「このデータベースを高可用にする」という何らかの概念と「読み取り専用のコピーを N 個欲しい」という何らかの概念があり、Recipe がプロバイダーごとの翻訳を担います。実現側にそのようなメカニズムがない場合、その Recipe はキーを示してビルドを停止できます。helm/mariadb と compose/mariadb は両方のキーについて、単一インスタンスの RDS Recipes は読み取りレプリカについてそうしています。
infra.ha.read_replicas: 0 がデフォルトです。両方のキーがデフォルトのとき、helm/mariadb-cluster は 1 つのインスタンス上のレプリケーションではなく、replication ブロックのない単一インスタンスの MariaDB をレンダリングします。compose/mariadb はローカルの Docker ホスト上でサーバーを 1 つだけ実行するため、infra.ha.enabled: true または 0 以外の infra.ha.read_replicas はキーを示してビルドを停止させ、メッセージはフェイルオーバーと読み取りレプリカを提供する helm/mariadb-cluster を案内します。
provides の柱
provides は Recipe が記述する公開 API です。Component の解決済み Recipe が下流の呼び出し元に提供する値であり、呼び出し元はそれを .context.uses.<alias>.provides.<provided-name> のサーフェス経由で(呼び出し元がエッジに inject: 許可リストを宣言している場合は .context.inject パイプ経由で)参照します。Component のスキーマが形(キー名と型)を宣言し、バインドされた Recipe の provides: ブロックが値を供給します。Aggregate を記述する Developer は、Component のページにある provides の形を、呼び出し元が依拠できる契約として参照します。Recipe の作成者は、自身がラップする特定の実装についてその契約を満たします。
契約の充足は Loud Guardrail として強制されます。バインドされた Recipe は、その Component が宣言するすべての provides キーを生成する必要があります。バインドされた Recipe が宣言済みのキーを省略すると、それを参照する呼び出し元に何も渡さないまま黙って進むのではなく、ビルドが停止し、欠けているキーを示します。宣言済みのセットを超える追加のキーを生成することは許可されています。検査されるのはキーの存在のみです。生成される値はコンパイラがそのまま通す不透明な文字列であるため、宣言された型は呼び出し元が読む契約にとどまり、コンパイラが検証する値ではありません。
# Component schema declares the provides contract:apiVersion: aggrega.ai/v1beta1kind: Componentmetadata: name: core/datastore/mariadb version: 1.0.0 labels: component.aggrega.ai/type: stateful-serverspec: schema: values: database_name: { type: string, required: true } provides: host: { type: string } port: { type: integer } database: { type: string }# Recipe fulfills the contract:apiVersion: aggrega.ai/v1beta1kind: Recipemetadata: name: mariadb-bitnami version: 1.0.0spec: capability: helm implements: core/datastore/mariadb:1.0.0 source: kind: helm-oci-chart url: oci://registry-1.docker.io/bitnamicharts/mariadb version: "25.0.8" provides: # The chart's primary Service, named by the fullnameOverride pinned below host: "{{ .context.rendered_name }}" port: "3306" database: "{{ .values.database_name }}" valuesMapping: | fullnameOverride: "{{ .context.rendered_name }}"provides と inject の評価の分離。 コンパイラは provides: テンプレートを provides 評価の段階で、自己完結したテンプレートコンテキスト(.context.instance_id、ノードの Provider が報告する場合は .context.rendered_name、.values、.infra、同じノード上の Recipe の解決済み locals:)に対して評価します。呼び出し元の状態は一切見えません。ノードの locals はその段階のプリアンブルで provides より先に解決されるため、provides: テンプレートは .locals を読むことができます。次に実行される inject ハイドレーションで、コンパイラは uses: エッジをたどり、各呼び出し元の .context.uses.<alias>.provides.<provided-name> を解決済みの provides の値に対して解決します。この 2 つを分離することで、非循環の解決が保証されます。provides: は呼び出し元を参照できず、呼び出し元の inject: は、inject ハイドレーションが実行されるまで、まだ解決されていない provider の出力を参照できません。
契約の進化。 provides フィールドの名前変更や削除は、古い名前に依拠するすべての呼び出し元にとって破壊的変更です。Component の metadata.version (および Recipe の implements: 宣言) が契約の進化を示すシグナルとなり、特定のメジャーバージョンに固定された下流の呼び出し元は安定した provides の形を参照します。
Recipe 側の解説。 provides: テンプレートの記述文法、テンプレートごとの利用可能性マトリクス、およびネームスペース間・リージョン間ルーティングの実例については、entities/recipe.md の「The provides: block」と architecture/06-data-taxonomy-and-composition.md §3 を参照してください。
存在の義務付け: features.aggrega.ai/requiredType.<label>
Component は、そのすべてのインスタンスが特定の Feature 型のアタッチメントを持たなければならないと宣言できます。これは存在の義務付けであり、Component 自身のメタデータに付ける繰り返し可能なアノテーションとして記述します。
apiVersion: aggrega.ai/v1beta1kind: Componentmetadata: name: core/payment-processor version: 1.0.0 labels: component.aggrega.ai/type: server annotations: features.aggrega.ai/requiredType.audit: core/audit-logging features.aggrega.ai/requiredType.compliance: core/pci-compliancespec: schema: values: processor_endpoint: { type: string, required: true }キーはプレフィックス features.aggrega.ai/requiredType. に任意のラベルを続けたもので、値は少なくとも 1 つのアタッチメントが持つべき Feature 型の URI です。ラベルは、満たされない義務付けが出す診断の中で要件を名指しします(上の例では audit と compliance)。ラベルの役割はそれだけです。ラベル付きのキーにより、Component は複数の義務付けを同時に宣言できます。アノテーションはフラットな文字列マップであり、重複したキーを持てないためです。
コンパイラは、5-Tier Onion Model のカスケードがすべてのスコープを畳み込んだ後の、インスタンスの最終的なアタッチメント集合に対して各義務付けを評価します。対象となるのは、Aggregate のコンポーネントレベルおよびサブシステムレベルの features: ブロック、Release の境界レベルおよびコンポーネントレベルの features: ブロック、そしてアノテーション駆動の展開で生成されたアタッチメントです。これらのいずれでも義務付けは満たされます。このルールは何が存在するかを検査し、それがどのようにそこに来たかは問いません。したがって、オペレーターが Release でモニタリングのアノテーションを設定したことによってのみ義務付けが満たされる Component も、開発者が手作業で Feature をアタッチした Component とまったく同じように合格します。
どのアタッチメントにも満たされない義務付けは、コンポーネントインスタンス、要件のラベル、必要な型を名指しする診断とともにビルドを停止します。アノテーションの値は不透明な文字列であるため、コンパイラが読み取る前にその形を検証するものはありません。そのため、Feature 型の URI ではない値や、プレフィックスの後にラベルのないキーは、宣言が不正であることを示す別の診断で停止します。この 2 つは意図的に区別されています。壊れた宣言はカタログのエンティティで修正し、満たされない要件は Feature をアタッチすることで解決します。そして、タイプミスが満たされた要件として読まれることがあってはなりません。
どちらの診断も errors/fatal-halts.md の「Required feature not attached(必須の Feature がアタッチされていません)」に記載されています。
義務付けはスロットではありません。 この 2 つは異なる問いに答えるものであり、その違いは見た目だけのものではありません。
featuresSchema スロット | 存在の義務付け | |
|---|---|---|
| 宣言するもの | 名前付きのバインディングポイント | 存在しなければならないものに対する制約 |
| 名前を参照解決できるか | はい — from: <slot> と .features.<slot>.provides.* | いいえ — ラベルは要件を名指しするだけです |
| カーディナリティ | スロットごとにちょうど 1 つの充足 | その型のアタッチメントが少なくとも 1 つ |
| 充足内容への制約 | selector, inject, sensitive | 型以外にはなし |
| 自由なアタッチメントで満たされるか | いいえ — スロットは名前で充足されます | はい — 任意のスコープで、任意の名前で |
| 要求が満たされない場合 | required: true で、スロットの名前に何もバインドされていない場合に停止 | その型を持つアタッチメントがない場合に停止 |
どちらの要求も同じ入力、つまりインスタンスの最終的なアタッチメント集合に対して検査され、どちらも独自の診断で停止します。それは、両者がその入力に異なる問いを投げかけるためです。1 つの名前付きバインディングポイントがバインドされているか、それとも何らかのアタッチメントが名前付きの型を持っているか、という問いです。一方が他方の代わりに答えることはありません。
Recipe がアタッチされたものを読み取る必要がある場合はスロットを使います。Component の契約がある機能の存在を求め、どのインスタンスがそれを提供するかを問わない場合は義務付けを使います。core/audit-logging を義務付ける決済処理の Component は、開発者がアタッチし忘れたかどうかに関係なく、すべてのデプロイメントで監査ログを得ます。core/pci-compliance を義務付ける PCI 準拠の Component は、デプロイメントのどこかにコンプライアンスの Feature がアタッチされていなければ出荷できません。
継承。 ベースの Component で宣言された義務付けは、それを extends: するすべての Component に継承されます。メタデータのアノテーションは extends チェーンに沿ってマージされ、キーごとに子が優先されるためです。したがって子は、同じラベルを別の型で再宣言して継承した義務付けの対象を変えることも、新しいラベルで独自の義務付けを追加することもできますが、ベースが宣言したものを取り除くことはできません。
トポロジーソケット: usesSchema
Component は usesSchema: ブロックによってトポロジーソケットを宣言できます。これは featuresSchema と並行する宣言的な YAML マップです。各エントリは、Component がコンポーネント間の依存関係を受け入れるソケットを指定し、開発者がそのソケットに接続できる Component の形を規定します。コンパイラは宣言されたソケットから JSON Schema 2020-12 の検証ルールを自動生成し、Component の解決時にそれを Component の schema: と統合します。構造は usesSchema から得られるため、開発者が schema: の中に uses: ピラーを手書きすることはありません。
# Component declares the sockets it accepts:apiVersion: aggrega.ai/v1beta1kind: Componentmetadata: name: core/ai-agent/orchestrator version: 1.0.0 labels: component.aggrega.ai/type: serverspec: usesSchema: primary_datastore: required: true selector: "datastore.aggrega.ai/engine=vector" inject: [env] cache: required: false selector: "datastore.aggrega.ai/engine=kv" inject: [env, file] log_destination: required: false selector: "component.aggrega.ai/category=messaging" inject: []# Aggregate fragment — developer wires the sockets:components: agent: type: core/ai-agent/orchestrator uses: primary_datastore: main: { target: vector-db-instance } log_destination: audit: { target: audit-sink }接続形式 — ソケットは 1 つまたは複数のターゲットを受け入れます。 上の例では各ソケットを単一のターゲットに接続していますが、ソケットは複数のターゲットに展開できます。ソケットの値は次の 2 つの形式のいずれかで記述します。
uses: # Compact form — a list of target names. Each entry produces an edge # whose alias equals its target. Use it for the single-target case, and # when one socket connects to several peers of the same shape. shards: [orders-db, customers-db, inventory-db]
# Verbose form — an alias-keyed map. Each alias maps to an entry object # carrying its own `target:`, and may carry its own inject directives. # Use when the connections need distinct names or per-edge inject. databases: primary: { target: orders-db, inject: { env: [{ in: DB_URL, from: url }] } } replica: { target: orders-db-ro, inject: { env: [{ in: DB_REPLICA_URL, from: url }] } }エイリアスは常にエントリオブジェクトに対応し、ターゲット名そのものには対応しません。databases: { primary: orders-db } はロード時に拒否され、target: を省略したエントリオブジェクトも同様に拒否されます。エイリアスを考案せずに単一のターゲットを接続するには、コンパクト形式 primary_datastore: [vector-db-instance] を使用します。この形式はターゲットを一度だけ指定し、そこからエイリアスを導出します。
各エントリ(リスト要素またはマップのエイリアス)は 1 つのエッジとなり、記述順に保持されます。ソケットの selector: はそのソケットを通じて接続されるすべてのターゲットに適用され(各エッジは静的解析中に個別に型チェックされます)、required: true は少なくとも 1 つのターゲットを接続しなければならないことを意味します。
フィールドのセマンティクス:
| フィールド | 種類 | デフォルト | 意味 |
|---|---|---|---|
required | bool | false | true の場合、開発者はこのソケットに少なくとも 1 つの依存関係を接続しなければなりません。false の場合、ソケットは任意です。 |
selector | string | — | Feature の appliesTo と同じ文法によるラベルセレクターで、このソケットを通じて接続されるすべてのエッジのターゲットが満たす必要があります。ここに記述された文字列として読み取られ、静的解析中にターゲットのラベルに対して評価されます。ラベルがこれを満たさないターゲットはビルドを停止させ、文法が拒否するセレクターも、読み取れなかった要件を示してビルドを停止させます。空のセレクターはターゲットに制約を課しません。 |
inject | string[] | — | 許可される inject 配信メカニズムの許可リストです(featuresSchema[].inject と並行)。省略、または [](空)はブラックボックスを意味します。開発者の uses: エントリには inject: ブロックを記述できず、配信は Recipe が制御します。[env, file, arg](空でない)は透過的であることを意味し、開発者は依存先の provides 値をどのメカニズムで配信するかを指定できます。強制されます。後述の「ソケットの inject 許可リストが強制される場所」を参照してください。 |
valueSchema | object | — | このソケットを通じて接続されるエッジ上の、開発者が記述する values に対する任意のエッジ単位の契約です(Aggregate で記述します)。schema: と同じ記述形式の JSON Schema 2020-12 です。省略した場合、ソケットは values の契約を宣言しません。 |
infraSchema | object | — | このソケットを通じて接続されるエッジ上の、オペレーターが記述する infra に対する任意のエッジ単位の契約です(Release で記述します)。記述形式は valueSchema と同じです。省略した場合、ソケットは infra の契約を宣言しません。 |
featuresSchema | map | — | このソケットを通じて接続される各接続が埋めることのできるアタッチメントスロットで、スロット名をキーとし、各スロットは Component レベルのスロットと同じキーを取ります。省略した場合、このソケットを通じた接続はアタッチメントを持ちません。後述の「各接続が埋めるスロット」を参照してください。 |
ソケットの inject 許可リストが強制される場所。 許可リストは、利用側が配信形式を選択できるかどうか、できる場合はどの形式かについてのソケットの表明です。そのため、エッジとソケットの宣言の両方が揃った時点で、ソケットを通じて接続されるすべての uses: エッジに対してチェックされます。1 つのルールから 2 つの拒否が導かれ、どちらもビルドを停止させます。
- 許可リストにないメカニズムを指定するエッジは、ソケット、違反したメカニズム、およびソケットが許可するものを示して停止します。エッジ上の違反したメカニズムはすべてまとめて報告されます。
- 許可リストが省略または空のソケットを通じて何らかの配信を指定するエッジも停止します。これはブラックボックス宣言が役割を果たしているものです。この宣言は「Recipe がこれを内部で配信するので、配信を指定しないこと」と述べており、空の許可リストはすべてを許可するのではなく、何も許可しません。
ソケットは、それを宣言したエンティティ上で読み取られます。これは必ずしもエッジが属するコンポーネントとは限りません。Feature アタッチメントの uses: に記述されたエッジは、アタッチされた Feature の usesSchema に対して解決され、それ以外のすべてのエッジ(Aggregate で記述されたもの、Release から接続されたもの、サブアグリゲートを経由して到達したもの)は利用側の Component のものに対して解決されます。extends を通じて継承されたソケットは、エンティティ自身が記述したソケットとまったく同じように読み取られます。
何も指定しないエッジは、ソケットが何を宣言していても、どちらの拒否の影響も受けません。利用側の Recipe で .context.uses.<alias>.provides.<name> から依存先の値を読み取るのに inject: ブロックは不要で、常に利用できます。両方の診断については errors/fatal-halts.md を参照してください。
エッジ単位の接続契約 — valueSchema と infraSchema。 どの Components がソケットに接続できるかを規定するだけでなく、ソケットは各接続がどの設定を持つかを宣言できます。2 つの任意のソケット単位スキーマが、ソケットを通じて接続されるすべてのエッジ上の接続スコープの設定を検証します。
valueSchemaは、usesエッジ上の開発者が記述するvaluesブロックの契約です。開発者が Aggregate で表現する接続単位の調整(たとえばコネクションプールのサイズやクライアントモード)です。infraSchemaは、usesエッジ上のオペレーターが記述するinfraブロックの契約です。オペレーターが Release で表現する接続単位の運用上のサイジングです。
どちらも schema: フィールドと同じ内容形式の JSON Schema 2020-12 を受け入れます。インラインのコンパクト形式、インラインの JSON Schema YAML、または SchemaLibrary エントリへのドキュメント横断の $ref: です。これらは各エッジの設定に対して個別に検証されるエッジ単位の契約であり、利用側の Component 自身の values スキーマには合成されません。あるピラーのエッジ単位スキーマを省略したソケットはそこに契約を宣言せず、そのピラーに記述された設定は検証されません。エッジ単位の設定はクローズドで検証され、検証はどちらのピラーでもデフォルトを考慮します。スキーマが default: を与えるキーは、記述者が省略しても指定されたものとみなされます。
宣言された default: は、どちらのピラーでも実体化されます。記述者が省略したキーは、省略されたコンポーネントの value や infra のキーとまったく同じように、宣言されたデフォルトを持って利用側の Recipe のレンダーコンテキストに届きます。そのため、ソケットにデフォルトを宣言するだけで十分であり、Recipe テンプレートにそのためのフォールバック式は不要です。記述された値は常に宣言されたデフォルトより優先され、指定したキーのみを埋めます。ソケットの契約のうち 1 つのキーを記述したエッジも、その契約の他のキーについては宣言されたデフォルトを受け取ります。デフォルトはエッジに付くため、接続されていないソケットは何も寄与しません。
spec: usesSchema: databases: required: true selector: "datastore.aggrega.ai/engine=relational" inject: [env] valueSchema: # developer per-edge values, authored in the Aggregate pool_size: { type: integer, minimum: 1, maximum: 100, default: 10 } tls_mode: { type: string, enum: [disable, require, verify-full], default: require } infraSchema: # operator per-edge infra, authored in the Release storage_class: { type: string, default: standard }このソケットを宣言すると、Aggregate が pool_size を省略したエッジは 10 をレンダリングし、Release が storage_class を省略したエッジは standard をレンダリングします。記述はキーごとに、それぞれのピラー内で優先されます。pool_size: 42 を設定した Aggregate は 42 をレンダリングし、tls_mode は引き続き require で埋められます。また storage_class: gp3 を設定した Release は、どちらの開発者キーにも影響を与えずに gp3 をレンダリングします。
利用側の Component の Recipe は、解決済みのエッジ単位の設定を、拡充されたトポロジーパイプの .context.uses.<alias>.values.<key> と .context.uses.<alias>.infra.<key> から読み取ります。vocabulary/topology-triad.md を参照してください。
各接続が埋めるスロット — ソケットの featuresSchema。 ソケットはアタッチメントスロットも宣言でき、その場合、ソケットを通じて接続される各接続は、それぞれのスロットに独自のアタッチメントを持つことができます。複数のモデルに接続するゲートウェイは、モデルごとに異なる認証情報を保持します。認証情報はゲートウェイではなく接続上にあるためです。
spec: usesSchema: models: selector: "component.aggrega.ai/category=ai-model" featuresSchema: credential: selector: "feature.aggrega.ai/kind=secret" sensitive: true inject: [env] description: The credential the consumer presents to the component this connection reaches.接続は、自身の features: の中にスロット名でアタッチメントを持たせることでスロットを埋めます。これは Aggregate の接続エントリ(Aggregate)または Release の接続エントリ(Release)で行い、そのアタッチメントは利用側コンポーネントのアタッチメントの 1 つとなり、<alias>.<slot> という名前が付きます。
この宣言が行うことを正確に述べます。
- スロット名は閉じた集合です。 任意の名前で自由なアタッチメントを認める Component 自身の
featuresSchemaとは異なり、ソケットのスロットは、そのソケットを通る接続が持てる唯一の名前です。それ以外の名前はビルドの読み込み時に停止し、featuresSchemaを宣言していないソケットは、その接続にアタッチメントを一切認めません。アドホックソケット(このusesSchemaが宣言していないソケット)はスロットを宣言しないため、その接続もアタッチメントを持ちません。各接続は自らスロットを埋めます。より広いスコープのアタッチメントが接続にカスケードすることはなく、接続アタッチメントの合成名を記述した Release キーは停止します。 - その他のキーは各接続をスロットに従わせます。 ここでのスロットは Component レベルのスロットと同じキー(
required、selector、inject、sensitive、description)を取り、各接続はそれぞれ個別にそれらに従います。selectorは、接続がスロットを埋める Feature のラベルに対して照合され、許可されない埋め込みは停止し、その埋め込みを記述したドキュメント内の該当接続エントリの位置で報告されます。required: trueはソケットを通じて配線されたすべての接続に課されます。スロットを空のままにした接続はその接続を示して停止し、隣のスロットを埋めた接続は通過します。sensitiveは Component レベルのスロットとまったく同様に解釈されます。スロットを埋めるアタッチメントは、ビルドグラフとaggrega inspectで機密としてマークされます。接続でもコンポーネントと同様に、アタッチメントのどの値を機密として伏せるかは、アタッチされた Feature 自身のスキーマのみによって決まります。injectは、スロットの素材を配信する Workload エントリを従わせます。接続のアタッチメントは独自のinject:ブロックを持たない(どちらのドキュメントも接続エントリでそれを認めない)ため、Workload はスロットと並べて接続を指定することでそれを配信し、そのエントリは、Component レベルのスロットを指定するエントリがそのスロットの許可リストに従うのとまったく同様に、ソケットスロットの許可リストに従います。
Feature の usesSchema は featuresSchema を取りません。Feature が引く接続はアタッチメントを持たず、ソケットにスロットを宣言する Feature は読み込み時に拒否されます。そのような接続が必要とする資格情報は、Feature 自身の featuresSchema のスロットとします。
usesSchema からのスキーマ生成。 コンパイラは宣言されたソケットから JSON Schema 2020-12 のベースフラグメントを生成し、ユーザーの schema: 宣言と合成します。これは featuresSchema と同じパターンです。生成されたスキーマがディスクに書き出されることはなく、Component の検証パスの間だけメモリ上に存在します。Aggregate 内の開発者の uses: マップはマージされたスキーマに対して検証され、ソケットごとの selector: は、ノード間の型安全性チェックとして、静的解析の間に候補 Component のラベルに対して評価されます。
セレクターのセマンティクス — Split Schema メカニズム。 usesSchema[].selector: は、Aggrega のトポロジーを型のない文字列の受け渡し以上のものにする要素です。selector: "datastore.aggrega.ai/engine=vector" を宣言したソケットは、一致するキーと値のペアのラベルを持つ Components への配線のみを受け付けます。エージェントが自身の primary_datastore ソケットを relational の Component に配線しようとすると、明確なセレクター違反の診断とともに Static Analyzer で失敗します。セレクターは Kubernetes 形式のラベルセレクター文字列で、=、!=、in (...)、notin (...)、キーのみ、!key の各形式による要件をカンマで AND 結合したものです。これは Feature の appliesTo と同じ文法です。文法については vocabulary/modifier-system.md を、エンジンのセマンティクスについては architecture/13-catalog-and-registry.md §2「Kubernetes-Style Selectors」 を参照してください。これらの形式以外の要件は、別のセレクターとして解釈されるのではなく拒否されます。空の要件(先頭、末尾、または連続するカンマ)、空白や =、!、(、)、カンマのいずれかを含むキー、閉じ括弧のない集合は、そのソケットを通じてエッジを配線するすべてのビルドを、要件を示して停止させます。したがって、フロントエンドを除外するためのソケットは selector: "tier!=frontend" と記述します。"!tier=frontend" は拒否されます。! はラベルキーのみを指すためです。
アドホックソケット — ソケットを宣言することで得られるもの、および宣言なしで作成者ができること。 Aggregate の作成者は、この usesSchema が宣言していないソケット名で、自身のコンポーネントに uses: エントリを記述できます。usesSchema をまったく宣言していない Component でも同様です。エッジは構築されます。カタログがソケットについて何も述べていないことは、その接続が想定されていなかったことを意味するのであって、禁止されていることを意味するのではありません。アプリケーションのトポロジーを所有するのは開発者です。
このようなアドホックソケットが失うものは、宣言されたソケットが提供するものそのものです。そのすべてが usesSchema エントリにあるためです。selector がないため、エッジがどのコンポーネントに到達できるかを制約するものはなく、ノード間の型安全性チェックで評価する対象もありません。inject: 許可リストもありません。エッジごとの valueSchema もないため、エッジごとの values: には照合される契約も、継承する宣言済みデフォルトもありません。infraSchema も失いますが、いずれにせよそのようなソケットではその契約に到達するものはありません。エッジごとの infra は Release のエッジエントリに記述され、Release のエントリは利用側 Component が宣言するソケットしか指定できないためです。変わらないのは、エッジが運べるものです。すべての inject エントリの from: は依然としてターゲット Component の schema.provides が宣言するキーを指定する必要があり、ターゲットも存在している必要があります。どちらも宣言されたソケットの場合と同様にビルドを停止させます。
「inject: 許可リストがない」は、ブラックボックス宣言ではなく制約の不在として読んでください。両者は見た目が似ていますが、動作は正反対です。アドホックソケットを通るエッジは配信を自由に指定できます。メカニズムが外れることになる許可リストは存在せず、値を内部で処理すると約束したエンティティもありません。前述のブラックボックスによる拒否は、エンティティが実際に宣言し、inject: 許可リストなしで残したソケットに適用されます。その省略はエンティティが想定した接続についての表明であり、アドホックソケットはそのような表明を行いません。
配信は同じ経路であり、レンダリングされた成果物に違いは記録されません。 アドホックエッジの inject ブロックは、宣言されたソケットのものとまったく同様に解決・配信されます。各 from: キーはターゲットの評価済み provides から読み取られ、作成者が選んだ配信キーで利用側ノードのインジェクションコンテキストに置かれ、そこからレンダリングされた成果物に届きます。配信経路は 1 つであり、その経路上にソケットが宣言されたかどうかで分岐するものはありません。宣言されたソケットが追加できるのは内容、つまり valueSchema や infraSchema が補うエッジごとのデフォルトです。そのため、宣言されたソケットがそのような契約を持たない場合、同じエッジはどちらの種類のソケットでも同一にレンダリングされます。宣言は接続についての事実であり、レンダリングされるものへの入力ではありません。
アドホックソケットでのエッジごとの values: は受け付けられ、検証されないまま .context.uses.<alias>.values で利用側の Recipe に届きます。照合する valueSchema がないため、どのキーもチェックされず、拒否されることもありません。これはアドホックソケット特有のことではなく、そのピラーの契約を記述していない宣言済みソケットも、エッジごとの設定を同様に扱います。アドホックソケットが変えるのは、ソケットを宣言しない限り契約を追加できないという点です。そのようなエッジでは .context.uses.<alias>.infra は空です。エッジごとの infra を提供する面は、宣言されていないソケットを指定できないためです。
出力されるグラフのすべてのエッジは、自身がこの 2 つのどちらであるかを記録するため、利用側がそれを推測する必要はありません。また、すべての接続を宣言済みのソケット経由にしたい組織は、それをガバナンスポリシーとして要求できます。ここでソケットを宣言することは引き続きより良い方法であり、標準ライブラリのカタログもそうしています。宣言済みのソケットは、エッジが到達できるコンポーネントを制約する selector、inject: 許可リスト、独自のデフォルトを持つエッジごとの契約、そして説明を備えます。これは、想定された接続をレビュー可能な形で表明したものであり、それを行うエンティティとともにバージョン管理されます。アドホック形式はエスケープハッチであり、新しいデフォルトではありません。2 つの面は意図的にこの方法では開かれていません。Feature アタッチメントの uses は、アタッチされた Feature が宣言するソケットしか指定できず、Release のエッジごとの uses は、利用側の Component が宣言するソケットしか指定できません。
実例 examples/adhoc-uses-socket/ は、1 つの利用側に両方の種類のエッジを構築し、配信された 2 つの値をレンダリング出力に並べて示すとともに、宣言されていない from: キーが引き起こす停止も示します。
ソケット名のタイプミスは、停止ではなく助言として表面化します。 宣言されていないソケット名は正当であるため、綴りを誤ったソケット名は、作成者が意図したソケットを配線するのではなく、それ自体が独立したアドホック接続になります。そして、その上を何も流れないままビルドは成功し続けます。コンパイラは、この usesSchema が宣言する名前から 1 編集以内のソケット名を、両方の綴りを示す警告として報告します。errors/warnings.md の「Uses-socket near-miss lint」を参照してください。この警告がビルドの判定を変えることはありません。コンパイラは、作成者がソケットにどのような名前を付けるかを取り締まりません。
usesSchema と featuresSchema の関係。 どちらも宣言的なテーブルであり、どちらも同一のセマンティクスを持つ inject: 許可リストを備えますが、ソケットとスロットは別物であり、互換ではありません。usesSchema はコンポーネント間のエッジ、つまりトポロジーグラフを管理し、どのソケットが契約を持つかを宣言します。featuresSchema はアタッチメントスロットを管理し、スロットは列挙ではなく名前付きのバインディングポイントです。どのスロットも宣言していない名前でのアタッチメントは、コンポーネント自身のブロック上では正当です。(ソケットが接続のために宣言するスロットは唯一の閉じた集合であり、これは上記の「Slots each connection fills」で述べたとおりです。)2 つの面はこの点で収束しています。宣言されていないソケット名でのコンポーネント自身の uses: エントリも正当です。しかし両者は区別されたままです。宣言されていないスロットは、宣言済みスロットに影響を与えない Component 上の自由なアタッチメントであるのに対し、宣言されていないソケットは、セレクターもエッジごとの契約も持たないエッジです。多くの Components は両方を宣言し、2 つのテーブルは互いに独立して組み合わされます。
アタッチメントスロット: featuresSchema
Component は featuresSchema ブロックを通じてアタッチメントスロットを宣言できます。各スロットは、Component が Feature のアタッチを期待するバインディングポイント(ルートパスワード、API キー、認証トークン、アイデンティティバインディングなど)を名指しし、どの Feature がそれをバインドできるか、およびフィルのマテリアルをどのように配信できるかを制約します。
このセクションは Component 自身のスロットについて説明します。ソケットが接続ごとに宣言するスロットは、これとは異なり閉じた集合です。トポロジーソケットの「各接続が埋めるスロット」を参照してください。
スロットを宣言しても、アタッチメントの面は閉じません。 作成者は、どのスロットも宣言していない名前で Feature をアタッチでき、そのアタッチメントはフリーアタッチメントになります。これは完全に正当であり、単に宣言済みスロットにバインドされていないだけです。この開放性により、1 つのカタログエンティティが、カタログをフォークすることなく 2 つの異なるデプロイ形態に対応できます。
- コンシューマーごと。 各インスタンスが自身の Feature でスロットを埋めるため、各コンシューマーは独自にレンダリングされた認証情報を得ます。
- 共有。 どのインスタンスもスロットを埋めず、代わりに 1 つの認証情報をより広いスコープ(サブシステム、または Release の境界)で一度だけアタッチし、その配下のすべてのコンポーネントにカスケードさせます。これにより、すべてのコンシューマーがその 1 つの宣言から埋められます。何がレンダリングされるかは実現方法に従います。Secret をレンダリングする実現方法では、コンシューマーごとに同じマテリアルを持つ Secret が 1 つずつレンダリングされます。すべてのコンシューマーを既存の Secret に向ける実現方法では、何もレンダリングされません。
作成者は、何をアタッチするかによってこれらを選択します。カタログエンティティはどちらの場合も同じです。
この開かれた面で停止する形態が 1 つあります。コンポーネント上に別の名前で書かれたフィルです。 コンポーネント自体に書かれたアタッチメント(Aggregate 内のそのコンポーネント自身の features: ブロック、またはその 1 つのコンポーネントに対する Release のエントリ)が、どのスロットも宣言していない名前を持ち、かつその Feature が、すべてのスコープが畳み込まれた後にそのコンポーネント上で何もバインドしていないスロットの selector を満たす場合、ビルドは停止します。これは、スロット向けのフィルが誤った名前で書かれたときにとる形態です。放置すればスロットが空のままフリーアタッチメントとなり、空のまま残された任意スロットはビルドが成功しても何も配信しません。メッセージはアタッチメント、コンポーネント、Feature、およびその Feature が適合する空のスロットそれぞれを名指しし、対処法はスロットの名前でアタッチすることです。これは認証情報だけでなく、すべての Feature に当てはまります。面上のそれ以外はすべて自由なままです。Feature がどの宣言済みスロットにも適合しないアタッチメント、適合するスロットがすべてバインドされた後の追加のアタッチメント、そしてコンポーネントがサブシステムや Release の境界から継承するアタッチメントです。したがって、上記の共有形態は影響を受けません。selector を宣言しないスロットは、どの Feature 向けかについて何も述べないため、どのアタッチメントもこの方法でそのスロットに照合されることはありません。この停止は errors/fatal-halts.md の「An attachment written under another name fits a slot its component leaves empty(別の名前で書かれたアタッチメントが、そのコンポーネントで空のままのスロットに適合します)」で説明しています。
2 つの形態は組み合わせられ、より近い方が優先されます。 作成者は両方を同時に行えます。より広いスコープで Feature をアタッチしてそのスコープ配下のすべてのコンポーネントに届け、異なるものが必要な 1 つのコンポーネントでスロットを埋めます。コンポーネントスコープのフィルがフィールド単位で優先されるため、変更するフィールドだけを記述し直せばよく、残りは引き続きより広いアタッチメントから得られます。スロットを埋めなかった兄弟コンポーネントは、より広いアタッチメントをそのまま保持します。アノテーション駆動のアタッチメントや合成された Aggregates との相互作用を含む完全な優先順位ルールは、vocabulary/labels-and-annotations.md の「Attachment precedence」にあります。
Component 上のスキーマ定義:
spec: featuresSchema: root_password: inject: [] description: Root database password. Recipe controls delivery (Black-Box). user_password: inject: [env, file] description: Application user password, auto-generated if omitted. replication_password: inject: [] description: Replication password for HA setups.フィールドのセマンティクス:
| フィールド | 種類 | デフォルト | 意味 |
|---|---|---|---|
required | bool | false | スロットが最終的にバインドされなければならないことを宣言します。この Component のインスタンス上でスロットの名前を何もバインドしない場合、ビルドは停止します。この判定は、アタッチメントのカスケード全体を経た後にインスタンスが保持するアタッチメント集合に対して行われるため、インスタンスが継承するスコープで宣言されたアタッチメントは、インスタンス自体に書かれたフィルとまったく同じようにスロットを満たします。診断はコンポーネントとスロットを名指しします。 |
inject | string[] | — | 許可される inject 配信メカニズムの許可リストです。[](空)はブラックボックスを意味します。Recipe が内部で配信を制御し、マテリアルが workload に配信されることはありません。[env, file] は透過を意味します。フィルのマテリアルは列挙されたメカニズムを通じて配信できます。usesSchema[].inject と同じセマンティクスです。 |
description | string | — | 人間向けのドキュメントで、IDE とハブで表示されます。 |
selector | string | — | どの Feature がこのスロットを埋められるかを制約する、任意の Kubernetes 形式のラベルセレクターです。usesSchema ソケットの selector のスロット版であり、同じ文法と同じネイティブのラベル照合エンジンを使います。静的解析中に、アタッチされた Feature 自身のラベルに対して評価されます。ラベルがこれを満たさないフィルは停止し、文法が受け付けないセレクターも、読み取れなかった要件を名指しして停止します。省略すると、フィルに制約を課しません。 |
sensitive | bool | false | このスロットをバインドするものが何であれ、シークレットマテリアルを扱うことを宣言します。特定のフィルではなくバインディングポイントについての記述です。後述の「スロットを機密として宣言する」を参照してください。 |
スロットが制約するのはどのフィルがそれをバインドできるかであり、フィルが何を設定するかではありません。スロットレベルの values や infra のコントラクトは意図的に存在しません。アタッチされた Feature 自身の schema: がそれらの柱を所有するため、各コントラクトの置き場所はちょうど 1 つです。
スロットの selector は、Component がどの Feature がスロットを埋められるかを絞り込む手段です。たとえばプロバイダー固有の認証情報 Feature(feature.aggrega.ai/kind=secret, provider=helm)に絞り込む場合で、FeatureRecipe を名指しする必要はありません。これは usesSchema ソケットのセレクターが依存エッジのターゲットを絞り込むのとまったく同じです。コンパイラはセレクターをアタッチされた Feature のラベルに対してのみ評価します。フィルが持つラベルを読み取り、セレクターがそれらを許可するかどうかを報告します。どのラベルを要求することに意味があるかはカタログ作成上の選択であり、コンパイラが課すルールではありません。
スロット名のタイプミスは停止ではなく助言として表面化します。 宣言されていないアタッチメント名は正当であるため、スロット名のスペルミスは、作成者が意図したスロットを埋めるのではなくフリーアタッチメントになります。コンパイラは、宣言済みスロット名から 1 編集以内のアタッチメント名を、両方の綴りを名指しする警告として報告します。errors/warnings.md の「Attachment-slot near-miss lint」を参照してください。この警告がビルドの判定を変えることはありません。コンパイラは、作成者がアタッチメントにどのような名前を付けるかを取り締まりません。アタッチメントの Feature がその selector を満たすスロットから 1 編集の名前には警告は出ません。そのスロットが最終的に空になる場合は、上述の停止が代わりにそのアタッチメントを報告し、別のものがスロットをバインドする場合は、そのアタッチメントは通常の追加アタッチメントとなります。
スロットを sensitive として宣言する
スロット上の sensitive: true は、利用側自身の要求を表明します。このポイントにバインドされるものは、すべて秘密情報を扱います。
spec: featuresSchema: password: selector: "feature.aggrega.ai/kind=secret" sensitive: true inject: [env] description: "Optional database password credential."これはスキーマのリーフの sensitive: true とは本質的に異なる情報であり、その便宜的な重複ではありません。標準ライブラリのカタログには両方が必要です。参照可能な認証情報は provides.name と provides.key(リソースのロケーターと、その中のデータキー)を公開しますが、どちらも sensitive ではありません。Kubernetes の Secret の名前は公開情報であり、その中のキーも同様です。それでも、その認証情報が埋めるスロットが秘密情報を扱うことは疑いありません。リーフは「このデータは秘密情報である」と述べ、スロットは「このバインディングポイントは秘密情報を扱う」と述べます。2 つの主張は異なる対象についてのものであり、互いに独立して成り立ちます。
実際上の帰結として、この要求は充填ではなくバインディングポイントに付随します。sensitive なリーフを一切宣言しない Feature(ターゲットエンジンが認証情報を所有し、作成者が何も記述しないため)であっても、sensitive なスロットにバインドされれば、スロットがそう宣言しているため sensitive なアタッチメントになります。逆も成り立ちます。sensitive なリーフを宣言する充填は、そのような宣言をしていないスロットにバインドされる場合でも、どのスロットにもバインドされないフリーアタッチメントである場合でも、sensitive なアタッチメントです。
この宣言は、特定の記述ブロックではなくアタッチメントのカスケードに従います。スロットの要求は、すべてのスコープが畳み込まれた後に最終的にバインドされた充填に適用されるため、より広いスコープの充填を置き換えるコンポーネントレベルの充填は、その要求をそのまま引き継ぎます。
スロット上の sensitive には、リーフレベルのキーワードと同じ上限があります。注釈を付けるだけで、暗号化、検証、拒否、配信メカニズムの強制、レンダリングされたバイトの変更は行いません。詳細は vocabulary/compact-form-authoring.md の「What the keyword does not do」にあります。
sensitive と compliance.aggrega.ai/data-class は異なる 2 つの軸であり、隣接して説明されていますが、決して混同されません。sensitive は 1 つのリーフまたは 1 つのスロットに付くブール値で、このデータ、またはこのバインディングポイントは秘密情報を扱うことを表します。compliance.aggrega.ai/data-class はノード全体に付く段階的なラベル(public、internal、restricted)で、コンポーネントが保持するデータにガバナンス上の識別を与えます。一方はデータ単位で二値、もう一方はノード単位で順序付きです。どちらも他方の代わりにはならず、1 つのエンティティが両方を持つこともできます。このラベルについては vocabulary/labels-and-annotations.md と architecture/08-credential-model.md の「Data governance around credentials」で説明しています。
featuresSchema からのスキーマ射影
宣言されたスロットは、アタッチメントブロックの形状を記述する JSON Schema 2020-12 のフラグメントに射影されます。これに対して検証されるフィルは 2 種類あります。インポートされたモジュールが提供するコンポーネントのアタッチメントブロック(それをインポートするコンポジションがビルドされた時点で検証)と、より広いスコープで宣言されたアタッチメント(それが届く各コンポーネント上のスロットに対して検証)です。Aggregate 自身が宣言するコンポーネントのアタッチメントブロックは、代わりに Aggregate のドキュメントスキーマとスロットの inject 許可リストによって検査され(後述)、フラグメントは、どのフィルに対しても両者が同じ判定に至るように形作られています。射影がディスクに書き出されることはなく、メモリ上にのみ存在します。Component の schema: でアタッチメントの柱を手書きする必要はありません。
入力の featuresSchema:
featuresSchema: root_password: inject: [] user_password: inject: [env, file]射影されたフラグメント(メモリ上、コンパクト形式での表現):
# The OUTER object is open: an attachment under a name no slot declares is# admitted, because a free attachment is legal authoring.root_password: type: { type: string } description: { type: string } values: type: object additionalProperties: true # inject admits only an empty block — inject: [] means the Recipe controls # delivery, so a fill may name no mechanism inject: {}user_password: type: { type: string } description: { type: string } values: type: object additionalProperties: true inject: env: { type: array } file: { type: array } # arg is absent — not in the inject allowlist2 つの階層は独立しています。外側のオブジェクトは開いているため、宣言されたスロットが、エンティティが列挙していないアタッチメントを禁止することはありません。宣言された各スロット自身のフラグメントは閉じているため、宣言されたスロットに実際にバインドされる充填は、引き続きそのスロットの形状に制約されます。
フラグメントが記述するのは形状のみです。どのスロットがバインドされなければならないかについては何も述べません。required とされたスロットは、より広いスコープからカスケードしてくるアタッチメントによってバインドされることがあり、その場合このフラグメントが記述するブロックは空になるためです。したがってこの要件は、個々のブロックが宣言する内容ではなく、コンポーネントが最終的に持つアタッチメントの集合に対して検査されます。記述されたブロックに対して問われるのは 2 つの問いのうち一方だけなので、両者が矛盾することはありません。
許可されるキーは、アタッチメントがどこでも持てるキーと同じです。そのため、フリーアタッチメントで有効なキーは、スロットの充填でも有効です。許可リストに含まれる各配信メカニズムは配信エントリのリストであり、inject: がどこでも取る形状と同じです。スロットが絞り込むのは出現してよいメカニズムの名前であり、エントリの形ではありません。
inject 許可リストが適用される場所
許可リストは、スロットの両側を 2 つの異なるステップで拘束します。
Recipe の Workload に対しては、レンダリングステップで適用されます。コンテナのアタッチメントエントリを通じてスロットを参照する Workload は、エンティティが宣言したスロットを指定し、かつそのスロットの inject 許可リストが許す配信メカニズムを選択しなければなりません。ブラックボックスのスロット(inject: [])、許可リスト外のメカニズム、またはエンティティが宣言していないスロットへの参照は、ビルドを停止させます。診断は Recipe、コンテナのパス、問題のスロットを示し、カタログの不備として分類されます。誤っているのは Recipe だからです。
Aggregate 自身のアタッチメントに対しては、アタッチメントが解決される時点で、あらゆるレンダリングより前に適用されます。宣言されたスロットにバインドされる充填上の inject: ブロックは、そのスロットの許可リストが許すメカニズムのみを指定でき、ブラックボックスのスロットは何も許しません。空の許可リストは「この配信は Recipe が内部で行う。配信を指示しないこと」を意味し、そのスロットに配信を記述するとビルドが停止します。診断はアタッチメントの位置に示され、スロットと問題のメカニズムに加え、スロットが何らかのメカニズムを許す場合はそれらも示します。誤っているのは Aggregate なので、開発者の不備として分類されます。空の inject: {} ブロックはメカニズムを何も指定しないため、配信を指示せず、ブラックボックスのスロットを含むすべてのスロットで受け入れられます。これは、Aggregate が宣言するコンポーネント上でも、インポートされたモジュールが提供するコンポーネント上でも、より広いスコープで宣言されたアタッチメント上でも同様です。フリーアタッチメント(どのスロットも宣言していない名前のもの)にはこのような制約はありません。許可リストはブロックではなくスロットに属するためです。
コンパイルパイプライン全体の流れ、すなわち Aggregate のアタッチメントが認証情報の Feature(core/secret-value など)に、さらに実行中のワークロードに認証情報を配信するプロバイダー固有の FeatureRecipe にどう接続されるかは、examples/05-credential-features で具体的に説明しています。
呼び出し側が提示するキーとサーバーが検証するキー
あるコンポーネントがキーを検証する別のコンポーネントを呼び出す場合、両端がそれぞれ自分の側でキーを保持します。キーは各端が自ら宣言するスロットに置かれます。これは標準ライブラリのカタログが従う慣例であり、コンパイラはそのいずれも強制しません。コンパイラは各コンポーネントのスロットをそのコンポーネント自身のアタッチメントと照合し、その文字列をそのまま受け渡すだけで、あるコンポーネントが保持するものと別のコンポーネントが保持するものを比較することはありません。
- 呼び出し側が提示するキーは呼び出し側のものです。 このキーは、呼び出し側のソケットが接続ごとに宣言するスロットに置かれます(前述の「Slots each connection fills」を参照)。そのため、複数のターゲットに接続する呼び出し側は、ターゲットごとに 1 つのキーを保持します。
core/ai-agent/crewaiのmodelソケットはそのスロットをcredentialとして宣言し、その Recipes はそこを埋めた値をOPENAI_API_KEYとして配信します。core/gateway/litellm、core/gateway/kong、core/gateway/apisixのmodelsソケットも同様に宣言し、その Recipes は各接続のキーを、接続のエイリアスにちなんで名付けた専用の変数で配信します。これにより、ゲートウェイが提供する各モデルがそれぞれ専用のキーを保持します。代わりに Component が自身のスロットで宣言したキーは、そのコンポーネントが行うすべての接続に共通の 1 つのキーになります。 - サーバーが検証するキーはサーバー自身のスロットです。
core/ai-model/vllm、core/ai-model/tei、core/ai-model/tgiはそれぞれ省略可能なapi_keyを宣言し、それぞれの Recipes はそこを埋めた値を、サーバーがキーを読み取る変数として配信します。LiteLLM のモデルとゲートウェイは、LiteLLM がマスターキーと呼ぶキーのためにapi_keyを宣言します。 - どちらの端も相手のアタッチメントを参照しません。 接続上のアタッチメントは呼び出し側のアタッチメントの 1 つであり、呼び出し側のレンダリングにのみ届きます。サーバーのレンダリング出力は、そこに届く接続が何を運んでいても同じです。
requiredと指定されたスロットは、それを宣言したコンポーネントが満たすべきものであり、接続先のコンポーネントが満たすものではありません。また、一方の端のスロットを埋めても他方の端には何も埋まりません。したがって、キーを両端で宣言することは重複ではなく最小限の構成です。 - 両端は 1 つのパラメータを読み取ります。そのため、呼び出し側が提示するキーとサーバーが検証するキーが食い違って記述されることはありません。
# Aggregate fragment — one parameter feeds both endsspec: parameters: model_key_secret: { type: string } components: model: type: core/ai-model/vllm values: { model: Qwen/Qwen2.5-0.5B-Instruct } features: api_key: # the key the server verifies type: core/referenced-secret values: origin: "{{ .parameters.model_key_secret }}" key: api-key agent: type: core/ai-agent/crewai # values (role, goal, backstory, …) elided uses: model: local: target: model features: credential: # the key the caller presents type: core/referenced-secret values: origin: "{{ .parameters.model_key_secret }}" key: api-key1 つのキーを検証するサーバーは、呼び出し側を区別できません。vLLM、TEI、TGI はそれぞれ単一のキーを検証するため、サーバーに届く接続がいくつあっても、すべての呼び出し側が同じキーを提示します。両端が 1 つのシークレットを参照するか、それぞれ独自のシークレットを保持するかは、各 provider がどこで参照によってシークレットを解決するかによって決まり、各端の実現方法は Manifest が選択します。Credential Model で両方のケースを詳しく説明しています。
コンポーネントが自身のために保持する資格情報(たとえば自身のセッションに署名するためのキー)は、他と同様に自身の featuresSchema: のスロットです。ソケットの 1 つを介して接続するデータストアに提示するパスワードは前述の呼び出し側のキーにあたるため、その接続上に credential として置かれます。core/gateway/kong の backend ソケットがこれを宣言し、そのワークロード合成用 Recipes はこれを KONG_PG_PASSWORD として配信します。また、core/gateway/litellm の cache_store ソケットは、セマンティックキャッシュがストアに提示するパスワードのためにこれを宣言し、REDIS_PASSWORD として配信されます。1 つの接続がペア(アクセスキー ID とそのシークレット)を提示する場合は、core/ai-agent/agenta-api の store ソケットのように、シークレット側を credential、ID 側を credential_id とします。
セルフインジェクト: spec.inject
Component は、セルフインジェクトの配信メカニズムを許可リストとして指定するトップレベルの spec.inject: 配列を宣言できます。これが存在する場合、開発者は Aggregate の コンポーネントレベル で inject: ブロックを使用し、Component 自身の values: または provides: のキーを、その Component 自身の配信パイプ(コンテナの環境変数、マウントされたファイル、またはプロセス引数)へ直接注入できます。spec.inject: が存在しないか空の場合、コンポーネントレベルのセルフインジェクトは禁止されます。この場合、すべての内部配線は Recipe が制御します。これは、usesSchema[].inject: [] と featuresSchema[].inject: [] がそれぞれコンポーネント間の配信と認証情報の配信に適用する Black-Box パターンと一致します。
# Component declares its self-inject allowlist:apiVersion: aggrega.ai/v1beta1kind: Componentmetadata: name: core/web-server version: 1.0.0 labels: component.aggrega.ai/type: serverspec: inject: [env, file] schema: values: log_level: { type: string, default: info } tls_enabled: { type: boolean, default: false } provides: health_endpoint: { type: string }# Aggregate fragment — developer dictates self-inject delivery:components: api: type: core/web-server values: log_level: debug tls_enabled: true inject: env: - in: LOG_LEVEL value: '{{"{{"}} .values.log_level }}' - in: TLS_ENABLED value: '{{"{{"}} .values.tls_enabled }}' file: - in: /etc/web/health-probe from: health_endpoint各 value: テンプレートは {{ ではなく {{"{{"}} で始まります。Aggregate のテキスト全体は、セルフインジェクトの解決が実行される前に、パラメータ補間のためにテンプレートとして一度読み込まれ、その時点では .values は存在しません。このエスケープによって {{ が戻され、セルフインジェクトの解決で評価されます。独自の二重波括弧を含むテキストを参照してください。
フィールドのセマンティクス。 spec.inject: はメカニズム名の配列です。定義されている値は次の 3 つです。
env— コンテナ内の環境変数。file— マウントされたファイルのパス。arg— プロセスのコマンドライン引数。
このセマンティクスは usesSchema[].inject および featuresSchema[].inject と完全に同じです。語彙も同じで、省略時は同じ Black-Box パターンになり、Aggregate 側での記述形式も同じです。違いはソースにあります。usesSchema[].inject はコンポーネント間の依存関係の provides がコンシューマの配信パイプへどう流れるかを制御し、featuresSchema[].inject は認証情報がコンテナへどう届くかを制御し、spec.inject は Component 自身の values と provides が Component 自身のコンテナへどう届くかを制御します。
記述上の指針。 spec.inject: [env, file] を宣言する core/web-server Component は、透過的な配信を選択します。どの環境変数名がどの値を運ぶかは Aggregate の作成者が指定します。spec.inject: [] を宣言する(またはフィールドを省略する)Component は、配信を不透明に保ちます。どのフィールドがどのコンテナ変数へ流れるかは Recipe の valuesMapping: が決定し、開発者は Aggregate で上書きできません。Black-Box パターンは安定した契約を持つ Components に適しています(DB パスワードを POSTGRES_PASSWORD 環境変数へ配線する方法を Recipe が把握している core/postgres-db Component など)。透過的なパターンは、開発者の意図が正当に配信の詳細を指定する Components に適しています(アプリケーションが LOG_LEVEL を、開発者がカスタマイズしたい非標準の変数名から読み取る core/web-server など)。
エラーモード。 spec.inject: が存在しないか空の Component に対して開発者の Aggregate が inject: ブロックを使用すると、ワークスペースのロード時にビルドが停止します (「Self-inject on a component without an allowlist (許可リストのないコンポーネントでのセルフインジェクト)」)。許可リストにないメカニズムを使用する inject: ブロックも同じ条件で停止し、そのメカニズムと許可リストが認めるメカニズムを示します (「Self-inject mechanism not in the component’s allowlist (セルフインジェクトのメカニズムがコンポーネントの許可リストにない)」)。セルフインジェクト、コンポーネント間インジェクト、認証情報インジェクトの間で配信キーが衝突した場合も停止します (「Duplicate delivery key across inject sources (インジェクト元の間で配信キーが重複している)」)。各エラーのメッセージ形式については errors/fatal-halts.md を参照してください。
カタログの作成: ベース Components の拡張
プラットフォームアーキテクトは extends キーワードを使い、企業やコミュニティのベースラインの上に特化したインターフェースを重ねます。拡張は構造を合成し、データの柱をまるごと継承します。コンパイラはベースから下へチェーンをたどります。この 2 つの側面は異なる振る舞いをし、その違いこそが作成モデルの全体です。
拡張が合成するもの。 以下の面はチェーンに沿ってマージされます。キーごとに拡張する側の Component が優先され、リストはベースを先頭に重複なく連結されます。
| 画面 | 合成のされ方 |
|---|---|
metadata.labels | キーごとにマージされます。共通のキーでは拡張する側の Component の値が優先されます |
metadata.annotations | キーごとにマージされ、優先順位も同じです。そのため、ベースの存在の要求はそれを拡張するすべての Component に届きます |
spec.featuresSchema | アタッチメントスロットは和集合になります。拡張する側の Component が再宣言したスロットは、ベースの同名のエントリを置き換えます |
spec.usesSchema | トポロジソケットは和集合になり、名前ごとの置き換えのルールも同じです |
spec.inject | 2 つのセルフインジェクトの許可リストは、ベースのエントリを先頭に連結され、重複は除かれます |
spec.assertions | 名前付きルールはベースのルールを先頭に蓄積されます。この面だけは名前ごとの置き換えを一切認めません。後述の「アサーションの継承は加算的です」を参照してください |
拡張する側の Component が追加するソケットは、エッジごとに独自の valueSchema と infraSchema を持つことができます。これらはそのソケットのエッジに対する契約であり、Component 自身の柱への追加ではありません。
metadata: の残りは、それを宣言したドキュメントにとどまります。 チェーンを下って伝わるメタデータは labels と annotations だけです。name、version、description、maintainers、license、repository、home、keywords は拡張する側の Component 自身のものであり、作成されたとおりに読み取られます。description: を省略した Component は、ベースのものを借りるのではなく、説明を持ちません。識別情報と出自は読んでいるドキュメントに属するため、ラッパーがラップ対象と取り違えられることはありません。
拡張がまるごと継承するもの。 3 つのデータの柱である values、infra、provides は合成されません。拡張する側の Component は柱の内容を記述しません。リテラルのマーカー schema: inherited を書き、ベースの schema: ブロックをベースが作成したとおりに受け取ります。どの深さのチェーンでも、その中のすべての Component がチェーンのルートのブロックを変更なしで持つため、リーフに対する aggrega inspect --resolved はルートと同じ柱を示します。
公開されている Component のスキーマは、3 つのありうる結果のうちどれが正当かを定め、残りの 2 つをドキュメントの読み込み時に拒否します。それぞれ異なる誤りであるため、診断もそれぞれ異なります。
schema:の下に柱の内容を持つextends:は拒否されます。Component の契約はベースの契約であり、2 つ目の異なる契約を置く場所はありません。schema:をまったく省略したextends:は拒否されます。省略を認めると、読み手は継承された柱のブロックと書き忘れたブロックを区別できなくなります。extends:のないschema: inheritedは拒否されます。このマーカーは柱の取得元を示しますが、この Component には取得元となるベースがありません。
拡張する側の Component はキーの集合を作り変えられません。 柱のキーを宣言しないため、ベースが宣言するキーを隠すことも、削除することも、型を変えることもできず、独自のキーを追加することもありません。新しい柱のキーは、その契約を所有する Component に置くべきものです。ベースが公開するものは、それを拡張するすべてのものがまったく同じように公開します。
特化は assertions: を通じて制約を強めます。 特化がベースの柱より狭い範囲しか認めてはならない場合、たとえばより狭い数値範囲や、継承した enum: の部分集合の場合は、自身の assertions: ブロックでそれを表現します。そこに置いたルールが、継承したスキーマなら受け入れる値を拒否します。制約の強化はこの面で行います。後述の「assertions: ブロック」を参照してください。
直前の 2 つの段落は 1 つのルールであり、片方だけでは誤解を招きます。キーの集合を狭めることはできず、制約を強めることはできます。 前者だけを読むと特化は何も制約できないと結論し、後者だけを読むと契約を作り変えられると結論してしまいます。どちらも誤りです。キーの集合はベースによって固定され、その中で認められる値は述語によって狭められます。
アサーションの継承は加算的であり、ルートから順に蓄積されます。 拡張する側の Component のインスタンスは、Component 自身が宣言するルールに加え、そのチェーンが宣言するすべてのルールに照らして検査され、継承したルールが先に評価されます。どの深さのチェーンでもルールはチェーンのルートから下へ蓄積されるため、インスタンスが複数のルールに違反する場合は、チェーンの最も上で宣言されたルールが報告されます。つまり、最も基本的な契約が最初に応答します。
継承は置き換えではなく加算であるため、拡張する側の Component は継承したルール名を再利用して異なるルールを宣言することはできません。これは extends チェーンがカタログに対して解決される時点で拒否され、診断には両方の Components と共通の名前が示されます。この検査にはベースの Component が必要なため、カタログの検証時やビルドがチェーンを解決する時に報告されます。拡張する側のドキュメントを単独で検証しても検出できません。ルール名は安定した識別子であるため、ベースのルールを削除することも、黙って名前を変えることも選択肢にはならず、修正方法は拡張する側の Component での名前の変更です。継承したルールを同じ名前でバイト単位で同一に再記述することは、何もしない操作として受け入れられます。
aggrega pull はベースを取得します。 ベースは、それを拡張する Component に到達するすべての Release の依存関係であり、他に何かがそれを指定しているかどうかは関係ありません。aggrega pull は各 extends: をチェーンの終端までたどり、どのカタログディレクトリにもないベースをレジストリから取得し、すべてのベースを Release のロックファイルに記録します。各ベースは、それを指定する Component の spec.extends から参照されます。ビルドはそこからベースを読みます。そのため、Manifest がマッピングするのはラッパー自身の型だけです。ベースに独自のマッピング行が必要になるのは、Aggregate がベースのインスタンスも宣言している場合だけです。カタログ全体に対する aggrega validate も同じ方法でベースを読むため、レジストリに公開されたベースは、pull が取得するまで、aggrega pull を示してそこで拒否されます。
スキーマの内容の形式については architecture/13-catalog-and-registry.md §3 を参照してください。
例 A: ベース Component(企業のベースライン) プラットフォームアーキテクトが基盤となるエンタープライズサーバーを定義します。このベースは、必要な運用クラウドプリミティブのラベルを設定し、スキーマにセキュリティ上の制約を定めます。柱のブロックは変更なしで継承されるため、ここでの制約はすべて、作成されたとおりに各拡張 Component に届きます。
apiVersion: aggrega.ai/v1beta1kind: Componentmetadata: name: core/base-enterprise-server version: 1.0.0 labels: component.aggrega.ai/type: "server"spec: inject: [env] schema: values: # The corporate baseline constraint. Every Component extending this base # receives this leaf verbatim; none of them can restate or loosen it. tls_enabled: { type: boolean, enum: [true], default: true }
# An open range at the baseline. A specialization that needs a tighter # bound expresses it as an assertion, not as a redeclared schema leaf. timeout_ms: { type: integer, default: 5000 } assertions: # A baseline invariant. It is evaluated for instances of this Component AND # for instances of every Component extending it, under this same name. audit-window-is-observable: | {{- if lt (int .values.timeout_ms) 100 -}} {{- fail "the corporate baseline needs timeout_ms of at least 100 so requests are observable" -}} {{- end -}}例 B: 拡張する Component(ベースラインの特化)
ゲートウェイはそのベースラインから特化されます。ベースの柱をまるごと受け取り、独自の構造としてラベル、セルフインジェクトの仕組み、アタッチメントスロットを持つトポロジソケットを追加し、継承したタイムアウトをアサーションによって強めます。ベースラインの audit-window-is-observable ルールは再記述しません。このルールは継承されて先に評価されるため、このゲートウェイのインスタンスは 100 以上かつ 2000 以下という両方の範囲を満たす必要があります。
apiVersion: aggrega.ai/v1beta1kind: Componentmetadata: name: core/gateway/kong version: 1.0.0 labels: # Every Component declares the reserved base-ontology key, including one # that extends: the envelope requires it on the document itself. component.aggrega.ai/type: "server" api.aggrega.ai/protocol: "http" # merged with the base's labelsspec: extends: core/base-enterprise-server schema: inherited # values, infra and provides are the base's, verbatim inject: [file] # concatenates with the base's [env] -> [env, file] usesSchema: # a socket of its own; the base declared none backend: required: true selector: "component.aggrega.ai/type=stateful-server" inject: [env] featuresSchema: # a slot each connection through it fills credential: sensitive: true inject: [env] description: Password the gateway presents to the configuration backend this connection reaches. assertions: # The tightening. The inherited schema admits any integer for timeout_ms; # this gateway admits only 2000 or less, so the rule rejects a value the # inherited pillar block would accept. timeout-within-gateway-budget: | {{- if gt (int .values.timeout_ms) 2000 -}} {{- fail "the gateway must answer within 2000ms: set timeout_ms to 2000 or less" -}} {{- end -}}この core/gateway/kong インターフェースを物理的な Helm チャートに対して実装する Recipe については、entities/recipe の例 C(kong-gateway)を参照してください。
assertions: ブロック
Component.spec.assertions: は、Component の契約におけるアーキテクチャ上の不変条件を表す名前付きルールの任意のマップです。これは、どの Recipe が Component にバインドされるかにかかわらず、開発者の記述が満たさなければならないフィールド横断のルールです。各キーは失敗メッセージに現れるルール識別子であり、各値は Go テンプレートの本体です。コンパイラはスキーマ検証の後、Recipe のバインドの前に、インスタンスごとに記述順でこれらを評価します。最初に失敗したルールが、Loud Guardrails 契約に従い、そのルール自身のエラーメッセージでビルドを停止します。
spec: assertions: replication-needs-two-secondaries: | {{- if eq .values.architecture "replication" -}} {{- if lt (int .values.secondary.replicaCount) 2 -}} {{- fail "architecture=replication requires secondary.replicaCount >= 2" -}} {{- end -}} {{- end -}}上記のルールは Component の契約の性質です。どの Recipe がバインドされても(Bitnami チャート、手作りの代替、将来の実装)、レプリケーションモードには少なくとも 2 つのセカンダリレプリカが必要です。
assertions: は、拡張する Component が制約を強める場所です。 ベースを extends: する Component は、ベースのピラーブロックをそのまま継承し、自身のピラー内容を宣言しません。そのため、継承したスキーマより受け入れる範囲を狭める必要がある特化は、その制限を狭めたスキーマのリーフとしてではなく、ここで述語として記述します。つまり、継承したピラーが受け入れる値を拒否するルールです。具体例の組と継承の完全な挙動は、上記の「Catalog Authoring: Extending Base Components」にあります。ルールはチェーンに沿ってルートから順に蓄積され、継承したルール名を別のルールに再利用すると、置き換えが許されるのではなく拒否されます。
コンパイラは、2 つのルールが同時に満たされ得るかどうかを検査しません。 ルールはテンプレートの述語であり、コンパイラが推論する制約ではありません。そのため、どの値も同時には満たせないルールの組(少なくとも 100 を要求するベースと、最大 50 を要求する特化など)があっても、カタログの読み込み時に警告は出ません。これは通常の形で表面化します。インスタンスが記述されると、2 つのうち先に発火した方でビルドが停止し、そのルールのメッセージが記述者の目にするものになります。矛盾が事前に報告されることは期待せず、特化での制約強化をベースがすでに要求している内容と照らし合わせて確認してください。
assertions: は、本当の意味でのフィールド横断ルールに使用します。フィールドごとの制約(範囲、パターン、enum)は schema: のキーワードに、フィールドごとのカスタム述語はコンパクト形式の validate: に、条件付きの形状(サブツリーの制約が適用されるかどうか)は when: に記述します。完全な記述文法(テンプレートのコンテキストフィールド、{{ fail }} のメッセージの慣例、評価フェーズ、Component と Recipe の両方の役割にわたる具体例)については、templates/assertions-block.md を参照してください。