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

アーキテクチャの不変条件

これら 8 つの不変条件は、Aggrega の基礎となるルールです。これらはリリースをまたいで、またコンパイラのコア、スキーマ層、カタログ、Wasm プラグインのサーフェスをまたいで成り立ちます。すべての設計判断、すべての機能、そして記述されたすべてのエンティティがこれらを尊重します。

不変条件は、他のアーキテクチャの章から番号で参照されます。後の章が「不変条件 2 により」や「String Pipe のルール(不変条件 3)により」と述べるとき、それはここを指しています。

1. コンパイラは内容に対して中立で、主張を持たず、ユーザーの意図に依存しない

Aggrega コンパイラは事前コンパイル(Ahead-Of-Time、AOT)型のテキストルーターです。YAML を解析し、グラフを走査し、ラベルの共通部分を評価し、文字列をソースからシンクへ流します。作成者が values、parameters、infra、provides、locals に何を入れるかは取り締まりません。命名の慣例、ポートの慣例、あるいは Architect が考案するセマンティックラベルを強制することもありません。

コンパイラのルールのように聞こえる多くのルール(Zero-Port Contract、Naked-Base / Flavored-Edges のカタログスタイル、特定のコンポーネントにどの運用プリミティブが適合するかの選択)は、社会契約です。つまり、エスケープハッチを備えたベストプラクティスであり、標準ライブラリのカタログを記述する Platform Architect によって維持されます。コンパイラはそれらを解釈しません。

**この不変条件は、記述されたコンテンツからコンパイラが何を推論するかに関するものであり、その範囲がすべてです。**ごく一部のキーは Aggrega 自身のものです。これらは予約済みで、受け付ける値は公開スキーマに記載されており、スキーマは他の宣言済みフィールドと同じ方法でそれらを検査します。component.aggrega.ai/type はその一つです。値の集合は閉じており、その外の値を持つドキュメントは読み込み時に拒否されます。これはプラットフォームが自分のキーの意味を定めているのであって、コンパイラが記述された文字列に意味を読み取っているのではありません。独自のキーはすべて、この不変条件が述べるとおり、まったく取り締まられないままです。Aggrega が定義しない軸でコンポーネントを分類するカタログは、独自のラベルキーを記述します。スキーマはそのキーを任意の文字列値で受け付け、すべてのセレクターのサーフェスが同じように読み取ります。

コンパイラが実際に強制するものは限られています。スキーマ検証、YAML の解析、グラフの構築、テンプレートの評価、そして Injection Contract の単純なテキストルーティングです。それ以外はすべて慣例であり、カタログの記述時、またはオプトインの Wasm ガバナンスソケット内で強制されます。

独自の社内カタログを記述する企業は、標準ライブラリの慣例を破ることを明示的に認められています。コンパイラは、スキーマ検証に合格する限り、書かれたものをすべて受け付けます。アーキテクチャはベストプラクティスを推奨しますが、牢獄は作りません。

2. AOT の純粋性:コンパイラはランタイム情報にアクセスできない

Aggrega は Ahead-Of-Time コンパイラです。コンパイル時には次のとおりです。

  • クラウド API で認証しません。
  • 稼働中の IP アドレス、DNS 名、クラウドが生成した URL を取得しません。
  • シークレットを平文に解決しません。シークレットは中間表現(Intermediate Representation)全体を通じてメタデータポインターのままです。
  • 対象のクラスターやサービスのランタイム状態を知りません。
  • まだ存在しないデータ(プロビジョニング後のエンドポイント、動的に割り当てられるポート、自動生成されるリソース名)を取得できません。

ランタイム状態に依存するものはすべて、決定的なポインター文字列(安定した DNS 名、Terraform の補間文字列、CloudFormation のリソース参照)として表現され、Ops Recipe が提供します。コンパイラはポインターを解決せずにそのまま流します。最終的な物理データを解決するのはランタイム環境(クラスター、IaC の状態管理ツール)です。

これが真の制御の反転(True Control Inversion)です。開発者は Aggregate で Injection Contract を指定し、コンパイラは決定的なポインターを事前に配線し、ランタイム環境が最終的な物理データを解決します。本当にランタイムでの解決を必要とする要件は、コンパイラのコアではなく、Ops Recipe の Wasm パイプラインに属します。

3. String Pipe:コンパイラは意味を推論できない

コンパイラは、パイプで渡される値が何を意味するかを解釈しません。Component A が Component B を使う場合、コンパイラは Component B の Recipe が provides を通じて生成するスカラー(文字列、数値、またはブール値)を受け取り、注入の境界で決定的に文字列化したうえで、Component A の Recipe のコンテキストにパイプで渡します。その値が FQDN、ローカルのホスト名、IP リテラル、ポート番号、Wasm で整形された DSN のいずれであっても違いはありません。コンパイラは、ルーティング可能性、プロトコルの正しさ、意味上の妥当性を検証しません。

ここから 2 つの帰結が導かれます。

  • コンパイラは名前からコンポーネントの目的を推測しません。database-production という名前のコンポーネントがデータベースとして認識されることはありません。component.aggrega.ai/type のようなセマンティックな型ラベル(存在する場合)は、ラベルの照合に使われる不透明なメタデータであり、コンパイラの分岐ロジックではありません。
  • コンパイラは、ホスト名、データベース名、ポート番号、任意の不透明な値を区別しません。これらはすべて注入コンテキスト内のスカラーエントリであり、文字列として渡されます。

トポロジーの三つ組(生成側の Recipe の provides、消費側の Aggregate の uses、エッジの inject)が Injection Contract です。コンパイラはラベルを評価して文字列を渡すだけであり、解釈は Recipe と Component の間の記述上の契約です。

4. ゴーストインフラストラクチャの禁止:コンパイラはコンピュートや機能を決して捏造しない

コンパイラは、コンピュート、Features、アノテーション、ルーティングプロキシ、その他作成者が明示的に宣言していないリソースを、黙って注入することは決してありません。ポリシー違反は明示的なガードレール(Loud Guardrails)を生みます。つまり、ビルドが停止し、作成者が書いたドキュメントの中で何を修正すべきかを示す具体的なエラーが出ます。デバッグ時にインフラの謎を生むような、黙った変更ではありません。

リソースは、記述時の明示的な宣言を通じてグラフに入ります。

  • 開発者の Aggregate(コンポーネント、uses エッジ、Feature のアタッチ)。
  • Release の Feature のアタッチ(オペレーターレベルの追加)。
  • アノテーション駆動の展開(Manifest がアノテーション → Feature のバインディングを宣言します。Component や境界に付けたアノテーションは明示的な宣言です)。
  • Recipe レベルのリソース生成:Recipe の source のレンダリングが主要な成果物を生成し、workload の合成がプロバイダー固有のデプロイ形式(Pod スペック、Compose サービスなど)を出力し、artifacts: のエントリ(インライン、または $import: で読み込んだもの)が Recipe 固有の補助マニフェストを出力し、FeatureRecipe のリソース生成が、明示的な Feature のアタッチをきっかけに Feature ごとの補助リソースを出力します。

Recipe レベルのパスは、一段階離れた記述時の宣言です。Recipe の作成者は Component の契約に対して source / workload / artifacts / valuesMapping を書き、開発者の Aggregate がどの Components を参加させるかを選びます。レンダリング出力に現れるリソースは、Aggregate、Release、アノテーションのバインディングのいずれかにある宣言か、Aggregate のコンポーネント型が選んだ Recipe の記述にまでさかのぼれます。

合成は、作成者が宣言した形をプロバイダー固有の出力形式に変換します。コンテナーのマップとして記述された Workload のスペックは、Kubernetes の Pod スペック、Compose のサービスブロック、Terraform のモジュールのいずれとしてもレンダリングできます。変換はプロバイダー主導ですが、リソースは作成者の Workload の宣言にまでさかのぼれます。

ガバナンスソケットはアタッチごとにロールを持ち、アタッチがビルドに対して何をしてよいかを決めるのは、プラグインの種類ではなくロールです。判定ロールでアタッチされたガバナンスプラグイン(IR グラフ(ir-verdict)またはレンダリング済みの成果物(render-verdict)を審査するもの)は、ビルドを拒否できますが、変更はできません。そのような判定がリソースの追加を求める場合は、是正のための指示を添えてビルドを失敗させ、作成者自身がリソースを追加するようにします。ホストは判定の出力を受理か拒否としてのみ読み、変更として適用することは決してありません。そのため、頼まれていないのにグラフを準拠状態へ書き換えること(まさにこの不変条件が禁じるゴーストインフラストラクチャ)が判定ロールから生じることはありえません。変換ロール(label-transform または annotation-transform)でアタッチされたガバナンスプラグインは、限定的で明示的な例外です。それをアタッチするオペレーターは、ワークスペースの plugins.governance 設定を通じたオプトインによって、その変換を宣言しています。したがって、変換による変更は明示的な宣言であり、アノテーション駆動の展開と同じ位置づけで、黙った注入ではありません。違いは招待の有無です。求められていない判定はビルドを書き換えられませんが、明示的にアタッチされた変換は、オペレーターが求めたものなので書き換えられます。変換はレンダリング出力を形作るため、出力を形作るすべてのプラグインと同様にロックファイルに固定されます。適用される変換は pull の時点で確定するので、変更するには pull し直す必要があり、ビルド間で黙って変わることはありません。判定は出力を形作らないため、固定されません。

5. Aggregate が記述の場であり、Release は values: を宣言できない

Release のスキーマは values: ブロックを機械的に禁止しています。オペレーターは Release から Component や Feature に values を書くことはできません。これは JSON Schema レベルでのスキーマによる強制であり、社会契約でも慣例でもありません。しかも明示的です。すべてのエンティティドキュメントは読み込み時にその種類のスキーマに照らして検証されるため、values: を含む Release は黙って無視されるのではなく、ファイルと問題のキーを示す診断とともにビルドを停止させます。

これは、値がすべての環境で同一であることを意味するわけではありません。環境ごとの差異に対してサポートされている方法は、パラメーターの巻き上げ(Parameter Hoisting)です。

  1. 開発者が Aggregate で型付きの parameters.* フィールドを公開します。
  2. Component の values テンプレートがそれを参照します:storage_size: "{{ .parameters.db_size }}"。
  3. Release がパラメーターを満たします:parameters: { db_size: "100Gi" }。
  4. レンダリング出力には環境固有の値が反映されます。

どの値を環境ごとの差異のために公開するか(parameters の宣言)と、それがどのようにコンポーネントの値へ流れ込むか(テンプレートの参照)について、Aggregate は唯一の信頼できる情報源であり続けます。Release は満たすだけで、上書きはしません。

同じ不変条件を守る制約がほかに 2 つあります。

  • Release が extends を使う場合、aggregate: ポインターの宣言はスキーマで禁止されています。子の Release は、親と同じ開発者の意図(Developer Intent)をデプロイしなければなりません。
  • Release は、Aggregate が宣言していないコンピュートを持ち込むことも、開発者が宣言したエッジの向き先を変えることもできません。Architect が宣言したソケットの範囲内で、Release は既存のコンポーネント間のエッジを配線し、設定できます。開発者が配線したエッジにエッジ単位の infra を設定したり、宣言済みだが未バインドのソケットへのエッジを既存のコンポーネントに配線したりします。エッジ単位の values を宣言すること(それは Aggregate に残ります)、Component の usesSchema が宣言していないソケットをバインドすること、存在しないコンポーネントにエッジを向けることはできず、いずれもビルドを停止させます。中ほどの節がどの宣言を指しているかに注意してください。ソケットはカタログの Component の usesSchema に現れていなければなりません。Aggregate の作成者は自分のコンポーネント型が宣言していないソケットを指定できますが、Release の側は意図的に同じようには開かれていません。オペレーターはアーキテクチャを考案するのではなく、その中で配線と設定を行います。

エッジ単位の接続設定のスコープは利用側です。エッジに載った values と infra は、そのエッジを記述したノードのレンダリングコンテキストにのみ現れ、対象のコンテキストには決して現れません。したがって、コンポーネント自身のレンダリング出力は、他のコンポーネントがそれに対して行う接続に左右されません。対象へのエッジを配線または設定しても、対象の Recipe がレンダリングする内容が乱れることは決してありません。それらの接続が見える唯一の場所は、対象にアタッチされた Feature です。その FeatureRecipe はどのコンポーネントが対象を使用しているかを読み取れるため、それが出力するリソース(たとえば、宣言された呼び出し元だけを正確に許可するポリシー)は配線に従いますが、対象自身の出力は従いません。その場合でも、エッジ単位の values と infra は利用側にとどまります。

6. WebAssembly の ABI 境界:ドメイン固有の知能は Wasm に置かれる

Go のホストバイナリには、クラウド固有やインフラ固有のロジックが一切含まれていません。ドメイン固有の知能、テンプレートのレンダリング、整形はすべて、組み込みの Wazero ランタイムが実行する WebAssembly プラグインの内部に厳密に置かれます。Go ホストはパイプラインを調整し、各ソケットが持つエンコーディングで、ペイロードをメモリポインターとして ABI 越しに Wasm ゲストへ渡します。

ここから 2 つの系が導かれます。

  • Provider 固有のロジック(Helm 固有のレンダリング、Terraform 固有の整形、Compose 固有のマージ)が Go コンパイラのコアに置かれることは決してありません。コンパイラは、Recipe が spec.capability で宣言したプロバイダー名を、それを担当するプロバイダーレンダリング用の Plugin に解決し、ノードをそのプラグインにディスパッチします。変換そのものは完全に Wasm ゲストの中で実行されます。標準プロバイダー向けのプロバイダーごとの Go コードはホストにないため、プロセス内にフォールバック先はありません。担当する Plugin に解決されないプロバイダー名は、何らかの組み込みのデフォルトをレンダリングするのではなく、ビルドを停止させます。
  • ポリシーのロジック(セキュリティルール、コンプライアンスチェック、FinOps の計算)が Go コンパイラのコアに置かれることは決してありません。ポリシーは、企業がオプトインする Wasm ガバナンスソケットに属します。ビルドを受理または拒否するために判定ロール(ir-verdict / render-verdict)でアタッチされたプラグイン、またはラベルやアノテーションを形作るために変換ロール(label-transform / annotation-transform)でアタッチされたプラグインです。

ABI 境界により、Go のコアはコンパクトで監査可能、かつクラウド非依存に保たれます。プロバイダーのレンダリングロジックを差し替えることは Wasm 成果物の差し替えであり、Aggrega 自体の再コンパイルではありません。

7. 関心の分離(4 ドメイン分割):指針であって牢獄ではない

Aggrega の設計指針は、記述を 4 つのドメインに分けます。

  • Developer Intent:Aggregate。
  • Platform Architect:Component と Feature のカタログエンティティ。
  • Platform Ops:Recipe、FeatureRecipe、Plugin(プロバイダーレンダリング用の Plugin を含む)。
  • Platform Operator:Manifest、Release。

うまく機能している典型的なデプロイは、この分割に従っています。開発者はアプリケーションの意図を書き、物理インフラは書きません。Ops は物理インフラを書き、アプリケーションロジックは書きません。Aggrega はこのように使われることを想定して設計されており、公式ドキュメント、例、標準ライブラリのカタログはこの分割に沿って記述されています。

4 ドメイン分割は指針と設計上の枠組みであって、コンパイラによる強制ではありません。コンパイラは(不変条件 1 により)主張を持ちません。ユーザーは次のことを自由に行えます。

  • ロールをまとめる(一人が Aggregates と Recipes の両方を書く)。
  • 関心を混在させる(企業のカタログが求める場合に、Architect がコンプライアンスラベルを core/* の Components に直接ハードコードする)。
  • ドメインの境界を越える(レガシーコードが求める場合に、開発者がパラメーターの巻き上げを使ってインフラ上の関心事を Aggregate に注入する)。

コンパイラは、スキーマ検証に合格する記述パターンであれば何でも受け付けます。アーキテクチャはベストプラクティスを推奨しますが、コンパイラが実際に拒否するドメインの越境は、スキーマレベルの制約(不変条件 5 にある Release での values: の禁止など)だけです。それ以外の分離はすべて社会契約であり、カタログの作成者によって、また企業がオプトインする場合は Wasm ガバナンスソケットによって守られます。

8. 決定的な出力

入力が同一であれば、コンパイラはバイト単位で同一の出力を生成します。同じカタログに対して同じ Aggregate + Release + Manifest を 2 回コンパイルすると、バイト単位で一致するレンダリング済みの成果物が得られます。

これは、GitOps ツールや差分ベースのレビューワークフローが頼りにしている契約です。入力を変更していないプルリクエストは、レンダリング出力に差分を生じさせないはずです。入力を変更したプルリクエストは、その変更が意味する差分だけを示すはずです。不要な並べ替えも、タイムスタンプの揺れも、マップの反復順序による乱れもありません。

決定的な出力は、3 つの規律によって維持されます。

  • 作成者の順序に従うマップ:反復順序がレンダリング出力に影響しうるマップはすべて順序付きマップのコンテナーを使い、反復がハッシュ順ではなく作成者の宣言順に従うようにします。
  • 作成者がテンプレートの入力を通じて明示的に注入しない限り、レンダリング済みの成果物に時刻やランダムな内容を含めません。
  • レンダリングは純粋です。同じ入力で同じ Wasm ゲストを呼び出せば、同じ出力が生成されます。

コンパイラの --trace フラグ(language-reference/cli/aggrega-build.md を参照)は、作成者とオペレーターにこの不変条件を検証する手段を提供します。--trace を有効にして同じ入力を 2 回コンパイルすると、バイト単位で同一のトレースダンプが生成されます。パスごとの差分があれば、それが回帰の場所を特定します。決定性はリリース時だけの性質ではありません。ノードごとのトレースレイアウトを通じて、コンパイラのあらゆる中間状態で観察できます。

決定的な出力という契約があるからこそ、Aggrega を GitOps ループにおける信頼できる情報源として安全に使えます。

解決階層をまたぐ不変性の範囲

バイト単位で同一の出力という保証の範囲は、ロックファイルに固定された成果物です。つまり、ロックファイルがダイジェストを記録しているレジストリの成果物を通じて解決されたエンティティ(3 階層のエンティティ解決モデルのレジストリ層)です。ビルドが、Release がパスで指定するファイル(./ または ../ で始まるローカルパス)や、ワークスペースのカタログディレクトリ内のエンティティ(ワークスペースとキャッシュの層にある catalog_dirs:)を読み込む場合、不変性はそれらのファイルがビルド間で変わらないことに依存します。ロックファイルは、ワークスペースのカタログディレクトリにあるエンティティを、そのドキュメントと宣言されたファイルのダイジェストによって記録するため、pull 以降に変更されたエンティティがあれば、ビルドはそれをレンダリングせずに停止します。ただし例外が 1 つあります。Manifest が、Component や Feature の名前でもある参照によって指定した Recipe や FeatureRecipe は、その参照のもとで Component または Feature として記録されます。そのため、その入力はロック内で隣にあるピンによってのみ保持され、それ自身のドキュメントへの編集は検出されません。ファイルを元のまま保つのは、ソース管理システム(一般的には Git)の責任です。

基になるファイルが 2 回のコンパイルの間に変わったローカルパスの参照は、コンパイラへの入力の形が変わっていなくても、レンダリング出力に正当な差分を生じさせます。決定的な出力の保証は維持されています(同じバイトの入力 → 同じバイトの出力)が、ローカルファイルが変わったために入力が異なるのです。すべてのソースについてビルド間の不変性を必要とするカタログは、成果物をローカルパスやワークスペースのディレクトリから読み込むのではなく、レジストリからロックファイルで固定されたキャッシュへ pull します。ロックファイルがバイト単位の同一性のよりどころです。