エンティティの分類
Aggrega のアーキテクチャは 4 つのドメインで構成され、それぞれが異なるペルソナに所有されて特定のエンティティ種別を収めています。さらに、再利用可能なスキーマ、マッピング、ワークロード、成果物のコンテンツを保持するティア 3 のライブラリ層(言語リファレンスのエンティティ階層モデルの第 3 層)があります。以下の全体図は、4 つのドメインとティア 3 のライブラリが互いにどのように関係するかを示しています。続く各セクションは、そのセクション自身のエンティティの図で始まり、その図では他のドメインのエンティティが破線の輪郭で描かれています。各エンティティの詳細な記述面(フィールド、スキーマ、例)は、言語リファレンスのエンティティカタログにあります。
graph TD
Intent["<b>Domain 1: Developer Intent</b><br/><i>Developer</i>"]
Catalog["<b>Domain 2: Platform Catalog</b><br/><i>Platform Architect</i>"]
Routing["<b>Domain 4: Routing & Policy</b><br/><i>Platform Operator / DevOps</i>"]
Infra["<b>Domain 3: Infrastructure Base</b><br/><i>Infrastructure Engineer / Ops</i>"]
Libs["<b>Tier 3: Libraries</b>"]
Intent -->|"requests, attaches"| Catalog
Intent -->|"binds via"| Routing
Routing -->|"attaches"| Catalog
Catalog -->|"resolved to"| Infra
Routing -->|"resolves, renders via"| Infra
Catalog -.->|"$ref"| Libs
Infra -.->|"$import"| Libs
コーパスは 4 つのドメインとティア 3 のライブラリ層にまたがります。
| # | エンティティ | ドメイン | 役割 |
|---|---|---|---|
| 1 | Aggregate | ドメイン 1 — 開発者の意図 | アプリケーショントポロジーの設計図 |
| 2 | Component | ドメイン 2 — Platform Catalog | 抽象的なコンピュートノードのインターフェース |
| 3 | Feature | ドメイン 2 — Platform Catalog | 運用上の特性(認証情報の Features を含む) |
| 4 | Recipe | ドメイン 3 — インフラ基盤 | プロバイダーごとの Component の実装 |
| 5 | FeatureRecipe | ドメイン 3 — インフラ基盤 | プロバイダーごとの Feature の実装 |
| 6 | Plugin | ドメイン 3 — インフラ基盤 | コンテンツアドレス指定された WebAssembly プラグイン(プロバイダーのレンダリング、パイプラインのステップ、リンティング) |
| 7 | Manifest | ドメイン 4 — ルーティングとポリシー | インターフェースを Recipes にマッピングする依存関係のロックファイル |
| 8 | Release | ドメイン 4 — ルーティングとポリシー | Aggregate を Manifest にバインドするデプロイルーター |
| 9 | SchemaLibrary | ティア 3 — ライブラリ | 再利用可能な JSON Schema 2020-12 の定義 |
| 10 | MappingLibrary | ティア 3 — ライブラリ | 再利用可能な Go テンプレートの断片 |
| 11 | WorkloadLibrary | ティア 3 — ライブラリ | 再利用可能な Workload テンプレートの断片 |
| 12 | ArtifactLibrary | ティア 3 — ライブラリ | 再利用可能な名前付き成果物バンドル |
この表が、記述用エンティティ種別、つまり作成者が kind: フィールドで宣言する種別のすべてです。Workload 種別は、独立したカタログエンティティではなく、Recipe の合成された入力に埋め込まれるプラットフォーム所有のコンテンツであるため(第 16 章を参照)、意図的に上の表には含まれていません。
Plugin は第一級の記述用エンティティであり、独自の種別、JSON Schema、カタログディレクトリを持ち、ドメイン 3 で Platform Ops が所有します。Plugin は WebAssembly 成果物へのコンテンツアドレス指定された参照であり、自身が実装する 1 つのソケット種別を宣言します。この分類には 7 つのメンバーがあります。provider(IR ノードをプロバイダー固有の成果物にレンダリングする)、linter(記述されたコンテンツに対して診断を発行する)、pipeline-step(feature-recipe-pipeline のステップ)、governance(ガバナンスの役割を担う。ラベルやアノテーションを変換するか、IR グラフまたはレンダリングされた成果物に対して受理/拒否の判定を返す)、cli(オペレーターがコマンドラインで呼び出す aggrega のサブコマンドを提供する)、parser(外部のソーステキストを正準的な構造化ツリーに変換する)、importer(外部のインフラストラクチャまたはエージェント定義のソースを Aggrega の記述用ファイルの草案に変換する)です。プロバイダーレンダリング用の Plugin(pluginType: provider)は、プロバイダーのレンダリングを担う単位です。自身がレンダリングするプロバイダー名を spec.provider.capabilities で宣言し、プロバイダーソケットのその他のメタデータも同じ spec.provider ブロックに保持します。コンパイラは参照を固定してルーティングし、WebAssembly ランタイムがバイトを実行します。コンパイラはプラグインが何をするかを解釈しません。プラグインは、WebAssembly 内に存在するドメイン固有のインテリジェンスを運ぶ手段です。その記述面とメタデータ面は language-reference/entities/plugin.md に記載されています。
ドメイン 1:開発者の意図(「何を」)
graph LR
classDef ext stroke-dasharray:5 4;
A["Aggregate<br/>The 'What'"]
CC["Component"]:::ext
CapC["Feature"]:::ext
EB["Release"]:::ext
A -.->|"Requests"| CC
A -.->|"Attaches"| CapC
A -->|"Binds via"| EB
- 役割:開発者。AI アーキテクチャ、認知ループ、アプリケーションの存続要件だけに集中します。CEL、OPA、物理ポートについての知識は必要ありません。
- 1. Aggregate:アプリケーショントポロジーの、マップベースの宣言的な設計図です。Release がビルドするルートの Aggregate としても、パラメーター化された再利用可能なモジュールとしても機能し、論理的な
componentsを定義するとともに、featuresの下に、振る舞いがアプリケーションの意図である Features をそのvaluesとともにアタッチします。入力がすべて運用上のものである Feature は、代わりにオペレーターが Release でアタッチします(ドメイン 4 を参照)。認証情報も同じfeaturesのアタッチ面で、認証情報の Feature を通じて要求します。そのための別のブロックはありません。parameters(コンパクト形式の語彙で記述された型付き契約)によって抽象的な容量要件を、valuesによってペイロードの状態を定義します。Component のインスタンスは、ドキュメントと Studio での表示のためのオプションのdescriptionフィールドをサポートします。ターゲットプラットフォームや名前空間をハードコードすることなく、「Zero-Port」の慣例(既存のコードが明示的に必要としない限りネットワークポートを抽象化すること)を推奨します。
ドメイン 2:Platform Catalog(「インターフェースとインテリジェンス」)
graph TD
classDef ext stroke-dasharray:5 4;
A["Aggregate"]:::ext
EB["Release"]:::ext
CC["Component<br/>The Compute Interface"]
CapC["Feature<br/>The Operational Trait"]
CD["Recipe"]:::ext
CapD["FeatureRecipe"]:::ext
A -.->|"Requests"| CC
A -.->|"Attaches"| CapC
EB -.->|"Attaches"| CapC
CC -.->|"Resolved to"| CD
CapC -.->|"Resolved to"| CapD
- 役割:Platform Architect。プラットフォームの「プログラマー」です。各コンポーネントを運用オントロジー上に位置付け、プログラム可能なポリシー(Wasm のミューテーターとバリデーター)を記述し、セマンティックなダックタイピングのラベルを確立します。
- 2. Component:コンピュートノードの抽象インターフェースです。運用的なクラウドオントロジー(例:
component.aggrega.ai/type: server)によって基本形を宣言し、ダックタイピングのラベル(例:model.aggrega.ai/capability: generative)によって認知的なアイデンティティを重ねます。featuresSchemaによって認証情報スロット(必須/任意、ブラックボックス/透過)を宣言し、schema:(JSON Schema 2020-12。通常はコンパクト形式の短縮記法で記述)を使って開発者の不透明なvaluesブロックを厳密に検証します。 - 3. Feature:モジュール化された運用上の特性です(例:データマスキング、DNS ルーティング、シークレット管理)。
appliesToのラベルセレクターを使って、特定のセマンティックラベルに動的にバインドします。Components と同様に、featuresSchemaによって認証情報スロットを宣言し、API キーのプロビジョニングを強制します。重要なのは、metadata.annotationsを使ってフラットな IR グラフ内の要素に明示的にタグを付けることで、下流の Wasm ポリシーバリデーターやレンダリングプラグインに、その Feature の設定ペイロードの扱い方を伝える点です。- 認証情報の Features:プラットフォームは認証情報の管理を Feature エンティティに統合しています。ラベル
feature.aggrega.ai/kind: secretを持つ Feature は認証情報の機能であり、シークレットストア(例:AWS Secrets Manager、HashiCorp Vault)へのクエリインターフェースを定義します。他の Feature と同じく、同じ面に同じ形でfeatures:の下にアタッチされます。ラベルは、そのアタッチが何を生み出すかを説明するためにカタログが保持するメタデータであり、コンパイラのどの分岐もそれを読みません。別個のシークレットストアやシークレット Recipe の種別はありません。認証情報の FeatureRecipe は他の FeatureRecipe と同じ形をしており、取得してから配信するパイプラインはどちらも同じで、injectの配信契約(env、file、arg)も共有されます。1 つのエンティティ、1 つのアタッチ用キーワード、レンダリングを通じた 1 つの修飾子実行パス。そして認証情報は Manifest のfeatures.typeの下にマッピングされます。
- 認証情報の Features:プラットフォームは認証情報の管理を Feature エンティティに統合しています。ラベル
ラベルとしてのオントロジー。 運用的なクラウドオントロジーは、トップレベルの spec.type フィールドではなく metadata.labels["component.aggrega.ai/type"] で宣言されます。この選択により、コンパイラのラベルセレクターエンジンがオントロジーの値を直接ターゲットにできます。Feature は appliesTo: "component.aggrega.ai/type in (server, worker)" を宣言するだけで、中核コンパイラに新しい Go のロジックを一切加えることなく、すべての server または worker コンポーネントに動的にアタッチできます。同じセレクターの仕組みはすべての Aggrega のラベルに適用されるため、Feature、ソケットセレクター、Release の境界マッピングは、カタログ独自のラベルキーをこのキーとまったく同じように読み取ります。
component.aggrega.ai/type は Aggrega のキーであり、その値の集合は閉じています。公開されている Component スキーマがプリミティブを列挙しており、それ以外の値を持つドキュメントは読み込み時に拒否されます。その際 E0215 がラベル名を示し、受け付ける値を列挙します。Aggrega が定義しない分類を必要とするカタログは、その隣に独自のラベルキーを追加します(Component スキーマは文字列値を持つ任意の追加ラベルキーを受け付けます)。そのため、新しい軸にかかるコストは自分のキー 1 つだけでコンパイラの新しいリリースは不要であり、予約キーはどこでも 1 つの意味を保ちます。これこそが、component.aggrega.ai/type in (stateful-server) に対して書かれた Feature が、互いに面識のない作者たちの Components に対して機能する理由です。
ドメイン 3:インフラ基盤(「実装」)
graph LR
classDef ext stroke-dasharray:5 4;
CC["Component"]:::ext
CapC["Feature"]:::ext
ENV["Manifest"]:::ext
EB["Release"]:::ext
CD["Recipe<br/>The Implementation"]
CapD["FeatureRecipe<br/>The Binding"]
T["Plugin<br/>The Wasm Plugin"]
CC -.->|"Resolved to"| CD
CapC -.->|"Resolved to"| CapD
ENV -->|"Resolves Interfaces to"| CD
ENV -->|"Resolves Interfaces to"| CapD
EB -->|"Renders via"| T
- 役割:インフラエンジニア/Ops。物理的な実態、ネットワークポートの割り当て、テンプレートのロジックを所有します。
- 4. Recipe:マルチプロバイダーの変換テンプレートです(例:Helm や Docker Compose)。
implementsキーワードによって、カタログコンポーネントとの厳格な 1:1 の API 契約を確立します。Recipe は開発者の.valuesを物理的な形式にマッピングします。物理ネットワークポート(例:5432)をハードコードし、.context.usesパイプを通じてターゲットのprovidesを読み取ることで、データベース名をハードコードせずに注入契約を満たします。 - 5. FeatureRecipe:
implementsキーワードによって、Featureを具体的なインフラ実装に明示的にマッピングします。capabilityでターゲットのプロバイダー機能(例:helm、compose)を必須とします。プラットフォームが認証情報の管理を Feature エンティティに統合しているため、FeatureRecipes は運用機能(データマスキング、DNS ルーティング、サイドカー注入)と認証情報の機能(ボールトの CRD 生成、シークレットボリュームのマウント)の両方を扱います。この全範囲をサポートするため、3 つの異なる実行ブロックをサポートします。pipeline:レンダリング後の Workload の変更のための、WebAssembly (Wasm) プラグインの順序付き配列です(例:JSONPatch による Envoy サイドカーの注入、シークレットボリュームのマウント)。sourceとvaluesMapping、workload、artifacts:Recipe が持つのと同じ 3 つの入力の種類で、リソース生成に使われ、Ops がベースコンポーネントと並べて静的テンプレートをネイティブにレンダリングできるようにします(例:新しいHTTPRouteCRD やExternalSecretCRD の生成)。injectMapping(レンダリング前のインターセプト):ベースの Recipe がレンダリングされる前に実行される、ネイティブな Go テンプレートブロックです。JSON 辞書を出力し、コンパイラはそれを呼び出し元の.context.injectメモリパイプの上にネイティブにディープマージします。これにより、Wasm を使わずに、呼び出し元の側で環境変数や接続文字列を変更できます。
- 認証情報の FeatureRecipe パターン:FeatureRecipe が認証情報の Feature(
feature.aggrega.ai/kind: secretのラベル付き)を実装する場合、標準の「2 部構成の Plugin 原則」が適用されます。pipelineは Fetcher プラグイン(ボールト固有の CRD を生成)に続いて Injector プラグイン(シークレットをターゲットコンテナにマウント)を連結します。Fetcher と Injector の分割により再利用性が最大化されます。AWS Secrets Manager から HashiCorp Vault への切り替えに必要なのは Fetcher プラグインの差し替えだけで、Injector はそのまま変わりません。
- 6. Plugin:コンテンツアドレス指定された WebAssembly プラグインです。プロバイダーレンダリング用の Plugin(
pluginType: provider)は、Recipe の入力種別を最終的な文字列化されたファイル形式に変換する単位です。対応するプロバイダー名をspec.provider.capabilities(例:helm)で宣言し、コンパイラがディスパッチするrender_nodeエクスポートを公開し、プロバイダーソケットの残りのメタデータ(workloadSchema、wellKnownAnnotations)を同じspec.providerブロックに保持します。Plugin が宣言できるその他のソケット種別は、pipeline-step、linter、governance、cli、parser、importerです。コンパイラは固定された参照をルーティングし、WebAssembly ランタイムがバイトを実行します。
ドメイン 4:ルーティングとポリシー(「接着剤」)
graph TD
classDef ext stroke-dasharray:5 4;
A["Aggregate"]:::ext
EB["Release<br/>The Deployment Router"]
ENV["Manifest<br/>The Dependency Lockfile"]
CapC["Feature"]:::ext
T["Plugin"]:::ext
CD["Recipe"]:::ext
CapD["FeatureRecipe"]:::ext
A -->|"Binds via"| EB
EB -.->|"Attaches"| CapC
EB -->|"Uses"| ENV
EB -->|"Renders via"| T
ENV -->|"Resolves Interfaces to"| CD
ENV -->|"Resolves Interfaces to"| CapD
- 役割:Platform Operator/DevOps。
- 7. Manifest:依存関係のロックファイルです。フラットな URI マッピングを使います。
components.type辞書がカタログのコンポーネント種別を Recipe の URI にマッピングし、features.type辞書が Feature の種別を FeatureRecipe の URI にマッピングします。解決はロックファイルとカタログに対する直接の URI ルックアップであり、ケイパビリティの決定はビルド時に、解決された各 Recipe のspec.capabilityフィールドから導かれます。解決後、すべてのエンティティにマッピングがなければコンパイラは停止します。DRY なエコシステムを維持するため、Manifests はextendsキーワードによる Kustomize 風の合成パターンをサポートしており、環境固有のマニフェスト(ローカルやステージングなど)がグローバルなベースマニフェストからきれいに継承し、固有の上書きだけを宣言できます。 - 8. Release:ルーターです。
aggregateをmanifestにバインドし、コンポーネントを物理的な境界(例:aws-eks-production)にマッピングします。DRY なワークフローを維持するため、Releases はextendsキーワードによる継承をサポートしており、環境固有のリリースがグローバルなベースリリースからきれいに継承できます。物理的な実情を厳密にparametersブロックに注入することで抽象的な aggregate の契約を満たし、物理的なサイジング(CPU やポートなど)は並列の名前空間infraを通じて注入します。Aggregate を単一の信頼できる情報源として保護するため、Release のスキーマはvalues:ブロックを機械的に禁止しています。Ops は Release から、どの Component や Feature に対してもvaluesを宣言できません。開発者向けの値の環境ごとの違いは、Parameter Hoisting によって流れます。開発者が Aggregate で型付きのparameters.*フィールドを公開し、Component のvaluesテンプレートがそれを参照し、Release がその環境のパラメーターを満たします。レンダリングされた値は環境ごとに異なりますが、どの値が存在し、それらがどのように流れるかを記述する面である Aggregate は、単一の信頼できる情報源のままです。スキーマレベルでの禁止が明示的に述べられている箇所については、アーキテクチャ上の制約と推奨パターンの制約 4「Release は開発者の値を上書きできない」を参照してください。重要なのは、追跡できない「aggregate を変更する」Releases を防ぐため、Release がextendsを使う場合、aggregateの宣言は Release のスキーマによって拒否される点です(extendsを使うとき、スキーマの制約はaggregateの宣言を許可しません)。子のリリースは、親とまったく同じ開発者の意図に対応していなければなりません。一方、manifestはオプションになり、「遅延バインディング」が可能になります。Ops は物理トポロジー全体を継承しつつ、依存関係のロックファイルだけを的確に差し替えることができます。- Feature のアタッチ:Release も、境界または 1 つのコンポーネントの
featuresの下に Features をアタッチします。入力がすべて運用上のものである Feature は、そのtypeとinfraとともにそのままアタッチします。Aggregate がアタッチした Feature については、そのアタッチのinfraを同じ名前の下に記述してサイジングを行います。
- Feature のアタッチ:Release も、境界または 1 つのコンポーネントの
Manifest と Release を分ける理由。 ソフトウェアのロックファイル(Manifest)をデプロイルーター(Release)から分離することで、どちらのエンティティも単独では生み出せない形が可能になります。DevOps は、1 つのアプリケーションを複数の地域別デプロイルーター(異なるクラウドリージョンをターゲットにし、すべて同じ Manifest を参照する異なる Releases)にデプロイでき、環境間で Recipe のバインディングを重複させる必要がありません。各地域の Release は、Manifest が提供する同じソフトウェアのロックファイルを使いながら、自らの境界レイアウトと環境固有のパラメーターを保持します。マルチリージョンへのスケーリングは、Manifest の複製からではなく、ドメインの分離から導かれます。
ティア 3:ライブラリ(カタログの再利用)
graph LR
classDef ext stroke-dasharray:5 4;
CC["Component"]:::ext
CapC["Feature"]:::ext
CD["Recipe"]:::ext
CapD["FeatureRecipe"]:::ext
SL["SchemaLibrary<br/>JSON Schema definitions"]
ML["MappingLibrary<br/>Go template fragments"]
WL["WorkloadLibrary<br/>Workload template fragments"]
AL["ArtifactLibrary<br/>Named artifact bundles"]
CC -.->|"$ref"| SL
CapC -.->|"$ref"| SL
CD -.->|"valuesMapping $import"| ML
CapD -.->|"$import"| ML
CD -.->|"workload $import"| WL
CD -.->|"artifacts $import"| AL
CapD -.->|"$import"| AL
- 役割:Platform Architect(ドメイン 2 と同じペルソナ)ですが、この役割が発揮されるのは、カタログのコンテンツが十分に大きくなり、Component をまたいだスキーマの再利用や、Recipe をまたいだテンプレート、ワークロードの形、成果物バンドルの再利用が有益になったときだけです。個人の作成者や小さなカタログは、ティア 3 のエンティティなしで提供できます。
- 9. SchemaLibrary:再利用可能な JSON Schema 2020-12 の定義です。ライブラリは
spec.schemas:で名前付きスキーマを、spec.templates:でオプションのパラメーター化されたヘルパーを宣言します(パラメトリックな再利用のための$params:宣言と$instantiate:参照を伴います)。カタログのエンティティは、標準の JSON Schema キーワード$ref:によってライブラリのエントリをアイデンティティで指し示して利用します。形式はホストなしの<library>#/schemas/<name>です(バージョンは参照ではなくロックファイルから得られます)。PascalCase の命名、OCI による配布、ロックファイルでの固定。Component をまたいだスキーマの再利用を必要とするカタログ向けのオプトインです。PodResources、PersistenceSpec、NodePool、MetricsServiceMonitorといった共通の形は、すべてのデータストア Component とすべてのワークロード Component で繰り返し現れ、SchemaLibrary のエントリはその繰り返しを Component ごとの記述から切り出します。 - 10. MappingLibrary:再利用可能な Go テンプレートの断片です。ライブラリは
spec.mappings:で名前付きテンプレートを宣言します。Recipes と FeatureRecipes はvaluesMapping: { $import: <library>#/mappings/<name> }によってライブラリのエントリをアイデンティティで利用します。記述方法は 1 つだけ(Go テンプレートのみ)で、並行する Jsonnet の記述経路はありません。Recipe をまたいだマッピングの再利用を必要とするカタログ向けのオプトインです。Bitnami チャートのヘルパーロジックや共有の Pod テンプレートパターンといった共通パターンは、同じプロバイダーをターゲットにするすべてのデータストア Recipe で繰り返し現れ、MappingLibrary のエントリはその繰り返しを Recipe ごとの記述から切り出します。 - 11. WorkloadLibrary:再利用可能な Workload テンプレートの断片です。ライブラリは
spec.workloads:で名前付きのワークロードエントリを宣言します。Recipe はworkload: { $import: <library>#/workloads/<entry> }によってエントリをアイデンティティで利用し、インポートされた本体は、インラインのworkload:ブロックとまったく同じように、プラットフォーム所有の Workload スキーマに対して検証されます。そのため、ライブラリからインポートしたワークロードは、同等のインラインのものと同一にレンダリングされます。記述方法は 1 つだけ(Go テンプレートのみ)です。Recipe をまたいだワークロードの再利用を必要とするカタログ向けのオプトインで、複数の Recipes が 1 つのデプロイの形を共有し、値だけが異なる場合に使います。 - 12. ArtifactLibrary:再利用可能な名前付き成果物バンドルです。ライブラリは
spec.artifacts:で名前付きバンドルを宣言します。各バンドルは、まとまって扱われる出力ファイル(たとえば CRD、その RBAC、ConfigMap)をグループ化し、1 つの単位としてインポートされます。Recipes と FeatureRecipes はartifacts.<name>: { $import: <library>#/artifacts/<name> }によってバンドルをアイデンティティで利用します。記述方法は 1 つだけ(Go テンプレートのみ)です。Recipe をまたいだ成果物の再利用を必要とするカタログ向けのオプトインで、同じ補助リソースのセットが多くの Recipes に付随する場合に使います。
すべてのライブラリは OCI を通じて公開され、ロックファイル(schema_libraries:、mapping_libraries:、workload_libraries:、artifact_libraries: の各セクション)で固定され、利用者を把握した状態で Hub の UI に表示されます(どの Components がどのライブラリエントリを参照しているか、どの Recipes がどのライブラリエントリを利用しているか)。