データ分類と合成
統一データ分類と合成ルール
予測可能なスキーマを確立し認知的な摩擦をなくすため、プラットフォームは広く理解されたちょうど 5 つのキーワードと、厳密に Map(辞書)ベースの YAML 構造を使用し、構造のルートにはネストした配列ではなく Map を置きます。
1. 5 キーワードの Map 標準と完全なスキーマ対称性
直接的な構造語彙: スキーマ設計の基本ルールは、ルートのデータ構造が単一の構造的キーワードでなければならないということです。会話的な英語のフレーズ(depends_on や runs_within など)を使うと YAML DSL は開発者にとって自然に読めるようになりますが、それらのキーをプログラム上の Go テンプレートにマッピングする際に構造的な複雑さが生じます。直接的な 1:1 の変数マッピングを維持し、ドメイン固有言語(DSL)の断片化を防ぐため、コアカタログエンティティ(Component、Feature)の JSON Schema は、作成されたインスタンススロット全体で使われるのと同じ構造的キーワードのコアセットに基づき、ほぼ完全な構造的対称性を示します。認証情報の Features(feature.aggrega.ai/kind: secret のラベル付き)もこれとまったく同じパラダイムを共有しており、シークレット専用のスキーマはありません。
parameters(グローバル環境契約)- スコープ:
Aggregateのルートで定義され、Release(CI/CD)によってparameters:の下にインラインで、または外部のパラメータファイルを指すparameters: { $import: <path> }を介して満たされます。 - 意味: 環境ごとにアプリケーションの認知的または論理的な状態を動的に変更する外部引数です(例:
workers: 2をworkers: 10に変更)。補間の前に検証される型付き契約をサポートします(型付き契約の完全な構文は data-pillars を参照)。パラメータ値を別ファイルに保持する GitOps ワークフローでは、Release は$import:形式を使用します。コンパイラはそのファイルの内容を読み込み、インラインのparameters:マップを置き換えます。複数ファイルのレイヤリングは Release のextends:チェーンで表現します。
- スコープ:
values(認知的意図 - 開発者所有)- スコープ:
Aggregate内のcomponentsとそのfeaturesアタッチメントの中で、認証情報の Features も含めて一様に使用されます。 - 意味: コアとなる認知的状態、ビジネスロジック、運用設定です。Go コンパイラにとっては不透明ですが、カタログの統一された
schema:宣言(コンパクト形式または JSON Schema 2020-12)によって厳密に検証されます。
- スコープ:
uses(構造トポロジー - 宣言的状態)- スコープ:
Aggregate内のcomponentsとそのfeaturesアタッチメントの中で、認証情報の Features も含めて一様に使用されます。 - 意味: ネットワークのエッジと依存関係を定義する、事実の宣言的な記述です(例: 「このエージェントはこのデータベースを使用する」)。Go コンパイラがネイティブに解析し、中間表現(IR)グラフを描画します。ノード間の型安全性を強制するため、カタログの統一された
usesSchema宣言によって検証されます。
- スコープ:
infra(物理的現実 - 運用所有)- スコープ:
Release内のバウンダリのcomponentsとそのfeaturesアタッチメントの中で一様に使用されます。 - 意味: Late Binding の間に注入される物理的なフットプリントと機械的なサイジングです(例:
cpu_limit: "4"、port: 5432)。Aggregate のコンポーネントインスタンスとそのfeaturesアタッチメントにはinfraフィールドがなく、additionalProperties: falseと組み合わさって、スキーマ検証時にinfraを拒否します。カタログの統一されたschema:宣言によって検証されます。
- スコープ:
inject(配信契約 - 命令的コマンド)- スコープ: コンポーネントインスタンス上、
uses内の明示的なターゲット定義の中、およびアタッチされたfeatures(認証情報の Features を含む)で使用されます。 - 意味: 配信の意図を指示する明示的かつ命令的なコマンドです(例: 「コンパイラよ、このマッピングされた値を環境変数として注入せよ」)。物理的な出力、解決済みのエンドポイント、または取得した認証情報に対する抽象的な契約(
env、file、arg、またはカスタムメカニズム)を確立し、そのマウントが正確にどのように実行されるかという物理的な仕組みは、基盤となる運用の Recipe に完全に委ねられます。各メカニズムはエントリーのリスト([{ in: API_HOST, from: "host" }])であり、各エントリーはin:でローカル識別子を指定し、from:またはvalue:のどちらか一方だけを持ちます。
- スコープ: コンポーネントインスタンス上、
.context(汎用メタデータパイプ)- スコープ: コンパイラによって運用の
Recipeテンプレートへ暗黙的に注入されます。 - 意味: コンパイラがグラフの他の部分からそのノードのために組み立てたもの(
.context.usesなど)を運び、運用のテンプレートエンジンへ直接渡されます。
- スコープ: コンパイラによって運用の
1:1 マッピングの実際
会話的な前置詞を厳密なインフラキーワードに置き換えることで、直接的な 1:1 マッピングが実現します。運用エンジニアは文法を翻訳する必要がなく、開発者が書いたとおりのキーを参照するだけです。
構造の形状: ルートはマップ、ペイロードは配列。 ルートのトポロジーブロック(components、features、aggregates、subsystems、boundaries)は YAML マップであり、ユーザーが作成したキーが安定したインスタンス ID として機能します。これらの位置では配列は無効です。マップのキーは、コンパイラが相互参照(target: my-db)、グラフノードの構築、Manifest の解決に使用する識別子です。不透明なペイロードブロック(values、infra、parameters)の内部では配列を完全に使用できます。開発者は Component の values の中に tools_allowed: ["sql", "web"] や hostnames: ["stripe.com", "twilio.com"] と書くことができます。Aggregate のスキーマはこれらのペイロードブロックを additionalProperties: true として宣言しているため、Go コンパイラにとって不透明であり、検証はすべてカタログに埋め込まれた schema: 宣言によって行われます。これにより、フレームワークの変動性(新しい AI API の形状、新しいクラウドネイティブのペイロード形式)は独立して進化できるカタログドメインの中に置かれ、Go コンパイラは構造のルートにおいてアドレス指定可能なキーのみを扱い続けます。
2. 情報フロー:誰が、いつ、何のために?
テンプレートの名前空間の衝突や、物理インフラ設定が認知的なアプリケーションロジックへ意図せず漏れ出すことを防ぐため、このアーキテクチャはデータを 6 つの異なるストリームに明示的に分離します。
- フロー 1:環境の注入(
parameters): CI/CD パイプラインがデプロイの実情を注入します。コンパイラは Release が提供する各値を型付きのparameters:契約に照らして検証し、その後、下流のvalues:スキーマ検証を実行する前に、解決済みの Go テンプレート変数を補間します。- 推奨される使い方:
parametersは、環境間で変化する認知的なアプリケーションロジック(例:LOG_LEVEL=debug、ENABLE_BETA=true)のために予約されています。運用上のサイジングや物理インフラに関する事項(レプリカ数、CPU 制限、AWS ARN、イングレスのホスト名)はReleaseのinfraブロックとバウンダリのオーバーレイを通じて流れ、開発者のAggregateをアプリケーションの意図に集中させます。 - 実用的なエスケープハッチ: 小規模なチーム、迅速なプロトタイピング、または厳密な分離が現実的でないレガシーな CI/CD 統合では、
parametersでグローバルな環境設定をスタック全体に渡すことができます。コンパイラはスキーマ検証を通過するものは何でも受け入れます。上記の推奨は社会契約であり、コンパイラの規則ではありません。
- 推奨される使い方:
- フロー 2:認知的なアプリケーションの意図(Components 内の
values): 本質的なアプリケーションロジックを定義します。Component のschema:宣言(コンパクト形式または JSON Schema 2020-12)は、このペイロードに厳密な型チェックと検証を提供し、開発者に即座の「シフトレフト」フィードバックを与えるとともに、要求された設定が基盤となるインフラ API と一致することを保証します。 - フロー 3:運用上の Feature の意図(Features 内の
values): Aggregate において、開発者は内部コードを変更することなく、振る舞いがアプリケーションの意図であるインフラ機能を要求し、厳密に型付けされた認証情報を照会します。入力がすべて運用上のものである Feature は開発者のvaluesを持ちません。運用側がそのinfraとともに Release でアタッチします(フロー 4)。 - フロー 4:物理インフラのサイジング(
infra): 開発者を完全に経由せず、物理的なinfraのサイジングは、環境固有のReleaseからローカルスコープの Components とそれにアタッチされた Features(認証情報の Features を含む)へ直接、明示的に投影されます。辞書をそのままブロードキャストすることによるクローズドスキーマ検証の衝突を避けるため、infraのサイジングはそれを対象とする明示的なコンポーネントに厳密にローカライズされます。これにより、コンピュート制限、レプリカ数、機械的なリソース要件は運用ドメインにとどまります。 - フロー 5:カスケードするアノテーション(コンテキストメタデータ): 広範なコンテキストデータ(運用ドメイン、名前空間、課金コードなど)はカスケードするアノテーションによって扱われ、
infraのブロードキャストによる汚染を防ぎます。これらは発生元に基づいてバケットに分離され、以下に示す各バケットの想定用途は社会契約です。Recipe テンプレートは 3 つすべてを読むことができ、コンパイラはこの分離を強制しません(labels-and-annotations を参照)。.context.annotations.release(ドメイン 4 バウンダリ): 物理的な実情を管理するためだけに使用されます。運用側は Go テンプレートを介して、これらのアノテーションを厳密なローカルinfraフィールドへ明示的にルーティングします(例:リージョンの名前空間をコンピュートコンポーネントにマッピングする)。.context.annotations.aggregate(ドメイン 1 サブシステム): 認知的および運用上のロジックを管理するためだけに使用されます。これらのアノテーションはコンポーネントのvaluesペイロードへ明示的にルーティングされます(例:チームの課金コードをアプリケーション設定へカスケードする)。.context.annotations.catalog(ドメイン 2 カタログ): アーキテクトが作成する不変の本質的な特性で、主にプログラムによる Wasm ポリシー評価に使用されます。
- フロー 6:メタデータパイプ(
.context): グローバルなエンタープライズ要件(SOC2 タグ)を物理インフラテンプレートに直接適用します。
3. ネットワーク抽象化:「ゼロポート」慣例
- ベストプラクティス: 開発者は
Aggregateからポートを省略すべきです。内部ルーティングは Ops Recipe が動的に処理します。 - エスケープハッチ: アプリケーションの内部コードを変更できない場合、プラットフォームアーキテクトは
schema:宣言でportフィールドを明示的に公開します。アーキテクチャ上の注記: 「ゼロポート」慣例は、プラットフォームのより広範な関心の分離の最も顕著な例です。物理的な仕組みを開発者から抽象化するというまったく同じ思想が、CPU リクエスト、メモリ制限、運用ドメイン、ディスクサイジングにも適用されます。物理インフラの制約が(レガシーコードや厳密なハードウェア要件により)開発者のアプリケーションペイロードに漏れ出さなければならない場合は、常にアーキテクトのschema:宣言、すなわち開発者のペイロードの検証に使われる宣言における明示的な「エスケープハッチ」によって管理されなければなりません。
「ゼロポート」という名前はこの慣例を表すものであり、この原則はレガシーアプリケーションがハードコードするあらゆる物理インフラの制約に一般化されます。以下のスキーマでは、明確にインフラ漏出の軸に位置するため、実例として tcp_keepalive_seconds(アプリケーションがソケット層で期待するカーネル/ネットワークのタイミング)を使用します。
スキーマ(ドメイン 2):
values: image: { type: string, required: true } # The architect explicitly allows the developer to declare a hardcoded constraint tcp_keepalive_seconds: { type: integer, min: 10, max: 300 }開発者の YAML(ドメイン 1):
components: legacy-payment-engine: type: core/java-tomcat:1.0.0 values: image: "corp/payments:v4" tcp_keepalive_seconds: 120 # The infrastructure must adapt to the app, not vice versaコンパイラの動作: Go コンパイラは tcp_keepalive_seconds: 120 を IR グラフに渡します。次に Ops Recipe が {{ .values.tcp_keepalive_seconds }} を読み取って Kubernetes の Pod スペックやクラウドプロバイダのロードバランサのアイドルタイムアウトを設定し、スキーマに違反することなくレガシーとのギャップを埋めます。
4. 注入契約と事前解決済みマップ
5 つの構造キーワードの中で、inject は他とは異なる形を持ちます。parameters、values、uses、infra は宣言的な状態であり、開発者はアプリケーションが何であり何に依存するかという事実を記述します。inject は命令的なコマンドであり、開発者は値を実行中のコンテナへどのように届けるべきかを指示し、抽象的なデータソース(ターゲットの provides キー、コンポーネント自身の values、認証情報 Feature の vault レスポンス)を具体的な配信メカニズム(env、file、arg、または Component が宣言するカスタムメカニズム)へマッピングします。
この分離は構造的なものです。開発者の Aggregate は、データベースの物理アドレス、シークレットストアの vault パス、クラウドプロバイダのホスト名形式を指定することなく、「データベースのホストを環境変数 DB_HOST として注入する」と記述します。Ops Recipe は解決済みの文字列を .context.inject を通じて受け取り、参照チェーンを記述することなくそれを使用します。
事前解決済みマップ。 レンダリング中、コンパイラはあらゆる inject ソース(セルフ注入のリテラルとコンポーネント自身の provides に対する from: 参照、uses[].inject を通じたコンポーネント間参照、FeatureRecipe の injectMapping による介入)を、.context.inject にある単一のフラットな辞書へ解決します。ベース Recipe の valuesMapping テンプレートが実行される時点で、すべての inject キーは最終的な文字列値を保持しています。Recipes は解決チェーンをたどることなく、マップを直接反復処理します({{ range $k, $v := .context.inject.env }})。
コンポーネント自身の値に開発者が付ける名前。 Component が spec.inject を宣言している場合、開発者自身の inject: ブロックが、コンポーネント自身の値と provides が配信パイプに届く際の名前を選びます。コンパイラは .context.self_inject で、各エントリのテンプレートが読み取る一つの自身の値を Recipe に伝えます。これはメカニズムごとに、各名前を provides.<key> に、自身の値をちょうど一つだけ読み取り他に何も読み取らないテンプレートの場合は values.<key> に、それ以外は空文字列に対応付けたもので、接続の名前が .context.uses.<alias>.inject でとる形と同じ形をとります。開発者のイメージを実行する Recipe に関する標準ライブラリカタログの慣例は、コンポーネント自身の値に対して本来選ぶはずの名前をデフォルトとして扱い、自身の値をデフォルト名で渡すのは、その値に対応付けられたエントリがまだない場合に限るというものです。これはカタログの慣例であり、コンパイラの規則ではありません。エンタープライズカタログは、自らのコンポーネント自身の値を任意の方法で渡すことができます。コンパイラは開発者が書いたテキストから対応表を読み取り、名前に意味を付与しません。
注入契約の完全な仕様(二重状態のコンテキストセマンティクス、キー衝突ルール、FeatureRecipe の介入モデル、実例)は topology-triad にあります。
5. テンプレートエンジン(Ops DX)
Platform Ops エンジニアは変換テンプレートを作成し、独自のテンプレート言語なしに、標準的なインフラテンプレートの機能をすべて必要とします。Aggrega のテンプレートは Go text/template です。
- 「マジック」文字列なし: コンパイラは Developer が記述したマップキーをそのまま保持します。Ops は標準の Go マップインデックスで安全に features にアクセスします:
{{ (index .features "public-route").infra.hostname }}。 - Sprig ライブラリ: コンパイラは Helm 標準の Sprig ライブラリをネイティブに登録しており、
| default、| quote、| toYamlなどのパイプラインをすぐに利用できます。 - MappingLibrary のフラグメント: 複数の Recipes が再利用するマッピングフラグメントは MappingLibrary に置かれ、
$import:によって各 Recipe に取り込まれます。Helm のチャートテンプレート用ヘルパー(include、tpl、required、warn)は登録されていません。登録されているものは sprig-functions に一覧があります。
6. 合成のルール: Aggregates、サブシステム、Components
- 論理グループ化(
subsystems配列): Developer はsubsystemsを使って、論理メタデータ(チームの所有権、コンプライアンスラベル)や横断的な features を多数のコンポーネントに同時に適用できます。サブシステムは論理/意図のプレーン上で再帰的なフォルダとして機能し、annotationsを下位の.context.annotations.aggregateバケットへカスケードし、物理的な境界を規定することなく含まれるすべてのコンポーネントに features をアタッチします。サブシステムレベルの features は Domain 1(Developer Intent)に属するため、コンポーネントレベルの features と同じスキーマ(type、values、uses、injectをサポート)に従います。コンパイラはグラフの確定時にサブシステムの features を、含まれる各コンポーネントの feature リストへ平坦化します。実行順序では、そのコンポーネント自身の features の後、Release でアタッチされた features の前に配置されます。
subsystems: finance-module: annotations: "billing.corp.com/team": "payments" features: audit-logging: type: core/audit-logger:1.0.0 values: { log_level: "verbose" } components: ledger-api: type: core/python-worker:1.0.0 ledger-db: type: core/postgres:1.0.0- 複合 Aggregates はサポートされています(Module パターン): Aggregates は、Release がビルドするルートの Aggregate と再利用可能なモジュールの両方として機能します。親 Aggregate は子 Aggregate をコンポーネントとまったく同じように宣言し、
parametersを渡すことができます。密結合を防ぐため、子 Aggregates はexportedComponents:コントラクトを公開し、安定した公開インターフェース名を確立します。親はこのインターフェースを通じてのみモジュールのコンポーネントに到達します。uses:のターゲットはモジュールとそのエクスポートされたエイリアスの 1 つを指定し、コンパイラはそのエイリアスが指す内部コンポーネントへエッジを接続します。一方、それ以外の名前でモジュールの内部に到達しようとするターゲットは、モジュールとそれがエクスポートするエイリアスを示してビルドを停止します。モジュール自体が、ネストされたモジュールのエクスポートされたコンポーネントを自身のインターフェース名で再エクスポートすることもでき(必要に応じて名前を変更可能)、コンパイラはそのような再エクスポートチェーンを基盤の内部ノードまで推移的に解決します。そのため、親がターゲットのネストの深さを知る必要なく、モジュールを任意の深さで合成できます。どの内部ノードにも解決されないターゲットは引き続き明示的に停止し、自身に戻って閉じる再エクスポートチェーンは永久に辿られるのではなく拒否されます。
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"apiVersion: aggrega.ai/v1beta1kind: Aggregatemetadata: name: parent-app version: 1.0.0spec: aggregates: finance-db-subsystem: type: my-catalog/child-database-module:1.0.0
components: billing-api: type: core/python-worker:1.0.0 uses: databases: - finance-db-subsystem.primary_db-
Components はサブコンポーネントを含むことができません: Components はアトミックな構成要素です。合成は Aggregate レベルで、サブシステムとサブアグリゲートを通じて行われます。アプリケーションが複数の物理コンテナ(API + サイドカーなど)を必要とする場合、その物理的なネストは Component 定義ではなく Ops の Recipe テンプレート内に置かれます。
-
Component ごとに一貫した 1 つのサービス — 単一ワークロードの境界: Component は一貫した 1 つのサービスをモデル化します。すなわち、公開される単一のサービス、または 1 つのサービスのワークロード(群)とその内部専用のヘルパーワークロードです。その
component.aggrega.ai/typeラベルは、その 1 つのサービスの運用上の形状を示します。単一の Component 内の複数の物理ワークロードは、独立して使用可能な部分を持たない一貫した 1 つの製品を構成する限り問題ありません。チャートがコントローラー、Webhook、インジェクターを実行するサービスも 1 つの Component です。判断基準は複数ワークロードかどうかではなく、独立した使用可能性です。境界は、バンドルに他のコンポーネントが単独で意味のある形で
useできるもの、特に Aggrega がすでに独自の Component としてモデル化しているデータベース、キャッシュ、メッセージブローカーなどの外部インフラが含まれる箇所で引かれます。そのようなバンドルは 1 つの Component ではなく、サブアグリゲート Module(前述のspec.aggregates+exportedComponentsパターン)であり、サービスごとに 1 つの Component を合成します。これにより、各サービスは独自のタイプ、独自のエッジ、独自のポリシーとスケーリングの対象を持つ、アドレス可能なノードになります。このヒューリスティックを明確なルールとして述べると次のとおりです: チャートに、他のコンポーネントが単独で意味のある形で使用できるもの、または Aggrega がすでに Component を持っているものが含まれていますか? 含まれている場合は、スタック、つまりサービスごとの Components を合成するサブアグリゲート Module としてモデル化します。この 1 つのサービスにのみ使われる場合は、1 つの Component としてモデル化します。
複数サービスからなる製品全体を単一の不透明な Component としてラップすることは、文書化されたアンチパターンです。コンパイラは主張を持たないためこれを受け入れます(スキーマ検証を通過するものは何でもレンダリングします)が、標準ライブラリは代わりにサービスごとの Components を Module に合成します。モノリシックなラップは、独立してモデル化可能なサービスを、トポロジー、セレクター、サービスごとのポリシーとスケーリングから隠してしまうためです。この粒度の規律は社会契約です。
../language-reference/vocabulary/social-contracts.md(Component の粒度)を参照してください。
7. デフォルトスコープ — グループ化の段階的開示
subsystems(Aggregate 内)と boundaries(Release 内)はグループ化のための構文ですが、開発者が最初からこれらを宣言する必要はありません。各エンティティには 2 つの記述形式があり、両者は相互排他的です。名前付きスコープの下にコンポーネントをグループ化して記述するか、トップレベルに直接コンポーネントを記述するかのどちらかであり、両方を同時に使うことはありません。トップレベルの components と名前付きスコープの両方を宣言したドキュメントは、ロード時にエンベロープエラーで停止します。
フラットな(トップレベルの components の)形式に対して、コンパイラはロード時に実体のある default スコープを合成し、トップレベルのコンポーネントをその中にまとめます。これにより、後続のすべてのパスはスコープを持つ一様な構造を扱えます。合成されたスコープは隠しコンテナではありません。IR 内の正規の、来歴が記録されたノードであり、開発者が明示的に default と名付けたスコープとは区別できます。隠されるのは作成者がパスを読む場面だけで、診断とアドレス指定では開発者が実際に記述したルート形式の .spec.components[…] が表示されます。
- フラットな Aggregate(トップレベルのコンポーネント):
subsystemsを使わずにspec.componentsの下にコンポーネントを記述します。コンパイラはロード時にそれらを合成されたdefaultサブシステムにまとめます。サブシステムスコープのアノテーションとサブシステムレベルのフィーチャーは宣言されたサブシステムにのみ適用され、フラットな形式はそれらを一切持ちません。 - フラットな Release(トップレベルのコンポーネント):
boundariesを使わずにspec.componentsの下にコンポーネントを記述します。コンパイラはそれらを合成されたdefaultバウンダリにまとめ、その出力はフラットになります。成果物はバウンダリ名のセグメントなしでdist/の直下(プロバイダごとにdist/compose/、dist/helm/、…)に配置されます。これが最も簡単なケースであり、バウンダリに名前を付けずに、フラットな Compose またはシングルクラスタのターゲットに対してaggrega buildを実行します。(開発者が宣言してdefaultと名付けたバウンダリは通常の名前付きバウンダリであり、独自のdirectory:がなければ、他と同様にdist/boundaries/default/に出力されます。) - アップグレードパス: フラットなアーキテクチャが、グループ化を必要とするもの(異なる名前空間、個別の論理グループ、複数バウンダリへのデプロイ)へと成長した場合、開発者はトップレベルのコンポーネントを明示的な
subsystemsに移すか、Ops が明示的なboundariesを導入します。2 つの形式は相互排他的なため、これはフラットな形式からスコープ付きの形式への移行であって両者の混在ではなく、移行の前後でノードの同一性は保たれます。
その理由は段階的開示です。些細なユースケース(単一サービスのデモ、手早いローカルプロトタイプ)にグループ化を必須とすると、不要な摩擦が生じます。「10 分でゼロから動作まで」というオンボーディングテストでは、開発者がサブシステムやバウンダリを先に理解しなくても、1 つのコンポーネントを持つ最小限の Aggregate、1 つの Manifest、1 つの Release を記述して動作する出力を得られることが求められます。デフォルトスコープは入口であり、宣言されたスコープはアーキテクチャが成長するにつれて向かう先です。
8. アーキテクチャ上の制約と推奨パターン
以下の項目は、1 つの推奨パターンと 5 つの制約です。スキーマが強制するのは制約 4 と 5 です。Release には values ブロックがなく、Aggregate のコンポーネントインスタンスには labels キーがありません。それ以外は、コンパイラがチェックしない慣例です。
-
推奨パターン:テンプレート文字列によるパラメータの巻き上げ
- 例: 開発者が
valuesブロックにworkers: {{ .parameters.env_workers }}と記述します。値が宣言どおりの整数として届くよう、引用符は付けません。 - 理由: Aggregate が
env_workersを型付きパラメータ(type: integer)として宣言している場合、コンパイラはまず Release から提供された値をコントラクトに照らして検証します。パラメータコントラクトの検証は補間の前に行われ、補間は周囲のvalues:スキーマ検証の前に行われます。これにより Aggregate の再利用性が保たれます。Ops はReleaseのparameters:で整数を提供し、コンパイラはそれを型付きのparameters:宣言に照らして検証し、解決された値をドキュメントに代入し、Component のschema:宣言が結果の整数を正しく検証します。
- 例: 開発者が
-
制約 1:認証情報は値ではなくアタッチメントである
- 非推奨パターン: 開発者がコンポーネントに
values: { password: "123" }と記述します。 - 理由: 標準ライブラリの慣例では、認証情報は
features:の下のアタッチメントとして要求し、認証情報用の Featuretype(feature.aggrega.ai/kind: secretというラベルを持つもの)を指定し、そのアタッチメント自身のvaluesでシークレットストアへのクエリを記述します。これは慣例であり、コンパイラによるチェックではありません。コンパイラはvaluesのリーフが何を意味するかを解釈せず、インラインのリテラルもそのまま運びます。適切に記述された形式を利用可能かつ型付きにしているのは、アタッチメントという仕組みです。
- 非推奨パターン: 開発者がコンポーネントに
-
制約 2:ケイパビリティに依存しない Components
- サポートされないパターン: アーキテクトが Component の
schema:宣言にaws_instance_type: stringと記述します。 - 理由: Components は慣例によりケイパビリティに依存しません。物理的なハードウェアターゲットは、アプリケーションの中核的な認知ロジックの内部ではなく、Ops の Recipes または汎用的な
.contextアノテーションに置きます。
- サポートされないパターン: アーキテクトが Component の
-
制約 3:メタデータに基づく条件ロジック
- サポートされないパターン: Ops がデプロイ戦略を根本的に変えるために、
Recipe内に{{ if eq .context.labels.gpu "true" }}と記述します。 - 理由:
.contextパイプはピラーごとのschema:検証を経由しません。検証されていないラベルにインフラの中核ロジックを依存させると、プラットフォームが脆くなります。.contextオブジェクトはメタデータのタグ付け(例:課金、SOC2)を運ぶものであり、構造的なルーティングはスキーマ検証されたピラーに属します。
- サポートされないパターン: Ops がデプロイ戦略を根本的に変えるために、
-
制約 4:Release は開発者の値を上書きできない
- サポートされないパターン: Ops が
Releaseから開発者の認知ロジックを上書きしようとします(例:workers: 4をworkers: 10に変更する)。 - 理由:
Aggregateは開発者の意図における信頼できる唯一の情報源です。Aggregateにハードコードされた値は、環境をまたいで不変です。値を環境ごとに変える必要がある場合、開発者はパラメータの巻き上げを使います。Releaseスキーマはvaluesブロックを禁止することでこれを強制し、Ops の役割をparametersコントラクトの充足と物理的なinfraの定義に限定します。
- サポートされないパターン: Ops が
-
制約 5:Aggregate 上のインスタンスレベルのラベル
- サポートされないパターン: 開発者が
Aggregate内のコンポーネントインスタンスにlabels: {}と記述します。 - 理由: ラベルはプラットフォームアーキテクトが作成する、カタログレベルの不変の特性であり、ポリシーエンジンやセレクターが読み取るセマンティックな識別情報です。Release は明示的なマップベースの ID 指定(
components: { "my-agent": {} })によってコンポーネントをバウンダリに振り分けます。これにより、ラベルの作成を開発者の Aggregate に混在させることなく、コンポーネントごとにinfraやフィーチャーの上書きをネストできます。
- サポートされないパターン: 開発者が
9. セキュリティ境界と明示的なエグレスガードレール(境界外の宛先)
真空の中に存在するアプリケーションはありません。コンパイルされた Aggrega アーキテクチャは、厳密にマッピングされたグラフを表します。しかし、現代の AI システムは、このコンパイルされた境界の外にあるエンティティ、たとえばパブリックな SaaS LLM(Anthropic、OpenAI)、汎用的なパブリック API(Stripe、Twilio)、レガシーなブラウンフィールドのデータベース(オンプレミスの Oracle)などと絶えずやり取りします。
これらの外部システムを安全に統合するため、Aggrega はセキュリティ境界と実行メカニズムを厳密に分離します。セキュリティ境界はユニバーサル Component ルールと明示的なエグレスガードレールによって管理されます。
1. ユニバーサル Component ルール
アプリケーションがエンティティとやり取りする場合、それがローカルデータベース、マネージドクラウドリソース、SaaS LLM、汎用的なパブリック API エンドポイントのいずれであっても、そのエンティティは Aggregate 内で個別の Component として宣言しなければなりません。このルールは慣例です。コンパイラはアプリケーションが行う呼び出しを見ることができないため、これをチェックするものはありません。
外部の SaaS API やレガシーデータベースを中間表現(IR)グラフのファーストクラスのノードとして扱うことで、開発者はゼロトラストのプロキシ設定を外向きの呼び出しに直接アタッチできるようになります。たとえば Stripe API を個別のノードとしてモデル化すると、開発者はそれに header-injector フィーチャーをアタッチでき、生成される設定によって、呼び出し元の Agent が生の API トークンを自身のメモリに保持しないようにできます。
2. 明示的なエグレスガードレール(インフラストラクチャの適合性)
Aggrega は、ネットワークのエグレスを統制するためにハードコードされたコンパイラのロジックに頼るのではなく、境界のセキュリティを企業の依存しないポリシーエンジンと Wasm レンダリングプラグインに完全に委ねます。これにより、生成される設定が明示的なエグレス承認に厳密に適合することが保証されます。
- カタログフック(ドメイン 2): Architect が公開 SaaS コンポーネント(例:
core/external-service)を定義するとき、そのコンポーネントに不変の企業ラベル(例:security.enterprise.com/zone: "untrusted-external")を付与します。 - ポリシーガードレール(コンパイル時): 設定が生成される前に、OPA または Kyverno のポリシーエンジンがグラフを評価します。企業は次のような簡単なルールを記述します: 「内部ノードが
untrusted-externalとラベル付けされたノードに接続する場合、その接続先ノードの ID は環境のparameters.approved_egress配列に明示的に列挙されていなければならない。」 開発者が承認されていない外部の宛先にデータをルーティングしようとすると、ポリシーエンジンがビルドを停止します。 - 設定の生成(レンダリング時): ポリシーを通過すると、エグレスルールはオペレーターがアタッチしたものからレンダリングされます。Release で呼び出し側のコンポーネントにアタッチされた
core/egress-allowlistFeature は、helm上で、そのコンポーネントがレンダリングするワークロードごとに Kubernetes のNetworkPolicyを 1 つレンダリングし、エグレスを、自身の Pod、usesエッジのターゲットの Pod(それらの Pod が宣言するポート上)、クラスターの DNS、そしてクラスター内で動いていないターゲット(公開 SaaS API など)に対してアタッチメントが列挙するアドレス範囲にのみ許可します。Release がinfra.control_plane_present: trueによってクラスターのネットワークプラグインがネットワークポリシーを強制することを明示しない限り、ビルドは停止します。また、アドレス範囲が列挙されていないそのような外部接続があれば、それを示してビルドは停止します。ネットワークポリシーを持たないcomposeでは、このアタッチメントがビルドを停止します。開発者がファイアウォールルールを書くことはありません。
これにより、宣言されたトポロジーを評価するガバナンス判定ロールを介して、コアの Go コンパイラが「外部」の意味を理解する必要なしに、明示的に宣言されたインフラストラクチャがエグレスポリシーに適合することが保証されます。(注: 真のゼロトラストエグレスは、対象クラスタが実行時に Default Deny の CNI を稼働させていることに依存します。生成される設定は、許可された例外をマッピングするだけです。)
外部サービスごとに 1 つの Component
各外部サービスは、複数の接続先をまとめた配列に集約するのではなく、個別のコンポーネントとして宣言します。アプリケーションが 5 つの異なるサードパーティ API を呼び出す場合、開発者は 5 つの個別の core/external-service コンポーネントを宣言します。このサービスごとの宣言によって、ポリシーエンジンと Wasm プラグインは各送信先を個別に対象にでき、外部依存関係ごとに異なるエグレスポリシー、異なるプロキシ機能、異なるオブザーバビリティフックを付与できます。
セキュリティと実行の分離(「ブラウンフィールド」シナリオ)
重要な点として、セマンティックラベル(例: untrusted-external)が規定するのはネットワークセキュリティポリシーであり、実行ではありません。Aggrega がそのリソースをプロビジョニングする成果物をレンダリングするかどうかとは無関係です。
- シナリオ A(公開 SaaS API): カタログで
untrusted-externalとラベル付けされます(ポリシーのエグレスガードレールが作動します)。参照型ワークロードによって実現されます(コンピュートはプロビジョニングされません。§10 を参照)。 - シナリオ B(内部のレガシーデータベース):
internal-trustedとラベル付けされます(エグレスガードレールを通らず、VPC 内にとどまります)。参照型ワークロードによって実現されます(コンピュートはプロビジョニングされません。§10 を参照)。 - シナリオ C(セルフホストのデータベース):
internal-trustedとラベル付けされます。Helm レンダラープラグインを介して実行されます(Kubernetes の StatefulSet として物理的にプロビジョニングされます)。
10. ビルドがプロビジョニングしないサービス:参照型 Workloads
アプリケーションがオンプレミスのレガシーデータベースや公開 SaaS API(Stripe など)とやり取りする場合、Universal Component Rule により、これらの外部エンティティは Aggregate 内で個別のコンポーネントとして宣言しなければなりません。しかし、Aggrega はそれらのために物理的な Kubernetes Pod や AWS RDS インスタンスのアーティファクトを生成しようとしてはなりません。
そのようなコンポーネントを実現する Recipe は、form: reference の Workload を宣言します。これは endpoint(ホストまたは URL)と、任意の port を持ち、コンテナは持ちません。コンパイラはこの両方を決定的なポインタ文字列としてそのまま受け渡し、解決することはありません。参照型 Workload に対してプロバイダーが何をレンダリングするかはプロバイダー自身が決めます。helm はエンドポイントのホストを持つ ExternalName Service を出力するため、クラスター内のワークロードは、エンドポイントが DNS 名であるサービスに安定したクラスター内の名前で到達できます。compose はこれに対して何もレンダリングしません。Kubernetes は externalName を DNS 名として扱うため、IP アドレスで書かれたエンドポイントには、Service を経由するのではなく、コンシューマーが受け取るアドレスで到達します。
どちらのプロバイダーでも、Recipe の provides: は、プロビジョニングされるコンポーネントの場合とまったく同じように、.context.uses と inject 契約を通じてすべてのコンシューマーに届きます。したがって、ターゲットがプロビジョニングから参照に移っても、コンシューマーの配線は変わりません。変わるのは、Manifest がそのターゲットをマッピングする Recipe だけです。
段階的な実行パイプライン
1. ドメイン 1(Aggregate): 開発者の意図 開発者はレガシーの Oracle データベースを要求します。それがどこにあるかは気にせず、呼び出し側の Agent が接続文字列を環境変数として受け取ることを期待する、とだけ指定します。IP は静的で事前にわかっているため、パラメータで渡します。
components: legacy-oracle: type: core/legacy-database:1.0.0 values: host: "{{ .parameters.legacy_oracle_ip }}" sid: "PROD_DB"
my-agent: type: core/python-worker:1.0.0 values: {} uses: databases: legacy_db: target: legacy-oracle inject: env: - in: ORACLE_DSN # Local env var from: "primary_endpoint" # Target provides key2. ドメイン 4(Manifest): ルーティング Ops は、レガシーデータベースの型を、その接続文字列を整形する Recipe にマッピングします。Manifest は Recipe を指定するだけで、それ以上のことはしません。指定された Recipe が form: reference の Workload を宣言し、その形式によってノードはコンピュートをプロビジョニングしません。対象が何であってもマップの形は 1 つだけなので、ルーティングは完全にフラットで予測可能なままです。
spec: mappings: components: type: "core/legacy-database": "oracle-dsn-formatter:1.0.0"3. ドメイン 3(参照型の Recipe): 受け渡しの構造化 Ops エンジニアが Recipe を記述します。この Recipe は locals ブロックで開発者の values から primary_endpoint 接続文字列を組み立て、それを provides の下で公開し、データベースのホストを指す参照型 Workload を宣言します。
apiVersion: aggrega.ai/v1beta1kind: Recipemetadata: name: oracle-dsn-formatter version: 1.0.0spec: capability: helm implements: core/legacy-database:1.0.0
# The connection string, built from the Developer's values locals: primary_endpoint: "oracle://{{ .values.host }}:1521/{{ .values.sid }}"
# The public contract a consumer's inject reads provides: primary_endpoint: "{{ .locals.primary_endpoint }}"
# No compute: an endpoint the build does not provision workload: | apiVersion: aggrega.ai/v1beta1 kind: Workload form: reference endpoint: "{{ .values.host }}" port: 15214. レンダリング時のコンパイラの実行(受け渡し)
- コンパイラは
legacy-oracleの Recipe を評価します。legacy_oracle_ip: "10.0.4.55"を与える Release では、そのprimary_endpointはoracle://10.0.4.55:1521/PROD_DBになります。 helmでは、参照型 Workload は ExternalName Servicelegacy-oracleを 1 つレンダリングし、そのexternalName: 10.0.4.55、ポートは1521です。composeでは何もレンダリングしません。- 次に、コンパイラは
my-agentの Recipe をレンダリングします。その.context.usesパイプは Oracle ノードのprovidesを運び、inject 契約はすでにそれらに対してORACLE_DSNを解決しています。
5. ドメイン 3(呼び出し側の Recipe): 契約の履行 Python ワーカー用の標準の Helm レシピは、受け取った inject マップを、ビルドがプロビジョニングするデータベースの場合とまったく同じように読み取ります。
# Inside python-worker-helm (The calling agent's recipe)env: # The compiler pre-resolved the target's provides into the inject map {{- range $key, $value := .context.inject.env }} - name: {{ $key }} # Renders: ORACLE_DSN value: "{{ $value }}" # Renders: oracle://10.0.4.55:1521/PROD_DB {{- end }}11. スキーマブリッジによるピラー間のパイピング: 意図とインフラストラクチャの橋渡し
子コンポーネントを通じて特化したインフラストラクチャの設定項目を安全に公開するスキーマブリッジパターンについては、inheritance-and-interface を参照してください。これは、Component の schema: で宣言された開発者向けの values: フィールドを、Recipe の valuesMapping: テンプレートがレンダリングされる infra: 形式の出力へパイプするものです。
12. グリーンフィールドのプロビジョニング(「Platform Aggregates」)
プラットフォームエンジニアリングでよく陥る罠は、ルーター(Release ファイル)に Day-0 の重いクラスタープロビジョニング(たとえば、アプリをデプロイする前に新しい AWS EKS クラスターを立ち上げること)を担わせてしまうことです。これにより、長く読みにくいルーティングファイルが生まれます。
Aggrega はこれを「Turtles All the Way Down(どこまでも亀)」の原則で扱います。Release スキーマにはインフラをインストールするためのブロックはなく、クラスターのプロビジョニングは Platform Aggregates でモデル化されます。
AWS EKS クラスター、Istio コントロールプレーン、AWS VPC は結局のところ物理的なクラウドリソースにすぎないため、アプリケーションのコンポーネントとまったく同じようにモデル化されます。
- Platform Aggregate: インフラストラクチャチームは、コンポーネントが
core/aws-vpc、core/eks-cluster、core/istio-baseである標準的なAggregate.yamlを記述します。 - Platform Release: チームはこの aggregate をデプロイします。これらのプラットフォームコンポーネントにバインドされたレンダラーが、ベースインフラストラクチャを構築するために必要な成果物を出力します。
- Application Release: アプリケーション開発者が AI エージェントをデプロイする準備が整ったら、Ops チームはアプリケーション自身の
Releaseファイル内のバウンダリで、新たに作成されたクラスターをターゲットに指定するだけです。