境界をまたぐネットワーク — 1 つのインテント、2 つのデプロイ
2 つのコンポーネントからなるスタック — Adminer データベース UI と PostgreSQL データベース — を 2 つの境界 に分割し、Adminer が境界の継ぎ目を越えてデータベースに 到達する必要がある構成です。同じ開発者インテントが 2 通りにデプロイされ、その 対比こそが学ぶべき点です:
- ローカル (Docker Compose): 各境界はそれぞれ独立した compose ネットワークであり、一方のサービスはもう一方のサービスに名前で到達できません。標準ライブラリの
core/compose-bridgeFeature の compose 用 FeatureRecipe は、その継ぎ目を越えるためのaggrega-gwゲートウェイを生成します。 - Kubernetes (Helm): 各境界はそれぞれ独立した namespace であり、一方の pod は
別の namespace の Service に ネイティブな namespace 間 DNS
(
db-default.backend) で到達します — ブリッジは不要です。データベースは素のサービス 名を公開し、利用側のcore/k8s-dns-resolverルーティング feature がそれを 対象 namespace で修飾します。
compose-bridge は、Kubernetes の namespace と namespace 間 DNS がネイティブに
提供するものです。 継ぎ目の越え方はターゲットによって異なる Ops/Operator の関心事であり、
開発者インテントは変わりません。まったく同じ aggrega.ai/namespace
境界アノテーションが、一方のバリアントでは compose の ネットワーク 配置を、もう一方では
Kubernetes の namespace 配置を決定します。
共有される開発者の意図
aggregate.yaml は両方のバリアントで同一です。
components: adminer: type: core/devtool/adminer uses: databases: primary: target: db inject: env: - in: ADMINER_DEFAULT_SERVER # rewritten/resolved per variant from: host # ← the target db's provides.host db: type: core/datastore/postgres1 本の uses エッジが、データベースの host を ADMINER_DEFAULT_SERVER に注入します。
そのホストが何に解決されるかは Aggregate より下のレイヤーで決まる Ops の関心事です。そのため
同じエッジが compose では aggrega-gw:5432 を、helm では db-default.backend
を生み出し、開発者の意図は一切変わりません。
サンプルを生成する
このサンプルは以下のコマンドでビルドできます。または、AI アシスタントにビルドを任せることもできます。
例の名前を付けた新しいフォルダーに例を書き出します。
aggrega scaffold --example cross-boundary-networkingその後、次に実行するコマンドを表示します。最初のコマンドは新しいフォルダーに移動します。
cd cross-boundary-networkingビルド
各バリアントは 1 つの Release で、それぞれ独自のカタログディレクトリに対してビルドし、1 回の実行につき 1 つの Release をビルドします。
aggrega pull --release release-compose.yaml --catalog catalog-composeaggrega build --release release-compose.yaml --catalog catalog-composeaggrega pull --release release-helm.yaml --catalog catalog-helmaggrega build --release release-helm.yaml --catalog catalog-helmAI アシスタントを使う
Aggrega のツールでセットアップした AI アシスタントでも同じことができます。次のプロンプトを貼り付けてください。
Aggrega のツールだけを使い、フォルダーは自分で作成しないでください。ワークスペースフォルダーにまだ `cross-boundary-networking` フォルダーがない場合は、`example` を `cross-boundary-networking` に設定し、`dir` を指定せずに `scaffold` ツールを 1 回呼び出してください。これにより、例が新しい `cross-boundary-networking` フォルダーに書き込まれます。次に、`workspace_root` を `cross-boundary-networking`、`release` を `release-compose.yaml`、`catalog_dirs` を `catalog-compose` を含むリスト、`auto_pull` を true、`write` を true に設定して `build` ツールを呼び出してください。次に、同じ方法で `release` を `release-helm.yaml`、`catalog_dirs` を `catalog-helm` を含むリストに設定して `build` ツールを呼び出してください。各ビルドが書き込んだファイルを教えてください。ファイルは `cross-boundary-networking/dist/` の下にあります。Variant A — ローカル(Docker Compose): ブリッジ
aggrega pull --release release-compose.yaml --catalog catalog-composeaggrega build --release release-compose.yaml --catalog catalog-compose親の bridge 境界は 2 つの子、frontend(adminer)と backend(db)を保持し、両者は 1 つのディレクトリを共有するため、単一の dist/bridge/compose/docker-compose.yaml にマージされます。各子の aggrega.ai/namespace アノテーションは compose の network になります。親(境界スコープ)にアタッチされた core/compose-bridge は、ネットワークをまたぐ uses エッジから aggrega-gw ゲートウェイを導出します。その標準ライブラリの FeatureRecipe は、境界ごとに一度、ブリッジすべきエッジ(両端がこの 1 つの compose ファイル内にあり、異なるネットワーク上にあるもの)の表を計算し、以下のすべては自身のテンプレートによってその表から読み取られます。
- その
valuesMappingはゲートウェイの nginxstream設定を書き出し、それはマウントされた compose config(トップレベルのconfigs:、/etc/nginx/nginx.confにマウント)として配信されます。この設定はresolverとエッジごとの変数によるproxy_passを持つため、アップストリームは接続時に解決されます(Compose の補間が nginx のためにそのまま残すよう、$は$$にエスケープされます)。 - 同じ
valuesMappingがゲートウェイのx-aggrega-networks-ofの下に両端を指定し、compose プロバイダーがそれを解決するため、ゲートウェイはブリッジされる両方のネットワークに参加します。 - adminer に対して実行されるその
injectMappingは、コンシューマーのADMINER_DEFAULT_SERVERをaggrega-gw:5432に書き換えます。この書き換えは adminer 自身のdatabases接続が配信した値を置き換えます。もし adminer にアタッチされた別の Feature がその変数を配信していた場合、ビルドは置き換えるのではなく、両者を名指しして停止します。
したがってトラフィックは adminer → aggrega-gw:5432 → proxy_pass db:5432 と流れ、ゲートウェイを通じて
ネットワークの境目を越えます。
実行する
cd dist/bridge/composedocker compose uphttp://localhost:8080 を開き(サーバーには aggrega-gw:5432 が入力済み)、ログインします。
| フィールド | 値 |
|---|---|
| システム | PostgreSQL |
| サーバー | aggrega-gw:5432(入力済み) |
| ユーザー名 | appuser |
| パスワード | apppass |
| データベース | appdb |
この認証情報はデモ専用です(スタックがそのまま動作するよう db recipe にインラインで設定されています)。実際のデプロイでは認証情報サブシステムを使用します。
Variant B — Kubernetes (Helm): namespace + namespace をまたぐ DNS
aggrega pull --release release-helm.yaml --catalog catalog-helmaggrega build --release release-helm.yaml --catalog catalog-helm同じ Aggregate を Kubernetes にデプロイします。2 つの兄弟境界があり、それぞれが異なる aggrega.ai/namespace アノテーションを持ち、このアノテーションはすべてのリソースに metadata.namespace として伝播します:
dist/frontend/helm/adminer-deployment.yaml # metadata.namespace: frontenddist/frontend/helm/adminer-default-service.yaml # metadata.namespace: frontenddist/backend/helm/db-statefulset.yaml # metadata.namespace: backenddist/backend/helm/db-default-service.yaml # metadata.namespace: backenddist/backend/helm/db-headless-service.yaml # metadata.namespace: backendaggrega-gw はありません。helm の db recipe は provides.host に素の service 名を公開します。helm provider は合成した Service に <rendered_name>-<service-key>(db-default)という名前を付け、namespace は含めません。コンシューマーは core/k8s-dns-resolver ルーティング feature をアタッチし(Release がそれを ADMINER_DEFAULT_SERVER に向けます)、その feature がコンシューマー自身の側でこの素のホストをターゲットの namespace で修飾します。これにより、Adminer がレンダリングされる前に namespace をまたぐ DNS 名 db-default.backend が生成されます。ホストはプロデューサーに手書きされるのではなく、導出されます:
- name: ADMINER_DEFAULT_SERVER value: db-default.backend # == the rendered db Service <name>.<namespace>この値は、レンダリングされた db Service の metadata.name + metadata.namespace とバイト単位で一致し、それがすべての証明となります。Kubernetes の namespace をまたぐ DNS は決定論的な契約であるため、レンダリングされたホストがレンダリングされた Service の識別子と等しければ、実行時に名前解決されます。配線を検証するのにゲートウェイも稼働中のクラスターも必要ありません。
二面性
| compose(Variant A) | helm(Variant B) | |
|---|---|---|
| 境界の継ぎ目 | 別々の compose ネットワーク | 別々の namespace |
| 越境の仕組み | core/compose-bridge ゲートウェイ(aggrega-gw) | ネイティブな namespace 間 DNS |
ADMINER_DEFAULT_SERVER の解決先 | aggrega-gw:5432(書き換え後) | db-default.backend(呼び出し側で修飾) |
| 追加リソース | aggrega-gw サービスとその設定 | なし |
同じ aggrega.ai/namespace が決めるもの | compose ネットワークへの配置 | k8s namespace への配置 |
開発者の意図は一つです。継ぎ目の越境は provider 固有の Ops/Operator の仕組みです。compose ブリッジが存在するのは、フラットな compose ネットワークには namespace スコープの DNS がないためです。Kubernetes はそれをネイティブに提供します。
両端が異なるプロバイダーでレンダリングされる場合
上記の 2 つのバリアントはいずれも開発者の意図を 1 つに保ち、境界の越え方を決定論的なポインター文字列に委ねます。データベースの provides.host は安定したポインターとして境界の継ぎ目を越えて流れ、各ターゲットはそのポインターを独自の方法で解決します。compose のゲートウェイアドレス、またはネームスペースをまたぐ DNS 名です。コンパイラはプロデューサーとコンシューマーの間で文字列を解釈せずに受け渡すため、ポインターは常に継ぎ目を越えます。
プロバイダーはさらに踏み込み、継ぎ目の両側にある自身のアセンブル済みアーティファクト 2 つの間にネイティブなクロスリファレンスを配線できます。これはそのプロバイダー自身の語彙による参照で、ターゲットプラットフォームがデプロイ時に解決します。CloudFormation プロバイダーは、スタックをまたぐ uses エッジに対してこれを行います。プロデューサー側のスタックが Export を公開し、コンシューマー側のスタックが Fn::ImportValue でそれを読み取ります(providers/cloudformation.md を参照)。ネイティブなクロスリファレンスは同一プロバイダー内での拡張です。両端が同じアーティファクトの語彙を使うため、一方が公開した参照を他方が解決できるからこそ機能します。
uses エッジが異なる 2 つのプロバイダー間の境界を越える場合、つまりプロデューサーがあるプロバイダーで、コンシューマーが別のプロバイダーでアセンブルされる場合、ネイティブなクロスリファレンスは不可能です。一方のプロバイダーの語彙で作られた参照は他方にとって意味を持たず、コンパイラはその間を変換しません。コンパイラは文字列を受け渡すだけで、意味を推論したり、一方のプロバイダーの参照を他方の形式に書き換えたりはしません。そのため、プロデューサーの決定論的なポインターはそのまま継ぎ目を越えます。2 つのプロバイダーのいずれかが CloudFormation のように独自のネイティブなクロスリファレンスを配線する場合、コンパイラは両方のエンドポイント、両方のプロバイダー名、およびソケットを示す警告を出力します。そしてビルドはそのポインターのまま完了します。コンパイラは作成者を信頼し、停止しません。作成者が指定した決定論的なポインターは、安定した DNS 名やインフラストラクチャの補間文字列のように、継ぎ目を越えても解決できる可能性が十分にあり、ターゲットのトポロジーを知っているのは作成者だけだからです。
これにより、継ぎ目の越え方は本来あるべき場所に保たれます。プロバイダーをまたぐポインターが使えるかどうかは作成者が責任を持つデプロイの関心事です。一方のプロバイダーのネイティブな参照を別のプロバイダーのコンシューマー形式に変換することは、主張を持つプロバイダー固有の作業であり、中立なコアの外側に置かれます。
構成
cross-boundary-networking/├── .aggrega-config.yaml # marks this folder as the workspace root; names the hub registry├── aggregate.yaml # SHARED developer intent (both variants)├── release-compose.yaml # Variant A: parent bridge boundary + two networks├── manifest-compose.yaml├── catalog-compose/ # local adminer compose recipe (the component + the rest from standard)├── release-helm.yaml # Variant B: two namespace boundaries, no bridge├── manifest-helm.yaml└── catalog-helm/ # local adminer helm recipe (the components + the rest from standard)この例は標準ライブラリを利用します。各バリアントは、そのバリアント自身のローカルディレクトリを指す --catalog catalog-<variant> でビルドし、そのディレクトリが宣言していないものは .aggrega-config.yaml が指定するデフォルトレジストリ hub.aggrega.ai から解決するため、ローカルエンティティは共有エンティティより先に解決されます。core/datastore/postgres、共有の core/devtool/adminer UI コンポーネント、core/compose-bridge と core/k8s-dns-resolver の Features とその compose および helm の FeatureRecipes、そして compose/helm プロバイダーは標準カタログから取得されます。ローカルに残るのは、この例に固有の教材となる内容、つまりターゲットごとの Adminer レシピです。helm の db レシピは標準ライブラリの helm/postgres であり、その provides.host は素の、自己完結したサービス名です。コンシューマーは標準ライブラリの core/k8s-dns-resolver ルーティング機能を使って呼び出し側でターゲットのネームスペースによる修飾を行うため、レシピは境界のネームスペースをハードコードしません。
ビルドされたバリアントには 2 種類のファイルが存在します。作成した入力(上記のすべて)と、dist/ 配下のコンパイラが生成した出力(マージされた docker-compose.yaml、または名前空間ごとの helm マニフェスト)です。後者を自分で作成することはありません。dist/ は aggrega build によって再生成され、gitignore の対象です。