Provider アーキテクチャ
provider は、Recipe の入力種別をプロバイダーネイティブなマニフェストファイルにレンダリングします。Recipe が capability: helm、capability: compose、またはその他のプロバイダー名を宣言すると、コンパイラはその名前を提供する provider にレンダリングをディスパッチします。この章では、provider が provider-rendering Plugin としてどのように実現されるか、ディスパッチがどのように機能するか、そしてコンパイラを各 provider に結び付ける plugin-socket 契約について説明します。
この章で扱わない内容: Recipe が出力を生成するために使用する 3 つの入力種別による合成モデル(source: + valuesMapping:、workload:、artifacts: — それぞれインラインのコンテンツまたは $import: を受け付けます)。このモデルはすべての provider に横断的に適用され、各 provider がどの入力種別をサポートするかを対応付ける Provider Capability Matrix も含めて、../../architecture/16-recipe-input-composition.md で説明しています。
provider-rendering Plugin
Provider レンダリングは、pluginType: provider を持つ Plugin によって提供されます。プロバイダーレンダリング Plugin は次のように動作します。
- 1 つ以上の provider 名を提供します — これは
spec.provider.capabilitiesで宣言されます。Recipe が指定する provider 名(spec.capability: helm)は、spec.provider.capabilitiesリストにその名前を含む provider-rendering Plugin に結び付けられます。複数の Plugin が同じターゲットを提供する場合、ワークスペースは.aggrega-config.yaml内の provider バインディングによってそれらの中から選択します。このバインディングはaggrega pullの時点で解決され、ロックファイルに記録されます。バインディングがなく候補がちょうど 1 つの場合はその候補が使われ、バインディングがなく候補が複数ある場合は、候補のプラグインを列挙してビルドが明示的に停止します。 - provider-socket のメタデータを同じブロックに保持します —
spec.providerは、上記の capability リストを provider のその他の宣言とともに保持します。spec.provider.workloadSchemaは JSON Schema 2020-12 の宣言で、プラットフォームが所有する Workload 種別がこの provider のネイティブ出力にどのように変換されるかを記述します。標準ライブラリのカタログは、合成を行う provider において、文書化された変換契約としてこれを宣言します。spec.provider.wellKnownAnnotationsは、provider が読み取るaggrega.ai/境界アノテーションを列挙します。合成入力(workload:)のサポートは provider の特性であり、レンダリング時に強制されます。workloadSchemaの有無によって決まるものではありません。
spec.provider ブロックを含む、Plugin エンティティのフィールドレベルの記述仕様の全体については、../entities/plugin.md を参照してください。
プロバイダーごとのディスパッチ
すべての Recipe は、その spec の先頭でちょうど 1 つの capability: を宣言します。コンパイラはこのフィールドを読み取り、その名前を提供するプロバイダーにレンダリングをディスパッチします。Recipe は複数のプロバイダーを同時に対象にすることはできません。複数プロバイダーの合成は Release のレベルで行われます。境界は異なるプロバイダーのコンポーネントを混在して保持でき、境界の評価済みアセンブリパスにおける各プロバイダーのコントリビューターは独立してアセンブルされます。(path, provider) のタプルごとに 1 つのアセンブリです。
単一ノードのディスパッチ経路は次のとおりです。
- コンパイラは、対象プロバイダーのマッピングセクションの下で、Manifest の 3 段階のルックアップを通じてこのノードの Recipe URI を解決します。Manifest のプロバイダー軸によるグループ化により、「同じ Component に対し、プロバイダーごとに異なる Recipes」が自然なパターンになります。
- 解決された Recipe の
spec.capabilityが、ディスパッチ先のプロバイダー名を特定します。 - コンパイラはその名前に対応するプロバイダーをバインドします。
spec.provider.capabilitiesリストにその名前を含むプロバイダーレンダリング Plugin を解決し、その Plugin のゲストを通じてレンダリングします。レンダリングは Wasm のみで行われます。フォールバック先となるホスト内レンダラーは存在しないため、提供する Plugin に解決されないプロバイダー名は、ルーティング時にビルドを明示的に停止させます。 - プロバイダーは、ノードごとのレンダーコンテキスト(ピラーの値、
.context.*のプロジェクション、Recipe の入力種別)とともに呼び出されます。 - プロバイダーはレンダリング結果を返します。コンパイラは、レンダリングされたファイルを、境界の評価済み
directory:とコンポーネントごとのsubDirectory:を結合したものをキーとする(path, provider)ごとのアセンブラーにルーティングします。同じプロバイダーの下で同じパスに評価される 2 つの境界は、アセンブラーを共有します。標準的なパターンは、親境界と、directory: "{{ .parent_boundary.directory }}"を持つ 2 つの子境界が 1 つのマージされたアセンブリにまとまるものです。
Manifest のプロバイダー軸によるディスパッチの形については ../entities/manifest.md を、Recipe 側の単一プロバイダー宣言については ../entities/recipe.md を参照してください。(path, provider) ごとのアセンブリモデルと、評価済みパスを制御するパステンプレート変数の許可リストは、../path-template-variables.md に記載されています。
Wasm プラグインの契約
Provider のレンダリングは WebAssembly サンドボックス内で実行されます。Go コンパイラがホストであり、provider-rendering Plugin がゲストです。コンパイラは各ノードについてそのノードのレンダーコンテキストをプラグインに渡し、プラグインはレンダリングしたファイルを返します。この契約はすべての provider で共通です。
- 双方向の正準バイナリエンコーディング。 コンパイラはレンダーコンテキスト(ノードの値とアタッチメント、パース済みの
.workload、評価済みのアーティファクトエントリ、解決済みの.sourceの名前のみのリスト、境界のメタデータ)を正準 CBOR(RFC 8949 §4.2.1)としてエンコードし、プラグインに渡します。プラグインは同じエンコーディングで、レンダリングしたファイルのリストを診断とともに返します。各ファイルは、ノードの出力ルートからの相対パスと、そこに書き込む正確なバイト列からなり、ファイルの形式を任意で添えられます。1 つのノードのレンダリングから、境界のアセンブル、境界をまたぐリンクの接続まで、ソケットのすべてのエクスポートがこのエンコーディングを双方向で扱い、各言語のプラグイン開発キットがプラグインのためにデコードとエンコードを行います。このエンコーディングでエクスポートの出力形式に従わない応答はビルドを停止させます。各エクスポートのペイロードはプラグインの契約に記載されています。 - ファイルシステムへのアクセスはありません。 Plugins はホストのファイルシステムから任意のファイルを読み取ることはできません。Recipe が指定するソース(レジストリ内のチャート、リポジトリ内のモジュールなど)は、プラグインの実行前にコンパイラによって解決されます。プラグインはその名前のみの一覧を受け取り、選択したファイルをホスト関数を通じてコンパイラに要求します。このホスト関数は、そのノードのソース配下にあるファイルについてのみ応答します。
- ネットワークへのアクセスはありません。 Plugins は決定的かつ密閉的であり、独自の接続を開きません。レンダリング中にプラグインが必要とする外部入力(チャートの values が参照するリモートスキーマなど)は、コンパイラの外部入力ホスト関数を通じて要求されます。このホスト関数は、その参照に対してワークスペースが固定したコンテンツから応答します。
- 決定的な出力。 同一の入力と同じプラグインバージョンが与えられた場合、プラグインはバイト単位で同一の出力を生成しなければなりません。この契約により、コンパイラのバイト単位で同一な出力の保証が、プラグイン層を通じてエンドツーエンドで成立します。
--verify-determinismを指定したビルドは、すべてのノードを 2 回レンダリングし、ノードの 2 回のレンダリング結果が異なる場合に停止します。
コンパイルパイプライン内の他の Wasm ソケット(ガバナンスソケットの変換ロールと判定ロール)を含む、より広い拡張性レベルでのプラグインソケットのアーキテクチャについては、../../architecture/14-extensibility.md を参照してください。
Aggrega の標準ライブラリのプロバイダー
helm、helm-chart、compose、terraform、cloudformation の各プロバイダーが、標準ライブラリのプロバイダーセットを構成します。これらは一般的なデプロイ先をカバーしており、エンタープライズのチームが独自のプロバイダーを作成する必要はありません。
helm は 3 つの入力種別すべてをサポートします。sourced(Helm SDK を通じて取得したアップストリームの Helm チャートに、Recipe の valuesMapping の出力をチャートのオーバーライドとして適用します)、synthesized(パース済みの Workload から出力されるフラットな Kubernetes YAML で、Workload の form によって選ばれるコントローラーオブジェクト(Deployment、StatefulSet、DaemonSet、Job、または CronJob)に Services と PVC を加えたもの)、artifacts(チャートの出力と並ぶスタンドアロンの YAML ファイル)です。3 つの種別のうちどれを受け付けるかについては、../../architecture/16-recipe-input-composition.md の Provider Capability Matrix を参照してください。
helm-chart は、sourced モード(アンブレラチャートによる構成:境界ごとに 1 つのチャート、コンポーネントごとに 1 つのサブチャート)と、それに併せて配置される artifacts: を、両方の記述形式でサポートします。$import: で読み込まれた artifacts: エントリは、まず Aggrega によって Go テンプレートとして処理され、レンダリング前にチャートの templates/ ディレクトリに注入されます。インラインコンテンツの artifacts: エントリも同じように評価され、来歴情報をマージせずにサブチャートのルートに配置され、チャート自身のテンプレートが Helm の .Files.Get / .Files.Glob を介してそれを読み込みます。スタンドアロンの artifacts のみの Recipe は、このプロバイダーが宣言する種別には含まれず、synthesized 種別も含まれません。アンブレラはサブチャートを統括するものであり、Workload 種別は各サブチャートの内部に属する末端の概念(helm プロバイダーの領域)だからです。
compose は次をサポートします。sourced(compose ファイルを読み込み、valuesMapping のオーバーレイをディープマージします)、synthesized(stateless と stateful の form について、パース済みの Workload から compose の services: + volumes: + networks: を出力します。persistentTemplate のボリューム処理は縮退し、レプリカごとの PVC は警告とともに単一の共有名前付きボリュームにまとめられます。daemon、scheduled、task の form には compose への対応付けがなく、明示的に停止します)、artifacts(トップレベルのキー services: / networks: / volumes: / configs: が境界ごとに統合された docker-compose.yaml にマージされる compose フラグメント)。Artifacts は他の 2 つの種別のいずれとも併用でき、スタンドアロンの artifacts のみの Recipe(source: も workload: もない artifacts:)も、このプロバイダーが宣言する種別です。そのフラグメントは同じ規則でマージされるため、ノードは宣言した内容だけを提供し、持たないコンピュートの代わりとなる Workload を必要としません。
terraform は、sourced(Terraform モジュールをそのままベンダリングし、valuesMapping の出力を境界のルート設定にあるそのコンポーネントの module ブロックの引数として渡します)と artifacts(記述された HCL または .tf.json の本文を、テンプレートの評価結果のまま書き換えずに出力します)をサポートします。synthesized 入力種別は提供しません。プラットフォームの Workload 種別から任意の Terraform リソースへの忠実な対応付けが存在しないためです。このプロバイダーは設定を出力するだけで、Terraform を実行することはありません。ランタイムに依存する値は、Terraform のランタイムが apply 時に解決する ${ ... } 補間文字列のまま残ります。
cloudformation は、境界を 1 つの AWS CloudFormation スタックテンプレートにレンダリングします。コンポーネントが記述したリソースフラグメントを単一の純粋な JSON テンプレートにまとめ、各コンポーネントの provides をスタックの Outputs として公開し、uses エッジをスタック内では Fn::GetAtt として、スタック間では Fn::ImportValue / Fn::GetStackOutput として接続します。sourced と artifacts の入力をサポートし、CloudFormation を実行することなく設定を出力します。ランタイムでのみ決まる値は CloudFormation の組み込み関数のまま残ります。
プロバイダーリファレンスの索引 から各プロバイダー固有のリファレンスページに移動できます。各プロバイダーがどの入力種別を受け付けるかは、../../architecture/16-recipe-input-composition.md の機能マトリクスに記載されています。
カスタムプロバイダー
独自のプロバイダーを作成するエンタープライズチームは、標準ライブラリと同じパターンに従います。まず、提供するプロバイダー名を spec.provider.capabilities に宣言し、spec.provider の残りのメタデータもあわせて記述したプロバイダーレンダリング Plugin(pluginType: provider)を作成し、次に上記のレンダリング契約を実装した Wasm アーティファクトを配布します。コンパイラはカスタムプロバイダーを標準ライブラリのプロバイダーとまったく同じように扱います。プロバイダーごとのディスパッチは、Recipe が宣言するプロバイダー名に基づいて動作します。
プロバイダーの作成方法は、後回しにされることなく文書化されています。プロバイダーの作成では、動作するプロバイダーゲストを最初から最後まで構築します。describe() による自己報告、ビルド、Plugin エンティティ、アタッチ、そして出力を読めるレンダリングまでを扱います。Wasm プラグイン開発者ガイドはエンティティと公開ライフサイクルのリファレンスであり、プラグイン契約は各ソケットのペイロードと結果の形を文書化しています。ゲストは、プラグイン開発キットを使って Go、Rust、TypeScript のいずれかで作成します。