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

ベースの Recipe で提供される公開ラッパー

この例が教えることは 1 つです。別の Component を extends する Component は、そのベースのデータ契約全体を継承するため、ベース向けに書かれたすべての Recipe がすでに拡張側の Component を実装しています。したがって、標準ライブラリのコンポーネントの特化版を公開するコストは、カタログエンティティ 1 つと Manifest の 1 行だけです。独自の Recipe は不要で、ベースへの変更もありません。

ここでのラッパーは example/gateway/nginx-reviewed です。これは、拡張元のコンポーネントである core/gateway/nginx と並んでカタログに含まれています。

ラッパーが追加するもの、継承するもの

ラッパーが記述する部分は、メタデータとソケット 1 つだけです。

metadata:
name: example/gateway/nginx-reviewed
labels:
component.aggrega.ai/type: server
component.aggrega.ai/category: gateway
gateway.example.com/audit-tier: reviewed # added
gateway.example.com/data-zone: eu-west # added
annotations:
governance.example.com/review-board: platform-architecture # added
governance.example.com/contact: platform-architecture@example.com
spec:
extends: core/gateway/nginx:1.0.0
schema: inherited
usesSchema:
reviewed_upstream: # added
selector: "gateway.example.com/audit-tier=reviewed"
inject: [env]

schema: inherited は、拡張する Component が schema: ブロックの代わりに書くリテラルのマーカーです。これは、3 つのデータの柱である values、infra、 provides が、ベースが記述したとおりのベースのものであることを示します。ラッパーは独自の柱のキーを宣言せず、宣言することもできません。契約は、チェーンのどの深さにおいてもベースに属します。

ラッパーが言及しないものはすべて継承されます。aggrega inspect example/gateway/nginx-reviewed --resolved はマージされたエンティティを表示し、その中の 2 点は注意深く読む価値があります。

  • uses ソケットが 3 つあり、1 つではありません。upstream と guard(ベースのもので、upstream は component.aggrega.ai/type=server を選択します)と reviewed_upstream(ラッパーのもの)です。拡張はソケットを追加するもので、セットを置き換えるものではありません。
  • ベースの 3 つの柱がそのまま含まれます。values.upstream_path、 infra.port / engine_version / compute / overrides、そして provides.host / port / protocol で、それぞれにベース自身の説明が付いています。

利用側の Aggregate が書くもの

aggregate-reviewed.yaml は、データベースコンソールの前段に置く 2 つのゲートウェイ層をラッパーとして宣言します。

components:
edge:
type: example/gateway/nginx-reviewed
values:
upstream_path: /api/ # declared by the base; the wrapper never mentions it
uses:
reviewed_upstream: # the socket the wrapper ADDS
internal: { target: internal, inject: { env: [ ... ] } }
internal:
type: example/gateway/nginx-reviewed
values:
upstream_path: /
uses:
upstream: # the socket the wrapper INHERITS
console: { target: console, inject: { env: [ ... ] } }
console:
type: core/devtool/adminer

注目すべきキーは upstream_path です。これは core/gateway/nginx の values の柱で宣言されており、ラッパーのファイルにはどこにも現れませんが、作成者はラッパーのインスタンスにこれを書くことができ、それはレンダリングされたゲートウェイ設定に届きます。これが、柱を丸ごと継承することの実際の意味です。

もう半分は Manifest で、型ごとに 1 行です。

mappings:
components:
type:
example/gateway/nginx-reviewed:1.0.0: compose/nginx:1.0.0
core/gateway/nginx:1.0.0: compose/nginx:1.0.0
core/devtool/adminer:1.0.0: compose/adminer:1.0.0

両方のゲートウェイの行は同じ Recipe を指定しています。compose/nginx は implements: core/gateway/nginx:1.0.0 を宣言しており、ベースを指定する Recipe はそのベースを拡張するすべての Component の実装となります。そのため、ラッパーは変更なしでこの Recipe によって提供されます。ここでは 2 つの事実が同時に成り立ち、それらは別個のものです。

  • Recipe は一致します。 ラッパー自身の型を実装する Recipe は存在せず、 必要もありません。
  • マッピングは依然として必要です。 Recipe の選択はマッピングキーの完全一致で行われるため、 ラッパーには独自の type エントリが必要です。ベースのものは継承されません。 独自のエントリを持たないラッパーのインスタンスは、ベースがマッピングされていても、未マッピングのインスタンスの診断で停止します。

サンプルを生成する

このサンプルは以下のコマンドでビルドできます。または、AI アシスタントにビルドを任せることもできます。

例の名前を付けた新しいフォルダーに例を書き出します。

Terminal window
aggrega scaffold --example extends-wrapper

その後、次に実行するコマンドを表示します。最初のコマンドは新しいフォルダーに移動します。

Terminal window
cd extends-wrapper

ビルド

Terminal window
aggrega build --release release-reviewed.yaml --auto-pull

レンダリングされた出力とロックファイルは生成されるもので、同梱されません。この例は入力をコミットし、それ以外はすべて再生成します。--auto-pull はビルド中にロックファイルを解決します。事前に一度 aggrega pull --release release-reviewed.yaml を実行しても同じことができ、以降のビルドはフラグなしで実行できます。

ラッパーとその拡張元のベースはどちらも共有カタログにあり、このカタログは .aggrega-config.yaml が宣言するデフォルトのレジストリ hub.aggrega.ai から解決されます。ビルドコマンドに --catalog フラグは不要で、このディレクトリから実行する aggrega inspect にも不要です。

ラッパーが core/gateway/nginx を拡張しているため、pull はそれを取得します。ベースはそれを拡張するすべてのものの依存関係であるため、pull はラッパーの extends: をたどり、Manifest がベースを指定しているかどうかにかかわらず、ロックファイルにベースを固定します。ここで Manifest がベースをマッピングしているのは別の理由によるものです — 後述の対照用リリースが、ベースそのもののインスタンスを宣言しているためです。

レンダリングされた dist/compose/docker-compose.yaml に証拠があります。

edge:
image: nginx:1.27.5-alpine
entrypoint:
- /bin/sh
- -c
- echo 'server { listen 8080; location /api/ { proxy_pass http://internal:8081; } }' > /etc/nginx/conf.d/default.conf && exec nginx -g 'daemon off;'
[… omitted: the published port]
labels:
[… omitted: the other provenance labels every rendered document carries]
aggrega.ai/recipe-uri: nginx:1.0.0
[… omitted: the service's network, its depends_on naming internal, and its healthcheck]

証明する内容の順に、3 つの読み取りです。

  • aggrega.ai/recipe-uri: nginx:1.0.0:ベースの Recipe がこのサービスを形作りました。 ラッパーのインスタンスの来歴ラベルがベースの Recipe を示しているのは、それがこのインスタンスをレンダリングした Recipe だからです。
  • location /api/:ベースだけが宣言するキーである values.upstream_path が、 ラッパーのインスタンスに記述され、レンダリングされています。
  • proxy_pass http://internal:8081:reviewed_upstream のエッジが解決されています。 ターゲットの provides.host と provides.port は、ベースの Recipe が読み取る配信キーの下でインジェクションコンテキストに届いたため、ラッパーが追加したソケットは、それを一切知らない Recipe を通って流れます。

ビルドが解決するロックファイルは、同じ事実をリゾルバの側から記録しています。 1 つのダイジェストを持つ 1 つの compose/nginx:1.0.0 エントリが、両方のマッピングキー(ベースの型とラッパーの型)から参照されています。

ラッパーのラベルとアノテーションは、解決されたエッジとともに伝わります。利用側のノードのレンダリングコンテキストは各ターゲットの provides、labels、アノテーションを保持するため、 edge のコンテキストは、そのアップストリームが audit-tier=reviewed であることと、誰がレビューしたかを知っています。そのいずれかをレンダリングされた成果物に含めるかどうかは Recipe の選択です。これらのラベルとアノテーションは、セレクタやポリシーが読み取るためのコンポーネントの識別情報であり、コンパイラが刻印する出力ではありません。

AI アシスタントを使う

Aggrega のツールでセットアップした AI アシスタントでも同じことができます。次のプロンプトを貼り付けてください。

Aggrega のツールだけを使い、フォルダーは自分で作成しないでください。ワークスペースフォルダーにまだ `extends-wrapper` フォルダーがない場合は、`example` を `extends-wrapper` に設定し、`dir` を指定せずに `scaffold` ツールを 1 回呼び出してください。これにより、例が新しい `extends-wrapper` フォルダーに書き込まれます。次に、`workspace_root` を `extends-wrapper`、`release` を `release-reviewed.yaml`、`auto_pull` を true、`write` を true に設定して `build` ツールを呼び出してください。ビルドが書き込んだファイルを教えてください。ファイルは `extends-wrapper/dist/` の下にあります。

対照実験:追加されたラベルの役割

aggregate-unreviewed.yaml は aggregate-reviewed.yaml に 1 箇所の編集を加えたもので、内部層をラッパーではなく素の core/gateway/nginx ベースとして宣言しています。これは失敗することが想定されています。

Terminal window
aggrega build --release release-negative-unreviewed.yaml --auto-pull
# [DEVELOPER_ERROR E0007] aggregate-unreviewed.yaml at .spec.components.edge.uses.reviewed_upstream.internal
# selector violation ("gateway.example.com/audit-tier=reviewed", declared on socket "reviewed_upstream", not satisfied by the labels of "internal"). Add the labels the selector requires to the target's component type, or wire the socket to a component that already carries them.

この停止こそが教訓です。ベースは自身の upstream ソケットを満たします。ベースは component.aggrega.ai/type=server であり、内部層はまったく同じ方法でそのソケットを通じて接続されています。しかしベースは audit-tier ラベルを持たないため、ラッパーのより厳しいソケットがそれを拒否します。ラッパーが追加するラベルこそが、そのインスタンスを選択可能にするものであり、それが表れるのがセレクタです。

知っておくべき停止がさらに 2 つあり、どちらもスキーマが役割を果たしているものです。

  • extends を宣言し、かつ schema: の下に柱の内容を記述する Component は、 ドキュメントの読み込み時に制約を示して拒否されます。schema: を完全に省略したものも同様です。schema: inherited が唯一受け入れられる形式であり、暗黙ではなく明示的に書かれるため、読み手が継承された柱のブロックを書き忘れたものと混同することはありません。
  • ベースが宣言していない values キーは、ラッパーのインスタンス上で、記述されたパスにおいて拒否されます。 適用される契約がベースのものだからです。

これが有用な理由

標準ライブラリのコンポーネントについてレビュー済みの形を決めた組織には、それを保管する場所が必要です。文章で保管すると、ラベル、アノテーション、ソケットは必要とするすべての Aggregate で書き直され、そのうちに食い違っていきます。ベースを拡張する Component として公開すれば、その形は名前を持つ、バージョン管理されたレビュー可能なカタログエンティティになります。それを利用するチームは type: example/gateway/nginx-reviewed と Manifest の 1 行を書くだけで、ベースがサポートするすべてのターゲットにおいて、ベースの契約全体と、それに対してすでに書かれたすべての Recipe を継承します。

これを機能させているのはラッパーのコストの小ささです。ラッパーは構造とメタデータを追加するだけで、それ以外は何も追加しません。柱を宣言しないため、ラッパーのインスタンスとベースのインスタンスは 1 つの契約に対して検証され、ベース向けに書かれた Recipe がその特化版によって想定外の事態に遭うことはありません。