extends と implements
extends による継承
カタログエンティティ(Component、Feature)は extends キーワードによる単一継承をサポートしており、Platform Architect は共有ベースの上に特化したエンティティを構築できます。YAML エンベロープのディープマージは両方の種類に共通です。継承する側のエンティティのメタデータ、ラベル、宣言的な構造テーブルはベースの一致するキーを上書きし、ネストされたマップは再帰的にマージされます。両者が異なるのはデータピラーの扱いです。
このページはカタログの種類を扱いますが、extends を宣言する種類はそれだけではありません。 Release と Manifest もこれを宣言します。どちらもカタログにインデックスされるエンティティではなく、互いに並べて作成されるデプロイ側のドキュメントです。そのため参照はカタログエンティティではなくファイルを指し、折り込まれるのはスキーマではなく作成対象の記述面です。これらについては entities/release.md と entities/manifest.md を参照してください。
Component の extends は構造を合成し、ピラーをそのまま継承する
Component の場合、extends は metadata.labels、metadata.annotations、spec.featuresSchema(アタッチメントスロット)、spec.usesSchema(トポロジーソケット)、spec.inject(自己注入の許可リストで、エントリはベースを先にして重複なく連結されます)を合成します。3 つのデータピラー(values、infra、provides)は合成されません。継承する Component はピラーの内容を記述しません。リテラルのマーカー schema: inherited を書き、チェーンのどの深さでも、ベースが記述したとおりのベースの schema: ブロックを受け取ります。
公開されている Component スキーマは、このマーカーを必須かつ排他的なものとし、これに反するものをドキュメントの読み込み時にそれぞれ固有の診断で拒否します。対象は、extends: を宣言する Component で schema: の下にピラーの内容を記述した場合、そこで schema: を完全に省略した場合、そして extends: を宣言しない Component で schema: inherited を書いた場合です。
ここから 2 つの帰結が生じ、それらは逆方向に働きます。
- キーの集合はベースによって固定されます。 継承する Component はピラーのキーを宣言しないため、ベースが宣言するキーを隠したり、削除したり、型を変更したりすることはできず、独自のキーを追加することもありません。ベースのインスタンスと、それを継承するもののインスタンスは、同じピラー契約に対して検証されます。
- 制約の強化は
assertions:に移ります。 継承したピラーよりも受け入れる範囲を狭める必要がある特化は、絞り込んだスキーマのリーフとしてではなく、自身に対する述語としてそれを表現します。ベースcore/base-serverがtls_enabled: { type: boolean, default: true }を宣言している場合、TLS を無条件に必須とする特化は次のように書きます。
apiVersion: aggrega.ai/v1beta1kind: Componentmetadata: name: core/tls-only-server version: 1.0.0 labels: component.aggrega.ai/type: "server"spec: extends: core/base-server schema: inherited # values, infra and provides are the base's, verbatim assertions: tls-is-mandatory: | {{- if not .values.tls_enabled -}} {{- fail "this component requires tls_enabled: true" -}} {{- end -}}このルールは、継承したピラーブロックが受け入れる値を拒否します。これがまさにここでいう制約の強化です。逆方向を表現する手段はまったくありません。特化は制約を持つリーフを再記述できないため、継承した制約を緩めることはできません。完全な合成テーブルと、ベースと拡張のペアの具体例については、entities/component.md の「Catalog Authoring: Extending Base Components」を参照してください。
Feature の extends はピラーを合成する
Feature の場合、子の schema: は JSON Schema 2020-12 の合成セマンティクスに従ってベースのものと合成され、作成されたインスタンスの検証対象となる単一のマージ済みスキーマが生成されます。クレデンシャル Features(feature.aggrega.ai/kind: secret のラベルを持つもの)はこれを使って共有ベースの上に構築します。子のクレデンシャル Feature は親を継承して、そのボールトクエリスキーマを受け継ぎつつ制約を絞り込みます。
コンパイラはその変更の方向について立場を取りません。合成は構造的であるため、ベースの制約を広げる子の制約もビルドを停止させることなく合成され、アドバイザリとして表示されます。それを拒否するものはありません。Feature ベースの制約は、カタログの作成者がレビューによって守る共有の期待であり、プラットフォームが取り締まる契約ではありません。
implements によるインターフェースバインディング
Recipes と FeatureRecipes は、spec の最上位にある implements: キーワードによって Component または Feature のインターフェースにバインドされます。このバインディングは、この Recipe / FeatureRecipe がどのカタログインターフェースの具体的な実装であるかを宣言し、次の 3 つの形式のバージョンマッチングをサポートします。
- 完全一致 —
implements: core/api-server:1.0.0— Component 型の特定の 1 バージョンにマッチします。 - メジャー互換範囲 —
implements: core/api-server:^1.0.0—>=1.0.0, <2.0.0を満たす任意のバージョンにマッチします(SemVer のメジャー互換)。Recipe が単一の固定バージョンではなく互換範囲をサポートする場合に使用します。 - バージョンなし —
implements: core/api-server— Component 型の任意のバージョンにマッチします。Recipe がその型のすべてのバージョンに対応する場合に使用します。
implements: が Recipe を選択することはありません。選択するのは Manifest のマッピングです。この宣言が駆動するのは、各マッピングエントリに対する整合性チェック(マッピングされた型のバージョンが、マッピングされた Recipe の implements: を 3 つの形式のいずれかで満たすか、その Recipe がその型の拡張元であるベースを実装していなければならない)と、マッピングなしの診断とエディタ補完が提示する候補リストです。Recipe の implements: がマッピングされた型にもそのいずれのベースにも一致しないマッピングエントリはビルドを停止させ、そのマッピング、Recipe、およびその implements: の値を示します。components.type キーが、そのキーの示さないバージョンのコンポーネントインスタンスに適用される場合(バージョンなしで書かれたキーではすべてのインスタンス)、チェックはそのインスタンス自身の型について、ビルドがコンパイルするバージョンで改めて行われ、それを満たさない Recipe は同様にビルドを停止させ、そのインスタンスを示します。
implements: バインディングは、「同じ Component 型に対し、provider ごとに異なる Recipes を使う」ことを可能にする仕組みです。core/postgres Component には、helm provider 向けに実装する Recipe と、compose provider 向けに実装する別の Recipe を持たせることができます。各 Recipe は同じ implements: 値を宣言し、Release がビルドに使う Manifest がその型を目的の Recipe にマッピングします。
ベースに対して書かれた Recipe は、それを拡張するすべてに対応する
implements: はベースを指定し、ベースを指定する Recipe は、チェーンの深さを問わず、そのベースを拡張するすべての Component の具体的な実装となります。そのため、extends で構築された特殊化には独自の Recipe が不要です。これにより、公開されたラッパーを低コストで利用できます。公開するチームは Component を作成し、デプロイするチームはすべてのターゲットでベースの Recipes を再利用します。
ここでは 2 つの事実が同時に成り立ち、両者は別のものです。これらを「特殊化には何も必要ない」とひとまとめにしてしまうと、失敗する Manifest を書くことになり、その原因を誤ったファイルで探すことになります。
- Recipe はマッチします。 Manifest のマッピングの型キーとマッピング先の Recipe の
implements:との整合性チェックは、Recipe がマッピング対象の型そのものまたはその型が拡張する任意のベースを実装していれば、マッピングを受け入れます。上記の 3 つのバージョン形式は、型そのものに適用されるのとまったく同じようにベースにも適用されます。implements: core/base-server:^1.0.0を宣言する Recipe は、ベースがバージョン1.4.0である特殊化を満たし、ベースが2.0.0である特殊化は満たしません。 - それでも Manifest は特殊化自身の型をマッピングします。 Recipe の選択は完全なマッピングキーによって行われます。
enterprise/labelled-serverのインスタンスには独自のmappings.components.typeエントリが必要で、core/base-server用に書かれたエントリは継承されません。独自のエントリを持たない特殊化は、ベースがマッピングされていても、未マッピングインスタンスの診断で停止します。
したがって、特殊化の作成コストは Manifest 1 行のみで、新しい Recipe は不要です。
# The wrapper extends core/base-server and authors no pillars.# core/helm/base-server declares: implements: core/base-serverspec: mappings: components: type: enterprise/labelled-server:1.0.0: core/helm/base-server:1.0.0マッピング対象の型の extends チェーンをたどれない場合(ループを形成している、または指定されたベースがカタログに存在しない場合)、マッピングではなくそのチェーンの障害でビルドが停止します。マッピングは、依存するチェーンが解決されるまで判定できないためです。このチェックは、このマシン上にすでにある Components(カタログディレクトリ内のもの、およびローカルのアーティファクトキャッシュがロックファイルのピンで保持しているもの)だけを通してチェーンをたどり、レジストリには問い合わせません。そのため、レジストリにのみ存在するベースはここでは存在しないものとして扱われます。それを取得するのが aggrega pull の役割です。ベースはそれを拡張するすべてのものの依存関係であるため、pull は Release が到達するすべての extends: チェーンをたどり、どのカタログディレクトリにもない各ベースを取得してロックファイルにピン留めし、後続のビルドはそこでそのベースを見つけます。Aggregate がベースのインスタンスも宣言している場合を除き、Manifest にはベース自体のための行は必要ありません。
Recipe の候補提示は、このマッチングルールより狭い範囲にとどまります。マッピングなしの診断が表示する候補リストや、エディタ補完がマッピング値に適用する並び順は、要求された型そのものを実装する recipe を挙げ、そのベースのいずれかを実装する recipe までは広げません。
実行可能なエンドツーエンドのウォークスルー(カタログ内の公開ラッパー、それを利用する Manifest の 1 行、レンダリング出力を形作るベースの Recipe、独自のマッピングを持たないラッパーインスタンスが引き起こす停止)については、実例 examples/extends-wrapper/ を参照してください。
エンティティ横断のバージョン利用
Aggrega のすべてのエンティティ種別(Component、Feature、Aggregate、Recipe、FeatureRecipe、Manifest、Release、Plugin、SchemaLibrary、MappingLibrary、WorkloadLibrary、ArtifactLibrary)は必須の metadata.version フィールドを持ち、同じ SemVer 正規表現(architecture/02-ecosystem-philosophy.md に従う MAJOR.MINOR.PATCH)で検証されます。バージョンの形は統一されていますが、バージョンの利用はエンティティ種別ごとに異なります。解決に積極的に関与するバージョンもあれば、コンパイラが照合しない記述的な来歴情報にとどまるものもあります。下の表はライブラリ以外の種別を対象とし、各エンティティのバージョンフィールドに対してコンパイラが何を行うかを示し、10-status.md の 4 ラベルのステータス分類を使って各利用方式を分類します。4 つのライブラリ種別は、その方式が一様でかつ異なるため表の対象外です。利用側はライブラリを名前のみで参照し、任意で :<version> による最小バージョンの下限を指定でき、解決されたバージョンとそのコンテンツダイジェストは Release ごとのロックファイルが保持します。
| エンティティ | 利用方式 | ステータス |
|---|---|---|
| Component | 型参照の解決、Recipe の implements: 照合 | available — 両方で完全一致、キャレット範囲(^MAJOR.MINOR.PATCH)、バージョンなしの形式に対応(バージョン解決およびステータス → バージョン照合を参照) |
| Feature | アタッチメント参照の解決、FeatureRecipe の implements: 照合 | Component と同じ |
| Recipe | Manifest のマッピング階層の解決 | available — マッピング値における完全一致、キャレット範囲、バージョンなしの形式。それぞれ条件を満たす最も高いバージョンを選択します |
| FeatureRecipe | Manifest のマッピング階層の解決 | Recipe と同じ |
| Aggregate | 親の aggregates[].type 参照の解決 | available — 完全一致、キャレット範囲、バージョンなしの形式に対応し、いずれも条件を満たす最も高いバージョンを選択(バージョン解決を参照) |
| Plugin | recipe.spec.capability → spec.provider.capabilities による Provider ディスパッチ | available — 素の capability が provider を選択し、それに付けたピン(helm:<version>、helm:^<version>)がそのプラグインのどのバージョンでレンダリングするかを選択します。プラグインの識別子はダイジェストを含まない oci://<repository> 参照と metadata.version の組であり、コンテンツダイジェストはリリースのロックファイルに記録され、ビルドは取得したバイト列をそれと照合して検証します |
| Manifest | IR グラフの来歴(manifest_version) | available(来歴のためにのみ読み取られ、解決のディスパッチには関与しない) |
| Release | IR グラフの来歴(release_version)+ テンプレートのメタデータ(.metadata.release_version) | Manifest と同じ |
カタログ解決の方式(Component、Feature、Aggregate、Plugin)。 これらの種類のいずれかへの参照(component の type、feature アタッチメントの type、サブ aggregate インポートの aggregates[].type、パイプラインステップの plugin)は、Version resolution が説明する規則によって解決されます。完全一致、キャレット範囲、またはバージョンなしの参照は、カタログが保持するバージョンのうち条件を満たす最も高いバージョンを選択し、pull、ビルド、validate、エディタ、アシスタント向けツールはいずれもこの同じ規則を適用します。Component または Feature の場合、implements: のマッチングは同じ 3 つの形式を逆方向から読みます。つまり、具体的な型のバージョンを Recipe または FeatureRecipe が宣言する形式と照合するもので、選択ではなく後述の整合性チェックとして行われます。Provider-rendering-plugin のディスパッチはより単純な形を使います。素の recipe.spec.capability を provider レンダリングプラグインの spec.provider.capabilities に対して名前で検索し、capability に書かれたバージョンのピンがそのプラグインのどのバージョンでレンダリングするかを選択します。どのバージョンも満たさない場合は停止します。
Manifest のマッピング階層の解決。 Manifest のフラットな mappings.{components,features} による解決の仕組み(name 階層と type 階層、名前が型より優先、バージョン付きの型がバージョンなしの型より優先)は entities/manifest.md に記載されています。リゾルバはこれらのマッピングを利用します。Recipe と FeatureRecipe の選択は、マッピングの値をロックファイルとカタログに対して直接参照するものであり、型にマッピングがないコンポーネントやアタッチメントはビルドを停止させます。spec.implements は Recipe を選択しません。これは作成者がすでに書いたマッピングに対するロード時の整合性チェックであり、マッピングなしの診断とエディタ補完が提示する候補リストの出典です。その後の機能ディスパッチは、Manifest の構造的な形ではなく、解決された Recipe の spec.capability フィールドに基づいて行われます。
記述的来歴方式(Manifest、Release)。 Manifest の metadata.version と Release の metadata.version は、コンパイラが来歴情報を設定する際に読み取られ、IR グラフの来歴ブロックに manifest_version および release_version として現れます。レンダリングされた出力のラベルにはどちらも含まれません。テンプレートからは Release のバージョンが .metadata.release_version として参照できます。いずれのバージョンも、解決のディスパッチのために他のエンティティのバージョンと照合されることはなく、純粋な来歴情報です。
表の読み方。 4 ラベルの分類は、「バージョンフィールドがスキーマで受け入れられ、エンティティ上に存在する」(常に真。SemVer 正規表現は統一)ことと、「コンパイラが解決時にこのバージョンと照合する」(エンティティごとに異なる)ことを区別します。
スキーマブリッジによるピラー横断パイピング:意図とインフラストラクチャの橋渡し
Aggrega は Domain 1 と Domain 4 の間に強い関心の分離を設けています。Developer は values ブロックに認知的なロジックを記述し、Operator は infra ブロックで物理的なサイジングを指定します。Aggregate.yaml のスキーマは、その具体的な帰結の一つを強制します。infra キーワードは Aggregate のコンポーネントインスタンスにもその features アタッチメントにも存在せず、additionalProperties: false と組み合わせることで、スキーマ検証によって拒否されます。Developer は Developer Intent の中で物理的なサイジングを指定すべきではありません。特定の値がアプリケーションのケースに適している場合(例:ハードコードされたポートや特定の CPU 数)は、Architect がそれを Component の schema: 宣言で明示的に公開でき、その値は values を通じて流れます。
特定のインフラストラクチャ制約がコンポーネントの契約に本質的に含まれる場合(10,000 のプロビジョンド IOPS を必要とする高スループットの取引データベースや、ちょうど 4 基の GPU で実行する必要がある ML ワークロードなど)、Platform Architect は スキーマブリッジによるピラー横断パイピング パターンを用いて、専用の Component を通じてその制約を公開します。
インフラストラクチャを意識したコンポーネントのためのスキーマブリッジパターン。
Component は、その schema: 宣言を通じて、特定のインフラストラクチャのダイヤルを開発者の values ブロック内に公開し、バインドされた Recipe の valuesMapping: テンプレートがその値をレンダリングされる infra: 形式の出力へ渡します。その結果、認知的な意図と物理的なサイジングの間に型付きのブリッジが生まれます。開発者は検証済みのフィールドを通じてハードウェア制約を指定し、その制約はどちらの側も生のインフラストラクチャコードを書くことなく Ops へ流れます。ダイヤルはピラーキーであるため、その契約がそれを所有する Component 上で宣言されます。ベースを extends: する Component はピラーキーを宣言しないため、新たに導入することはできません。
# Domain 2: The Platform Catalog (the schema-bridge Component)apiVersion: aggrega.ai/v1beta1kind: Componentmetadata: name: core/high-perf-postgres version: 1.0.0 labels: component.aggrega.ai/type: "stateful-server"spec: schema: values: # Expose the dial safely to the Developer with a typed contract. required_iops: { type: integer, min: 1000, max: 100000, required: true } infra: # Operator-owned sizing the Recipe below reads alongside the dial. storage: { size: { type: string, default: 100Gi } } compute: { instance_class: { type: string, default: db.m5.large } }# Domain 2: The Platform Catalog (the Recipe pipes the dial into provider infra)apiVersion: aggrega.ai/v1beta1kind: Recipemetadata: name: aws-rds-high-perf-postgres version: 1.0.0spec: implements: core/high-perf-postgres:^1.0.0 capability: terraform source: ./modules/rds valuesMapping: | # The Recipe pipes the developer's values.required_iops into the provider's infra-side knob. iops: {{ .values.required_iops }} allocated_storage: "{{ .infra.storage.size }}" instance_class: "{{ .infra.compute.instance_class }}"# Domain 1: The Developer Intent (remains capability-agnostic)components: trading-db: type: core/high-perf-postgres:1.0.0 values: required_iops: 10000 # Developer dictates the hardware constraint safelyマルチ環境スケーリング(パラメータのホイスティング要件)。
開発者の Aggregate.yaml を変更せずにこのハードウェア制約を GitOps 環境(Dev と Prod)にわたってスケールさせるため、開発者は値を型付きの parameters 契約へホイストします。Ops は環境ごとの Release ファイルによって特定の IOPS 要件を満たします。コンパイラの実行順序がこの流れを保護します。パラメータ契約の検証は解決時に実行され、補間によってパラメータが周囲の values: 文字列へ解決され、Recipe の valuesMapping: テンプレートが解決済みの値をレンダリング出力へ渡します。
1. Developer Intent(ダイヤルの抽象化)。
Developer は IOPS を制御する必要があることを理解していますが、型付きの parameters 契約を通じて明示的な数値を環境レベルへ抽象化します。
spec: parameters: env_iops: type: integer min: 1000 max: 100000 description: Provisioned IOPS for the trading-db instance components: trading-db: type: core/high-perf-postgres:1.0.0 values: required_iops: {{ .parameters.env_iops }} # Hoisted to the environment2. GitOps の Releases(Ops による充足)。
Ops は環境ごとの Release ファイルで parameters 契約を満たします。型付きの契約は、補間が実行される前に、Release が提供する各値を検証します。
- Dev 環境(
release-dev.yaml):env_iops: 1000 - Prod 環境(
release-prod.yaml):env_iops: 25000
コンパイル順序。 この仕組みは、解決時におけるコンパイラの厳密な実行順序によって保護されています。
- パラメータ契約の検証。 Release が提供する各パラメータ値は、Aggregate の型付き
parameters:宣言に対して検証されます。Prod の値25000は検証を通過します(min: 1000, max: 100000の範囲内)。500という値であれば、明確なエラーで停止します。 - 補間。 コンパイラは Prod の
Releaseのパラメータ値を読み取り、25000をAggregateYAML 文字列のvalues.required_iopsに補間します。マージされたパラメータマップはレンダリングの間も保持されるため、パステンプレートのサーフェスは.parameters.<slot>を直接読み取れます。値テンプレートのサーフェスは、Aggregate のvalues:ブロックにすでに書き込まれた補間後のリテラルを使用します。このマップはすべてのレンダーフェーズが完了するまで読み取り可能であり、それが解決されたコンパイルからのみ参照できます。 - スキーマ検証。 Component の
schema:宣言は、生成されたvalues:ディクショナリを検証します。values.required_iops: 25000はスキーマのmin: 1000, max: 100000を満たします。 - Recipe の valuesMapping レンダリング。 バインドされた Recipe の
valuesMapping:テンプレートは、values.required_iopsをプロバイダのinfra形式の出力(iops: 25000)へ渡します。Wasm プロバイダプラグインは正しい物理データベース設定を生成します。開発者は明示的なハードウェア制御を得て、Ops は環境ごとのスケーリングを得て、Aggregateはケイパビリティに依存しないままとなります。