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

マネージドデータベースとそれを読み取るサービス(Terraform と CloudFormation)

1 つの Aggregate が、PostgreSQL データベースとそれを読み取るサーバーを保持します。同じ Aggregate を AWS に対して 3 通りにビルドします。1 つ目は 1 つの Terraform ルート構成としてで、 データベースは terraform-aws-modules プロジェクトが公開している RDS モジュールでプロビジョニングし、 サーバーは Fargate 上の Amazon ECS サービスとして実行します。2 つ目は両方を保持する 1 つの CloudFormation スタックとして、 3 つ目は 2 つの CloudFormation スタックとしてで、データベースを一方に、サーバーをもう一方に置きます。

各ターゲットで、サーバーはデータベースのアドレスを、そのターゲット自身が解決する形式で受け取ります。 ルート構成ではモジュール出力の参照、1 つのスタック内では Fn::GetAtt、2 つのスタックをまたぐ場合は Fn::ImportValue です。 コンパイラはそのいずれも評価しません。アドレスはインスタンスが作成されるまで存在しないため、 ビルドは参照をそのまま受け渡し、ターゲットがデプロイ時にそれを解決します。

このページの出力ブロックは、これらのページの出力の読み方に従い、実際の実行からコピーしたものです。

ファイル

  • aggregate.yaml — 開発者の意図です。ロール orders_admin が所有する論理データベース orders を持つ型 core/datastore/postgres の db コンポーネントと、それを使用する型 core/compute/server の api コンポーネントを定義します。このファイル内のキーや値には AWS に関するものはありません。
  • manifest-terraform.yaml — データベースを Recipe terraform/postgres-rds-terraform-aws-modules に、サーバーを terraform/server-ecs に、core/backup Feature を terraform/backup-native にバインドします。
  • manifest-cloudformation.yaml — データベースを cloudformation/postgres-rds に、サーバーを cloudformation/server-ecs に、core/backup Feature を cloudformation/backup-native にバインドします。
  • release-terraform.yaml — 両方のコンポーネントを 1 つの境界に置き、Terraform の Manifest を通じてビルドします。
  • release-one-stack.yaml — 両方のコンポーネントを 1 つの境界に置き、CloudFormation の Manifest を通じてビルドします。そのため、両方が単一のスタックに組み立てられます。
  • release-two-stacks.yaml — 同じ意図を 2 つの境界に分割します。そのため、サーバーからデータベースへの参照はスタックの境界をまたぎます。
  • .aggrega-config.yaml — 標準ライブラリのカタログの解決元となるハブレジストリを指定します。

この例で使用するエンティティはすべてそのカタログにあります。リリースファイルの隣には何もコピーされていません。

サーバーが要求するもの

サーバーは database という名前のソケット上に 1 つのエッジを宣言し、データベースが公開するエントリのうち 4 つを、自身の設定が読み取る環境変数名で要求します。

api:
type: core/compute/server
uses:
database:
db:
target: db
inject:
env:
- in: DB_HOST
from: host
- in: DB_PORT
from: port
- in: DB_USER
from: user
- in: DB_NAME
from: database

core/compute/server は独自のソケットを宣言しないため、database はアドホックなソケットです。このエッジはセレクターも inject 許可リストも持ちませんが、各 from: キーはやはりデータベースが公開するキーでなければなりません。この契約については adhoc-uses-socket を参照してください。Aggregate はアドレス、ポート番号、クラウドプロバイダーを一切指定せず、以下の 3 つのビルドすべてで同じファイルです。

オペレーターが提供するもの

各 Release は、オペレーターがすでに運用していて Recipes が読み取るものを infra.overrides の下に指定します。RDS の DB サブネットグループとデータベースのセキュリティグループ、ECS クラスター、タスクが接続するサブネットとセキュリティグループ、そして ECS がイメージのプルとログの書き込みに使う実行ロールです。 サーバーのイメージは infra.image です。サーバーの Recipes はどちらも、イメージ、クラスター、サブネット、セキュリティグループ、実行ロールを必須とし、Terraform のデータベース Recipe はサブネットグループを必須とします。いずれかが欠けたビルドは、ネットワークやロールを代わりに選ぶことはせず、そのキーを示して停止します。

これらの値はすべてプレースホルダーです。123456789012 は AWS のドキュメントが例で使うアカウント番号であり、example-cluster、 example-private-db-subnets、subnet-… と sg-… の ID、ロール、 registry.example.com/orders-api:1.0.0 は、ご自身のアカウント内のリソースを表しています。 ビルドはこれらを照会しないため受け付けますが、plan やデプロイの前に置き換えてください。

Terraform の Recipes は、カタログの Terraform 式の綴りでキーを読み取ります (subnet_group、subnet_ids、vpc_security_groups、cluster、 execution_role_arn)。CloudFormation の Recipes は、リソースプロパティ自身の名前でキーを読み取ります(DBSubnetGroupName、VPCSecurityGroups、Cluster、 Subnets、SecurityGroups、ExecutionRoleArn)。そのため、同じオペレーターの値でも 2 つのターゲットで綴りが異なります。

サンプルを生成する

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

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

Terminal window
aggrega scaffold --example aws-rds-and-ecs-service

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

Terminal window
cd aws-rds-and-ecs-service

ビルド

この例には 3 つのリリースが含まれているため、ビルドするものを指定してください。1 回の実行でビルドされるリリースは 1 つです。新しいコピーでは、各リリースを初めてビルドするときに --auto-pull を渡し、ビルド中にそのロックファイルが埋められるようにします。最初の Terraform ビルドでは、RDS モジュールをその git リポジトリから、Recipe 自身のピンが記録しているコミットで取得します。

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

次のように出力されます(<workspace> はこの例のフォルダを表します)。

Pull complete: release-terraform.lock (entities=11, source_artifacts=1, external_inputs=0)
Total build time: 9.4s
Build completed: 151 files written to <workspace>/dist

ロックファイルが存在すれば、通常のコマンドでそれに基づいてビルドされます。

Terminal window
aggrega build --release release-terraform.yaml
Total build time: 5.7s
Build completed: 151 files written to <workspace>/dist

AI アシスタントを使う

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

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

1 つの Terraform ルート構成

境界のルート構成は dist/one-root/terraform/aggrega.modules.tf に出力され、各コンポーネント自身のファイルは、その module ブロックが指すディレクトリに置かれます。ベンダリングされた RDS モジュールは modules/db/ に、カタログ内でその Recipe の隣に保持されているサーバーの ECS モジュールは modules/api/ に置かれます。ルート構成の全体は次のとおりです。

# Root configuration for this boundary. Each component rendered here is one
# module block below, and the directory that block points at holds that
# component's own files. One configuration means one dependency graph, which is
# what lets a reference or a depends_on reach from one component to another.
module "api" {
source = "./modules/api"
assign_public_ip = false
cluster = "example-cluster"
cpu = "256"
desired_count = 2
environment = {"DB_HOST":"${module.db.db_instance_address}","DB_NAME":"orders","DB_PORT":"5432","DB_USER":"orders_admin"}
execution_role_arn = "arn:aws:iam::123456789012:role/example-ecs-task-execution"
image = "registry.example.com/orders-api:1.0.0"
memory = "512"
name = "api"
port = 8080
security_groups = ["sg-0fedcba9876543210"]
subnet_ids = ["subnet-0123456789abcdef0","subnet-0fedcba9876543210"]
}
module "db" {
source = "./modules/db"
allocated_storage = 50
backup_retention_period = 14
create_db_subnet_group = false
db_name = "orders"
db_subnet_group_name = "example-private-db-subnets"
engine = "postgres"
engine_version = "16"
family = "postgres16"
identifier = "db"
instance_class = "db.t3.small"
manage_master_user_password = true
multi_az = true
port = "5432"
skip_final_snapshot = false
storage_type = "gp3"
username = "orders_admin"
vpc_security_group_ids = ["sg-0123456789abcdef0"]
}

サーバーの environment 引数は、エッジが要求した 4 つの値を運びます。DB_HOST は ${module.db.db_instance_address} です。データベースの Recipe は、この同じルートが module "db" として宣言するモジュール呼び出しを通じて、RDS モジュール自身の db_instance_address 出力への参照を公開します。そのため Terraform はこれをここで plan 時と apply 時に評価し、サーバーのモジュールはインスタンスのアドレスを通常の入力として受け取ります。残りの 3 つは、コンパイラが事前に知っていたプレーンテキストです。Release が設定するポートと、Aggregate が記述した 2 つの名前です。

これが機能するのは、サーバーの Recipe が source: Recipe であるためです。そのマッピングはサーバーの module ブロックの引数になり、これは Terraform が隣接するモジュールが宣言されたスコープで評価する唯一の位置です。仕組みと、コンシューマーが参照を他の場所に書いた場合に何が問題になるかについては、別のコンポーネントが公開した値の利用と実例となるペアを参照してください。同じ理由で、いずれかのモジュールディレクトリ単体ではなく、このディレクトリ(aggrega.modules.tf を含むディレクトリ)を plan してください。

このディレクトリの作業用コピーで tofu init -backend=false を実行すると、ルートとベンダリングされたモジュールがディスクから読み込まれ、プロバイダーのみが取得されます。

Initializing modules...
- api in modules/api
- db in modules/db
- db.db_instance in modules/db/modules/db_instance
- db.db_instance_role_association in modules/db/modules/db_instance_role_association
- db.db_option_group in modules/db/modules/db_option_group
- db.db_parameter_group in modules/db/modules/db_parameter_group
- db.db_subnet_group in modules/db/modules/db_subnet_group
[… omitted: provider installation, whose versions move with the registry, and OpenTofu's closing advice]

続いて tofu validate は次のように出力します。

Success! The configuration is valid.

1 つの CloudFormation スタック

Terminal window
aggrega build --release release-one-stack.yaml --auto-pull
Pull complete: release-one-stack.lock (entities=11, source_artifacts=0, external_inputs=0)
Total build time: 6.2s
Build completed: 1 file written to <workspace>/dist

組み立てられたスタックは dist/one-stack/cloudformation/cloudformation-stack.json に出力され、3 つの リソースを持ちます。RDS インスタンスである Db、ECS サービスである Api、そして そのサービスが実行するタスク定義である ApiTaskDefinition です。ApiTaskDefinition 内の コンテナの環境は次のとおりです。

"Environment": [
{
"Name": "DB_HOST",
"Value": {
"Fn::GetAtt": [
"Db",
"Endpoint.Address"
]
}
},
{
"Name": "DB_NAME",
"Value": "orders"
},
{
"Name": "DB_PORT",
"Value": "5432"
},
{
"Name": "DB_USER",
"Value": "orders_admin"
}
],

DB_HOST は、インスタンスの Endpoint.Address に対する Fn::GetAtt であり、 データベースの Recipe がコンポーネント名 db から導出する論理 ID Db を対象とします。 CloudFormation はスタックの作成時にこれを解決し、サーバーのタスク定義が Db の属性を読み取るため、 インスタンスを先に作成します。 スタック内参照を参照してください。

2 つの CloudFormation スタック

Terminal window
aggrega build --release release-two-stacks.yaml --auto-pull
Pull complete: release-two-stacks.lock (entities=11, source_artifacts=0, external_inputs=0)
Total build time: 6.2s
Build completed: 2 files written to <workspace>/dist

aggregate.yaml は何も変わりません。Release はデータベースを data 境界に、サーバーを app 境界に配置するため、それぞれが独自のスタックにアセンブルされ、サーバーからデータベースへのエッジは一方のスタックから他方へまたがります。データベースのスタック dist/two-stacks-data/cloudformation/cloudformation-stack.json は、エッジが消費する各エントリを Export 付きの出力として公開します。その Outputs は次のとおりです。

"Outputs": {
"dbXXdatabase": {
"Value": "orders",
"Export": {
"Name": "aggrega--orders-two-stacks--two-stacks-data-zscloudformation--db--database"
}
},
"dbXXhost": {
"Value": {
"Fn::GetAtt": [
"Db",
"Endpoint.Address"
]
},
"Export": {
"Name": "aggrega--orders-two-stacks--two-stacks-data-zscloudformation--db--host"
}
},
"dbXXport": {
"Value": "5432",
"Export": {
"Name": "aggrega--orders-two-stacks--two-stacks-data-zscloudformation--db--port"
}
},
"dbXXprotocol": {
"Value": "postgres"
},
"dbXXuser": {
"Value": "orders_admin",
"Export": {
"Name": "aggrega--orders-two-stacks--two-stacks-data-zscloudformation--db--user"
}
}
},

protocol も公開されますが、どのエッジも読み取らないため Export を持ちません。サーバーのスタック dist/two-stacks-app/cloudformation/cloudformation-stack.json は、4 つのそれぞれを同じ名前で読み戻します。

"Environment": [
{
"Name": "DB_HOST",
"Value": {"Fn::ImportValue":"aggrega--orders-two-stacks--two-stacks-data-zscloudformation--db--host"}
},
{
"Name": "DB_NAME",
"Value": {"Fn::ImportValue":"aggrega--orders-two-stacks--two-stacks-data-zscloudformation--db--database"}
},
{
"Name": "DB_PORT",
"Value": {"Fn::ImportValue":"aggrega--orders-two-stacks--two-stacks-data-zscloudformation--db--port"}
},
{
"Name": "DB_USER",
"Value": {"Fn::ImportValue":"aggrega--orders-two-stacks--two-stacks-data-zscloudformation--db--user"}
}
],

各エクスポート名は、Release 名、プロデューサー境界の出力ディレクトリ、コンポーネント、エントリを連結したものであるため、ビルド時に確定し、コンシューマーはどちらのスタックも存在しないうちからその名前を指定できます。ここではどちらの Release もアカウントやリージョンを宣言していないため、読み取りは同一アカウントの Fn::ImportValue になります。名前の組み立て方と、コンシューマーが代わりにアカウントをまたいで読み取る場合については、スタック間の接続で説明しています。インポートはすでに存在するエクスポートに対してのみ解決されるため、データベースのスタックはサーバーのスタックより先に作成されます。2 つのスタックの順序付けはビルドの外側で、オペレーターが行います。

パスワードは RDS 自身が管理します

Aggregate はデータベースのユーザーを指定しますが、パスワードについては何も指定せず、どの Release もデータベースに認証情報を付与しません。どちらのターゲットでも、Manifest が選択する Recipe がパスワードを RDS に委ねます。上のモジュールブロックでは manage_master_user_password = true、各スタックのインスタンスでは ManageMasterUserPassword です。1 スタック構成のテンプレートにおけるデータベースの Properties は次のとおりです。

"Properties": {
"AllocatedStorage": 50,
"BackupRetentionPeriod": 14,
"DBInstanceClass": "db.t3.small",
"DBName": "orders",
"DBSubnetGroupName": "example-private-db-subnets",
"Engine": "postgres",
"EngineVersion": "16",
"ManageMasterUserPassword": true,
"MasterUsername": "orders_admin",
"MultiAZ": true,
"Port": 5432,
"StorageType": "gp3",
"VPCSecurityGroups": [
"sg-0123456789abcdef0"
]
},

RDS はインスタンスの作成時に管理者パスワードを生成し、AWS Secrets Manager に保管します。パスワードを含むビルド入力はないため、3 つのビルドのいずれもパスワードをファイルに書き込みません。サーバーはユーザー名を受け取りますが、パスワードは受け取りません。Secrets Manager からパスワードを読み取る処理は、サーバーのイメージが実行するコードに委ねられます。

バックアップはアタッチメントです

RDS は、特に指定がなければインスタンスを自らバックアップし、各自動バックアップを 7 日間保持します。各 Release は、db のエントリでデータベースに core/backup をアタッチすることで、それを 14 日間保持します。

db:
features:
backup:
type: core/backup
infra:
retention_days: 14

各 Manifest は Feature をそのターゲット用の FeatureRecipe、つまり terraform/backup-native または cloudformation/backup-native にバインドし、どちらも何もレンダリングしません。バックアップはインスタンスの設定であるため、データベースの Recipe がアタッチメントを読み取り、インスタンスを書き込む場所に保持期間を書き込みます。モジュールブロックの backup_retention_period = 14 と、上記のインスタンスの Properties 内の "BackupRetentionPeriod": 14 です。単一スタックのテンプレートがちょうど 3 つのリソースを持つのはそのためです。

ビルドはデプロイではない

各ビルドは dist/ 配下にファイルを書き出して停止します。Terraform、OpenTofu、CloudFormation を実行することはなく、AWS に対して認証することもなく、Releases が指定する識別子を参照することもありません。ルート構成の plan と apply、およびスタックの作成は、プレースホルダーを置き換えたうえで、各自の認証情報を使って出力に対して行う手順です。

同一の入力、同一の出力

変更のない入力から 2 回ビルドすると、3 つの release のそれぞれについてバイト単位で同一の出力が得られます。コンパイラはライブデータを一切解決しないため、再ビルドでバイトを変化させうるものを新たに見つけることはありません。差分ベースのレビューが前提とするのは、この性質です。

dist/、.aggrega/、および *.lock ファイルは生成物であり、コミットされません。これらはコミットされているファイルから再生成されます。