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

1 つの契約、3 つの実現

PostgreSQL データベースとそれを読み取るアプリケーションを、変更を加えない 1 つの Aggregate から 3 通りの方法でデプロイします。クラスタ内で動作する PostgreSQL、マネージドクラウドインスタンスとしての PostgreSQL、そしてこの Release がデプロイされる前から存在していた PostgreSQL サーバーです。

学ぶべきは、何が変わらないかです。 アプリケーションは、データベースから欲しいキーとそれらを何と呼ぶかを一度だけ指定します。 3 つのうちどれが応答したかを知ることはありません。コンパイラも知ることはありません。コンパイラは選択された Recipe が公開したキーを読み取り、文字列をルーティングするだけです。

唯一変化するもの

.-- helm/postgres ---------- a StatefulSet in the cluster
/
core/datastore/postgres --- terraform/postgres-rds -- an RDS instance in Terraform
one Component \
one contract '- helm/postgres-external -- a server that already exists

3 つの Recipes が同じ Component を実装します。それぞれが同じ provides キーを公開します。host、port、user、database、protocol、そしてスクレイパーがデータベースのメトリクスをどこで見つけるかを示すキーで、これは 3 つとも空です。どれが実行されるかは、Manifest の 1 行で決まります。

ファイル

  • aggregate.yaml — 開発者の意図を表すもので、3 つのデプロイすべてで同じドキュメントです。型が core/datastore/postgres の db コンポーネント、それを uses する app、そしてアプリケーションが求める 5 つのキーを宣言します。ここにはターゲットも、クラウドも、Recipe も一切現れません。
  • manifest-selfhosted.yaml、manifest-managed.yaml、manifest-external.yaml — Ops のマッピングです。それぞれが 1 行で実現方式を選びます。PostgreSQL コンポーネント型をどの Recipe に結び付けるかです。マネージドのものは、その Releases がアタッチするバックアップ Feature もバインドします。
  • release-selfhosted.yaml、release-managed.yaml、release-external.yaml — 各 Release でのオペレーターによるサイジングです。クラスター内のものではストレージとエンジンのバージョン、マネージドのものではストレージ、HA、core/backup のアタッチ、参照するものでは既存サーバーのアドレスを指定します。
  • release-managed-dns.yaml — マネージドの Release をもう一度示したもので、オペレーターがインスタンスに付ける DNS 名を含みます。これによりアプリケーションには名前解決できる名前が渡されます。
  • catalog/ — アプリケーション自身の Component と、それをレンダリングする唯一の Recipe です。データベース側のものはすべて、標準ライブラリから変更なしで取り込まれます。

サンプルを生成する

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

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

Terminal window
aggrega scaffold --example postgres-three-realizations

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

Terminal window
cd postgres-three-realizations

ビルド

Terminal window
aggrega build --release release-selfhosted.yaml --auto-pull
aggrega build --release release-managed.yaml --auto-pull
aggrega build --release release-managed-dns.yaml --auto-pull
aggrega build --release release-external.yaml --auto-pull

--auto-pull は各 Release の初回ビルド時にそのロックファイルを書き出し、以降のビルドではフラグは不要です。どちらも dist/ に書き出し、ビルドは以前のビルドが残したものを消去せずにファイルを追加します。1 つの実現方式の出力だけを確認するには、実行の間に dist/ を削除してください。

Terminal window
rm -rf dist && aggrega build --release release-managed.yaml

AI アシスタントを使う

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

Aggrega のツールのみを使用し、フォルダーは自分で作成しないでください。Workspace フォルダーにまだ `postgres-three-realizations` フォルダーがない場合は、`example` を `postgres-three-realizations` に設定し、`dir` を指定せずに `scaffold` ツールを 1 回呼び出してください。これにより、新しい `postgres-three-realizations` フォルダーに例が書き込まれます。次に、各 Release について 1 回ずつ、`release-selfhosted.yaml`、`release-managed.yaml`、`release-managed-dns.yaml`、`release-external.yaml` の順に `build` ツールを呼び出してください。毎回、`workspace_root` を `postgres-three-realizations`、`release` をそのファイル、`auto_pull` を true、`write` を true に設定します。各ビルドが書き込んだファイルを教えてください。それらは `postgres-three-realizations/dist/` の下にあります。

それぞれがレンダリングするもの

セルフホスト — デプロイメントがサーバーを実行する

helm/postgres はクラスター内にデータベースを合成します。StatefulSet、 ClusterIP Service、headless Service です。provides.host はその Service の 素の名前なので、アプリケーションはクラスター内 DNS でそこに到達します。

dist/stack/helm/app-deployment.yaml
- name: DB_HOST
value: db-default

マネージド — クラウドプロバイダーがサーバーを実行する

terraform/postgres-rds は aws_db_instance を Terraform HCL として出力し、オペレーターの ha のサイジングと core/backup のアタッチはインスタンスのネイティブ設定に対応付けられます。アタッチの retention_days: 14 はインスタンスの backup_retention_period = 14 になります。アプリケーションは引き続き Kubernetes にレンダリングされます。このデプロイメントの 2 つの側は、共有ターゲットではなく、データベースが公開する契約で接します。

dist/stack/helm/app-deployment.yaml
- name: DB_HOST
value: ${module.db.address}

その値はホスト名ではなく、このビルドの中にそれをホスト名に変えるものはありません。 RDS インスタンスのアドレスはインスタンスが作成されるまで存在しないため、 事前に実行されるコンパイラが参照できるものは何もありません。 Recipe が公開するのは、データベース自身のモジュールの出力への Terraform 参照です。 コンパイラはそれを手を加えずにエッジの向こうへ渡し、アプリケーションの Recipe はそれをそのまま受け取り、上に示したリテラルの文字列として Kubernetes マニフェストにレンダリングされます。コンテナにはそのテキストが渡されます。

DB_PORT は異なります。"5432" としてレンダリングされます。Recipe がインスタンスのポートを Release から設定し、同じ値を公開しており、その値は何かが存在する前から既知だからです。

2 つのコンポーネント間のネイティブな配線は、ターゲットが自身の出力の中で行うものなので、 ここでは行うべきものがありません。 このエッジの両端は異なるターゲットでレンダリングされます — データベースは Terraform HCL に、アプリケーションは Kubernetes マニフェストに — そして Terraform 参照は Terraform 構成の中でのみ意味を持ちます。 その境目を越えると、公開された値は他の文字列と同様にテキストとして届けられます。 データベースと同じルート構成の中で source: Recipe として Terraform 上にレンダリングされる コンシューマーは、同じ参照をそのモジュールの引数の 1 つとして受け取り、そこで Terraform がそれを解決します。

これは RDS の特殊なケースではなく一般的な規則です。実行中のシステムの状態に 依存するものはすべて、ランタイムが解決する決定的なポインターとして表現され、 コンパイラが取得する値として表現されることはありません。コンパイラの役割は ポインターを変更せずに届けることです。届いた先でそれを解決できるようにするのは Recipe の作者の役割です。消費側が使えるアドレスを公開するか、両方の コンポーネントに同じターゲットにレンダリングされる Recipes を与えます。

アプリケーションが解決できる名前をインスタンスに与える

terraform/postgres-rds は、そのうちの 1 つ目をオペレーターが設定するオプションとして受け付けます。release-managed-dns.yaml はマネージドの Release に 1 つ追加したもので、オペレーターがインスタンスに与える DNS 名です。

db:
infra:
overrides:
host: db.internal.example.net

Recipe は Terraform 参照の代わりにその名前を host として公開し、 アプリケーションはそれを受け取ります。

dist/stack/helm/app-deployment.yaml
- name: DB_HOST
value: db.internal.example.net
変数release-managed.yamlrelease-managed-dns.yaml
DB_HOST${module.db.address}db.internal.example.net
DB_PORT54325432

出力のうち変わるのはその 1 行だけです。Recipe はその名前に対する DNS レコードもエイリアスも出力せず、ビルドはその名前を解決しません。コンパイラは参照を渡したのとまったく同じようにそれを渡します。インスタンスが存在した後に db.internal.example.net をインスタンスに向けること — オペレーター自身の DNS ゾーン内の、インスタンスのアドレスを指すレコード — は、Release の外側でオペレーターが行うことです。このキーは、下の参照型の実現方式が同じアドレスのために読むものと同じです。この Recipe はそれを素の名前または IP リテラルとして受け付け、スキーム、パス、ユーザー、ポートを含む値はビルドを停止させます。ポートは Release の infra.port であり、コンシューマーはこの 2 つから接続を組み立てるためです。

データベースと同じ Terraform 構成にレンダリングされるコンシューマーも名前を受け取りますが、 それにより参照が与えていた順序を失います。Terraform は、参照先のモジュールの後にそのモジュールを処理しますが、 名前は何も参照しないからです。そのコンシューマーを、データベースの directory: を共有し、 より後の syncWave: を持つ独自の境界に置くと、順序が回復します。

外部 — このデプロイメントでは誰もサーバーを実行しない

helm/postgres-external は何もプロビジョニングしません。その出力全体は、 クラスター内の名前を Release が指定するアドレスに対応付ける 1 つの Service です。

dist/stack/helm/db-service.yaml
[… omitted: the Service's apiVersion, kind and metadata — its name, db, and the labels and annotations every rendered document carries]
spec:
type: ExternalName
externalName: postgres.data.example.net
ports:
- port: 5432

StatefulSet も、ボリュームも、コンテナもありません — サーバーのライフサイクルは完全に このデプロイメントの外にあります。アドレスは Release から来ます。

db:
infra:
overrides:
host: postgres.data.example.net
dist/stack/helm/app-deployment.yaml
- name: DB_HOST
value: postgres.data.example.net

サーバーを参照することは、それを引き継ぐことと同じではありません。この Recipe は 外部所有のままのサーバーに到達します。ここにあるものは何もそれをデプロイメントの管理下に置かず、 ここにあるものは何もそれを変更しません。

アドレスを省くと、ビルドは停止してその旨を伝えます。 参照されるサーバーは アドレスを持つか何も持たないかのどちらかなので、Recipe は空の名前をエイリアスする Service を出力する代わりに拒否します。

[… omitted: what resolving the lockfile prints, the same halt among it, then [CATALOG_ERROR E0033], the Recipe's assertion external_host_supplied, its template position and source, and "error calling fail:"]
assertion failed: the Manifest selects the referenced realization of
PostgreSQL, which addresses a server it does not provision, but no address was
supplied: set infra.overrides.host on this component in the Release to the DNS
name or IP literal the existing server answers on

要点となる比較

アプリケーションのレンダリングされた環境を、3 つ並べて示します。

変数セルフホストマネージド外部
POOL_SIZE101010
DB_HOSTdb-default${module.db.address}postgres.data.example.net
DB_NAMEappdbappdbappdb
DB_PORT543254325432
DB_PROTOCOLpostgrespostgrespostgres
DB_USERappuserappuserappuser

変数は同じで、順序も同じで、毎回変わりません。変わるのは、そのうち 1 つの背後にある文字列だけです。 アプリケーションの Recipe は DB_ 変数をどれも名指ししません。uses エッジが解決したものをそのまま出力するだけであり、そのため 1 つの Recipe が 3 つのデータベースのいずれに対しても変更なしでレンダリングされます。

そして、コンパイラはそれらの文字列が何であるかを知りません。db-default は Kubernetes の Service 名、${module.db.address} は Terraform の参照、postgres.data.example.net は DNS 名です。しかしコンパイラにとって、これらは Recipe がキー host の下に公開し、エッジが DB_HOST として届けるよう求めた 3 つの文字列にすぎません。コンパイラは、それらのいずれかがルーティング可能かどうか、ポートが数値かどうか、db という名前のコンポーネントがデータベースかどうかを検査しません。Component が持つラベルでエッジを照合し、コントラクトが宣言するキーを読み取り、テキストを移しただけです。

境界線はどこにあるか

3 つのデプロイメントはいずれも Ops のマッピングによって選ばれ、開発者のドキュメントはその選択の影響を受けませんでした。これこそが、この例全体が具体的に示そうとしている分担です:

  • 開発者は アプリケーションがデータベースに何を必要とするか を示します。
  • Ops はデータベースが何で構成されるかを示します — 実現方法ごとに Recipe が 1 つです。
  • オペレーターはこのデプロイメントがどれを使うかを示し、そのサイズを決めます。

明日 4 つ目の実現方法 — 別のクラウド、別の運用事業者、ローカル作業用の Compose サービス — を追加しても、それは同じキーを公開する Recipe が 1 つ増え、Manifest に 1 行加わるだけです。このディレクトリの aggregate.yaml は変わりません。