Lewati ke konten
AggregaAggrega
Pilih Bahasa: Bahasa Indonesia
Halaman ini diterjemahkan oleh mesin. Baca versi asli dalam bahasa Inggris.

Basis data terkelola dan layanan yang membacanya, di Terraform dan CloudFormation

Satu Aggregate memuat sebuah basis data PostgreSQL dan server yang membacanya. Aggregate yang sama dibangun dengan tiga cara terhadap AWS: sebagai satu konfigurasi root Terraform, dengan basis data yang diprovisikan oleh modul RDS yang dipublikasikan oleh proyek terraform-aws-modules dan server yang dijalankan sebagai layanan Amazon ECS di Fargate; sebagai satu stack CloudFormation yang memuat keduanya; dan sebagai dua stack CloudFormation, basis data di satu stack dan server di stack lainnya.

Pada setiap target, server menerima alamat basis data dalam bentuk yang diresolusikan sendiri oleh target tersebut: referensi output modul dalam konfigurasi root, Fn::GetAtt di dalam satu stack, Fn::ImportValue di antara dua stack. Compiler tidak mengevaluasi satu pun di antaranya. Alamat tersebut belum ada sampai instance dibuat, sehingga build meneruskan sebuah referensi dan target meresolusikannya saat melakukan deployment.

Blok output di halaman ini disalin dari eksekusi nyata, sesuai dengan Membaca output di halaman-halaman ini.

Berkas

  • aggregate.yaml — maksud pengembang: sebuah komponen db bertipe core/datastore/postgres dengan basis data logis orders yang dimiliki oleh peran orders_admin, dan sebuah komponen api bertipe core/compute/server yang menggunakannya. Tidak ada kunci atau nilai di dalamnya yang berkaitan dengan AWS.
  • manifest-terraform.yaml — mengikat basis data ke Recipe terraform/postgres-rds-terraform-aws-modules, server ke terraform/server-ecs, dan Feature core/backup ke terraform/backup-native.
  • manifest-cloudformation.yaml — mengikat basis data ke cloudformation/postgres-rds, server ke cloudformation/server-ecs, dan Feature core/backup ke cloudformation/backup-native.
  • release-terraform.yaml — kedua komponen dalam satu batas, dibangun melalui Manifest Terraform.
  • release-one-stack.yaml — kedua komponen dalam satu batas, dibangun melalui Manifest CloudFormation, sehingga keduanya dirakit menjadi satu stack.
  • release-two-stacks.yaml — maksud yang sama dibagi ke dua batas, sehingga referensi server ke basis data melintasi tepi stack.
  • .aggrega-config.yaml — menyebut registri hub tempat katalog pustaka standar di-resolve.

Semua entitas yang digunakan contoh ini berada di katalog tersebut. Tidak ada yang disalin ke samping berkas rilis.

Apa yang diminta server

Server mendeklarasikan satu edge, pada sebuah socket yang dinamainya database, dan meminta empat entri yang dipublikasikan database, dengan nama variabel lingkungan yang dibaca oleh konfigurasinya sendiri:

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 tidak mendeklarasikan socket sendiri, sehingga database adalah socket ad-hoc: edge tersebut tidak membawa selector maupun allowlist inject, dan setiap kunci from: tetap harus merupakan kunci yang dipublikasikan database — lihat adhoc-uses-socket untuk kontrak tersebut. Aggregate tidak pernah menyebutkan alamat, nomor port, atau penyedia cloud, dan file tersebut sama untuk ketiga build di bawah ini.

Apa yang disediakan operator

Setiap Release menyebutkan, di bawah infra.overrides, hal-hal yang sudah dijalankan operator dan dibaca oleh Recipes: grup subnet DB RDS dan grup keamanan basis data, serta kluster ECS, subnet dan grup keamanan tempat task dipasang, dan peran eksekusi yang digunakan ECS untuk menarik image dan menulis log. Image server adalah infra.image. Kedua Recipes server memerlukan image, kluster, subnet, grup keamanan, dan peran eksekusi, dan Recipe basis data Terraform memerlukan grup subnet: build yang kekurangan salah satunya akan berhenti dengan menyebutkan kuncinya, alih-alih memilihkan jaringan atau peran untuk Anda.

Setiap nilai tersebut adalah placeholder — 123456789012 adalah nomor akun yang digunakan dokumentasi AWS dalam contoh, dan example-cluster, example-private-db-subnets, ID subnet-… dan sg-…, peran tersebut, serta registry.example.com/orders-api:1.0.0 mewakili sumber daya di akun Anda sendiri. Build menerimanya karena build tidak pernah mencarinya; ganti nilai-nilai tersebut sebelum Anda melakukan plan atau deploy.

Recipes Terraform membaca kuncinya dalam ejaan terraform milik katalog (subnet_group, subnet_ids, vpc_security_groups, cluster, execution_role_arn); Recipes CloudFormation membacanya dengan nama properti sumber daya itu sendiri (DBSubnetGroupName, VPCSecurityGroups, Cluster, Subnets, SecurityGroups, ExecutionRoleArn), sehingga nilai operator yang sama dieja secara berbeda pada kedua target.

Membuat contoh

Anda dapat mem-build contoh ini dengan perintah di bawah, atau meminta asisten AI Anda mem-build-nya untuk Anda.

Tulis contoh ke folder baru yang dinamai sesuai contoh itu:

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

Kemudian ia mencetak perintah yang dijalankan berikutnya. Perintah pertama berpindah ke folder baru:

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

Build

Contoh ini menyertakan tiga rilis, jadi sebutkan rilis yang Anda inginkan. Satu rilis dibangun per eksekusi. Pada salinan yang baru, teruskan --auto-pull pada kali pertama setiap rilis dibangun, sehingga lockfile-nya terisi selama build. Build Terraform pertama mengambil modul RDS dari repositori git-nya, pada commit yang dicatat oleh pin milik Recipe itu sendiri:

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

Perintah ini mencetak keluaran berikut, dengan <workspace> mewakili folder contoh ini:

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

Setelah lockfile tersedia, perintah biasa melakukan build berdasarkan lockfile tersebut:

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

Dengan asisten AI

Asisten AI yang disiapkan dengan tool Aggrega dapat melakukan hal yang sama: tempelkan prompt ini ke asisten tersebut.

Gunakan hanya tool Aggrega, dan jangan membuat folder apa pun sendiri. Jika folder workspace belum berisi folder `aws-rds-and-ecs-service`, panggil tool `scaffold` sekali dengan `example` diatur ke `aws-rds-and-ecs-service` dan tanpa `dir`: tool itu menulis contoh ke folder baru `aws-rds-and-ecs-service`. Lalu panggil tool `build` dengan `workspace_root` diatur ke `aws-rds-and-ecs-service`, `release` diatur ke `release-terraform.yaml`, `auto_pull` diatur ke true, dan `write` diatur ke true. Beri tahu saya file mana saja yang ditulis build; file-file itu berada di bawah `aws-rds-and-ecs-service/dist/`.

Satu konfigurasi root Terraform

Konfigurasi root dari batas ini ditempatkan di dist/one-root/terraform/aggrega.modules.tf, dan berkas milik setiap komponen berada di direktori yang ditunjuk oleh blok module-nya: modul RDS yang di-vendor di bawah modules/db/, dan modul ECS milik server, yang disimpan di samping Recipe-nya dalam katalog, di bawah modules/api/. Seluruh konfigurasi root:

# 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"]
}

Argumen environment milik server membawa empat nilai yang diminta oleh edge. DB_HOST adalah ${module.db.db_instance_address}: Recipe basis data memublikasikan referensi ke output db_instance_address milik modul RDS melalui pemanggilan modul yang dideklarasikan oleh root yang sama ini sebagai module "db", sehingga Terraform mengevaluasinya di sini, pada saat plan dan apply, dan modul server menerima alamat instans sebagai input biasa. Tiga nilai lainnya adalah teks biasa yang sudah diketahui compiler sebelumnya — port yang dikonfigurasi oleh Release dan dua nama yang ditulis oleh Aggregate.

Hal ini berhasil karena Recipe server adalah Recipe source:: mapping-nya menjadi argumen blok module milik server, yang merupakan satu-satunya posisi yang dievaluasi Terraform dalam cakupan tempat modul tetangganya dideklarasikan — lihat Mengonsumsi nilai yang dipublikasikan komponen lain dan Contoh pasangan untuk mekanismenya, serta untuk apa yang salah ketika konsumen menulis referensi tersebut di tempat lain. Untuk alasan yang sama, lakukan plan pada direktori ini — direktori yang berisi aggrega.modules.tf — dan bukan pada salah satu direktori modul secara tersendiri.

Pada salinan sementara direktori tersebut, tofu init -backend=false memuat root dan modul yang di-vendor dari disk serta hanya mengunduh provider:

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]

lalu tofu validate mencetak:

Success! The configuration is valid.

Satu stack 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

Stack yang telah dirakit berada di dist/one-stack/cloudformation/cloudformation-stack.json, berisi tiga resource: Db, instance RDS; Api, layanan ECS; dan ApiTaskDefinition, task definition yang dijalankannya. Environment kontainer di 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 adalah sebuah Fn::GetAtt pada Endpoint.Address milik instance, terhadap logical ID Db yang diturunkan oleh Recipe database dari nama komponen db. CloudFormation me-resolve-nya saat membuat stack, dan karena task definition server membaca sebuah atribut dari Db, CloudFormation membuat instance tersebut terlebih dahulu. Lihat Referensi intra-stack.

Dua stack 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

Tidak ada yang berubah di aggregate.yaml. Release menempatkan basis data di boundary data dan server di boundary app, sehingga masing-masing dirakit menjadi stack tersendiri, dan edge dari server ke basis data melintas dari satu stack ke stack lainnya. Stack basis data, dist/two-stacks-data/cloudformation/cloudformation-stack.json, menerbitkan setiap entri yang dikonsumsi edge sebagai output dengan Export. Bagian Outputs-nya:

"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 juga diterbitkan, dan tidak membawa Export karena tidak ada edge yang membacanya. Stack server, dist/two-stacks-app/cloudformation/cloudformation-stack.json, membaca kembali masing-masing dari keempatnya dengan nama yang sama:

"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"}
}
],

Setiap nama export menggabungkan nama Release, direktori output boundary produsen, komponen, dan entri, sehingga nama tersebut sudah tetap pada waktu build dan konsumen dapat menyebutnya sebelum salah satu stack ada. Tidak satu pun Release di sini mendeklarasikan akun atau region, sehingga pembacaannya berupa Fn::ImportValue dalam akun yang sama. Cara nama tersebut dibentuk, dan kapan konsumen membaca lintas akun sebagai gantinya, dijelaskan dalam Pengkabelan lintas stack. Sebuah import hanya dapat diresolusi terhadap export yang sudah ada, sehingga stack basis data dibuat sebelum stack server; pengurutan kedua stack tersebut menjadi urusan operator, di luar build.

Kata sandi adalah milik RDS sendiri

Aggregate menyebutkan nama pengguna basis data dan tidak menyebutkan apa pun tentang kata sandinya, dan tidak ada Release yang melampirkan kredensial ke basis data. Pada kedua target, Recipe yang dipilih Manifest menyerahkan kata sandi kepada RDS: manage_master_user_password = true pada blok modul di atas, dan ManageMasterUserPassword pada instans di setiap stack. Properties basis data dalam templat satu stack:

"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 membuat kata sandi administrator ketika membuat instans dan menyimpannya di AWS Secrets Manager. Tidak ada masukan build yang membawa kata sandi, sehingga tidak satu pun dari ketiga build menuliskannya ke dalam file apa pun. Server menerima nama pengguna, bukan kata sandinya; pembacaan kata sandi dari Secrets Manager diserahkan kepada kode yang dijalankan oleh image server.

Cadangan adalah sebuah lampiran

RDS mencadangkan instans dengan sendirinya dan menyimpan setiap cadangan otomatis selama 7 hari jika tidak ada yang menyatakan lain. Setiap Release menyimpannya selama 14 hari dengan melampirkan core/backup ke basis data, pada entrinya untuk db:

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

Setiap Manifest mengikat Feature ke FeatureRecipe untuk targetnya, terraform/backup-native atau cloudformation/backup-native, dan keduanya tidak merender apa pun: cadangan adalah pengaturan instans, sehingga Recipe basis data membaca lampiran dan menulis masa retensi di tempat instans ditulis — backup_retention_period = 14 pada blok modul, dan "BackupRetentionPeriod": 14 dalam Properties instans di atas. Itulah sebabnya templat satu stack memuat tepat tiga sumber daya.

Membangun bukan berarti men-deploy

Setiap build menulis berkas di bawah dist/ lalu berhenti. Build tidak pernah menjalankan Terraform, OpenTofu, atau CloudFormation, tidak pernah melakukan autentikasi ke AWS, dan tidak mencari satu pun pengenal yang disebutkan oleh Releases. Membuat rencana dan menerapkan konfigurasi root, serta membuat stack, adalah langkah yang Anda lakukan pada keluaran, dengan kredensial Anda sendiri, setelah mengganti placeholder.

Input identik, output identik

Membangun dua kali dari input yang tidak berubah menghasilkan output yang identik byte demi byte, untuk masing-masing dari ketiga rilis. Compiler tidak me-resolve data live apa pun, sehingga build ulang tidak memiliki apa pun untuk ditemukan yang dapat mengubah byte tersebut. Itulah properti yang menjadi andalan tinjauan berbasis diff.

dist/, .aggrega/, dan file *.lock dihasilkan secara otomatis dan tidak di-commit; semuanya dibuat ulang dari file yang di-commit.