Bỏ qua để đến nội dung
AggregaAggrega
Chọn ngôn ngữ: Tiếng Việt
Trang này được dịch bằng máy. Đọc bản gốc tiếng Anh.

Một cơ sở dữ liệu được quản lý và dịch vụ đọc nó, trên Terraform và CloudFormation

Một Aggregate chứa một cơ sở dữ liệu PostgreSQL và máy chủ đọc nó. Cùng một Aggregate được build theo ba cách trên AWS: thành một cấu hình gốc Terraform, với cơ sở dữ liệu được cấp phát bởi module RDS đã phát hành của dự án terraform-aws-modules và máy chủ chạy dưới dạng một dịch vụ Amazon ECS trên Fargate; thành một stack CloudFormation chứa cả hai; và thành hai stack CloudFormation, cơ sở dữ liệu ở một stack và máy chủ ở stack còn lại.

Trên mỗi đích, máy chủ nhận địa chỉ của cơ sở dữ liệu dưới dạng mà chính đích đó tự phân giải: một tham chiếu đến output của module trong cấu hình gốc, một Fn::GetAtt bên trong một stack, một Fn::ImportValue xuyên qua hai stack. Trình biên dịch không đánh giá cái nào trong số đó. Địa chỉ chưa tồn tại cho đến khi instance được tạo, nên quá trình build chuyển tiếp một tham chiếu và đích sẽ phân giải nó khi triển khai.

Các khối output trên trang này được sao chép từ một lần chạy thật, theo Đọc output trên các trang này.

Các tệp

  • aggregate.yaml — ý định của nhà phát triển: một component db thuộc kiểu core/datastore/postgres với cơ sở dữ liệu logic orders do vai trò orders_admin sở hữu, và một component api thuộc kiểu core/compute/server sử dụng nó. Không có khóa hay giá trị nào trong tệp này liên quan đến AWS.
  • manifest-terraform.yaml — gắn cơ sở dữ liệu với Recipe terraform/postgres-rds-terraform-aws-modules, máy chủ với terraform/server-ecs, và Feature core/backup với terraform/backup-native.
  • manifest-cloudformation.yaml — gắn cơ sở dữ liệu với cloudformation/postgres-rds, máy chủ với cloudformation/server-ecs, và Feature core/backup với cloudformation/backup-native.
  • release-terraform.yaml — cả hai component trong một ranh giới, được build qua Manifest Terraform.
  • release-one-stack.yaml — cả hai component trong một ranh giới, được build qua Manifest CloudFormation, nên cả hai được ghép thành một stack duy nhất.
  • release-two-stacks.yaml — cùng ý định đó được chia qua hai ranh giới, nên tham chiếu của máy chủ tới cơ sở dữ liệu vượt qua một cạnh stack.
  • .aggrega-config.yaml — chỉ định hub registry mà catalog thư viện chuẩn được phân giải từ đó.

Tất cả các thực thể mà ví dụ này dùng đều nằm trong catalog đó. Không có gì được sao chép vào bên cạnh các tệp release.

Máy chủ yêu cầu những gì

Máy chủ khai báo một cạnh, trên một socket mà nó đặt tên là database, và yêu cầu bốn trong số các mục mà cơ sở dữ liệu công bố, dưới các tên biến môi trường mà cấu hình của chính nó đọc:

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 không khai báo socket nào của riêng nó, nên database là một socket ad-hoc: cạnh này không mang selector nào và không có danh sách cho phép inject nào, và mỗi khóa from: vẫn phải là một khóa mà cơ sở dữ liệu công bố — xem adhoc-uses-socket để biết về hợp đồng đó. Aggregate không bao giờ nêu tên một địa chỉ, một số cổng hay một nhà cung cấp đám mây, và nó là cùng một tệp cho cả ba bản dựng bên dưới.

Những gì người vận hành cung cấp

Mỗi Release nêu tên, dưới infra.overrides, những thứ người vận hành đã chạy sẵn và các Recipes đọc: nhóm subnet DB của RDS và các nhóm bảo mật của cơ sở dữ liệu, cùng với cụm ECS, các subnet và nhóm bảo mật mà các tác vụ gắn vào, và vai trò thực thi mà ECS dùng để kéo image và ghi log. Image của máy chủ là infra.image. Cả hai Recipes của máy chủ đều yêu cầu image, cụm, các subnet, các nhóm bảo mật và vai trò thực thi, còn Recipe cơ sở dữ liệu Terraform yêu cầu nhóm subnet: một bản build thiếu một trong số đó sẽ dừng lại, nêu tên khóa, thay vì tự chọn một mạng hay một vai trò cho bạn.

Mọi giá trị trong số đó đều là giá trị giữ chỗ — 123456789012 là số tài khoản mà tài liệu AWS dùng trong các ví dụ, còn example-cluster, example-private-db-subnets, các ID subnet-… và sg-…, vai trò và registry.example.com/orders-api:1.0.0 đại diện cho các tài nguyên trong tài khoản của chính bạn. Bản build chấp nhận chúng vì nó không bao giờ tra cứu chúng; hãy thay thế chúng trước khi bạn plan hoặc triển khai.

Các Recipes Terraform đọc các khóa của chúng theo cách viết terraform của catalog (subnet_group, subnet_ids, vpc_security_groups, cluster, execution_role_arn); các Recipes CloudFormation đọc chúng dưới chính tên các thuộc tính tài nguyên (DBSubnetGroupName, VPCSecurityGroups, Cluster, Subnets, SecurityGroups, ExecutionRoleArn), vì vậy cùng các giá trị của người vận hành được viết khác nhau trên hai đích.

Tạo ví dụ

Bạn có thể build ví dụ này bằng các lệnh bên dưới, hoặc để trợ lý AI của bạn build giúp bạn.

Ghi ví dụ vào một thư mục mới đặt theo tên của nó:

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

Sau đó nó in ra các lệnh cần chạy tiếp theo. Lệnh đầu tiên chuyển vào thư mục mới:

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

Build

Ví dụ này đi kèm ba release, vì vậy hãy chỉ định release bạn muốn. Mỗi lần chạy chỉ build một release. Trong một bản sao mới, hãy truyền --auto-pull trong lần đầu tiên mỗi release được build, để lockfile của nó được điền trong quá trình build. Lần build Terraform đầu tiên sẽ tải module RDS từ kho git của nó, tại commit mà pin riêng của Recipe ghi lại:

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

Lệnh in ra, với <workspace> đại diện cho thư mục của ví dụ này:

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

Khi lockfile đã tồn tại, lệnh thông thường sẽ build dựa trên nó:

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

Với trợ lý AI

Một trợ lý AI được thiết lập với các công cụ của Aggrega cũng có thể làm như vậy: hãy dán prompt này vào trợ lý.

Chỉ dùng các công cụ của Aggrega và không tự tạo thư mục nào. Nếu thư mục workspace chưa có thư mục `aws-rds-and-ecs-service`, hãy gọi công cụ `scaffold` một lần với `example` đặt thành `aws-rds-and-ecs-service` và không có `dir`: công cụ này ghi ví dụ vào một thư mục `aws-rds-and-ecs-service` mới. Sau đó gọi công cụ `build` với `workspace_root` đặt thành `aws-rds-and-ecs-service`, `release` đặt thành `release-terraform.yaml`, `auto_pull` đặt thành true và `write` đặt thành true. Hãy cho tôi biết bản build đã ghi những tệp nào; chúng nằm trong `aws-rds-and-ecs-service/dist/`.

Một cấu hình gốc Terraform

Cấu hình gốc của ranh giới được đặt tại dist/one-root/terraform/aggrega.modules.tf, và các tệp riêng của mỗi component nằm trong thư mục mà khối module của nó trỏ tới: module RDS được vendor nằm dưới modules/db/, và module ECS của server, được giữ cạnh Recipe của nó trong catalog, nằm dưới modules/api/. Toàn bộ cấu hình gốc:

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

Đối số environment của server mang bốn giá trị mà edge đã yêu cầu. DB_HOST là ${module.db.db_instance_address}: Recipe của cơ sở dữ liệu công bố một tham chiếu tới output db_instance_address của chính module RDS thông qua lời gọi module mà chính cấu hình gốc này khai báo là module "db", nên Terraform đánh giá nó tại đây, vào lúc plan và apply, và module của server nhận địa chỉ của instance như một input thông thường. Ba giá trị còn lại là văn bản thuần mà trình biên dịch đã biết trước — cổng mà Release cấu hình và hai tên mà Aggregate đã viết.

Điều này hoạt động vì Recipe của server là một Recipe source:: ánh xạ của nó trở thành các đối số của khối module của server, đây là vị trí duy nhất mà Terraform đánh giá trong một phạm vi có khai báo module của thành phần lân cận — xem Consuming another component’s published value và A worked pair để hiểu cơ chế, và để biết điều gì xảy ra khi một bên tiêu thụ viết tham chiếu ở bất kỳ chỗ nào khác. Cũng vì lý do đó, hãy plan thư mục này — thư mục chứa aggrega.modules.tf — thay vì riêng một trong hai thư mục module.

Trên một bản sao nháp của thư mục đó, tofu init -backend=false tải cấu hình gốc và các module được vendor từ đĩa và chỉ tải về các 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]

và sau đó tofu validate in ra:

Success! The configuration is valid.

Một 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 đã lắp ráp nằm tại dist/one-stack/cloudformation/cloudformation-stack.json, chứa ba tài nguyên: Db, phiên bản RDS; Api, dịch vụ ECS; và ApiTaskDefinition, định nghĩa tác vụ mà dịch vụ đó chạy. Môi trường của container trong 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 là một Fn::GetAtt trên Endpoint.Address của phiên bản, đối với logical ID Db mà Recipe cơ sở dữ liệu suy ra từ tên component db. CloudFormation phân giải nó khi tạo stack, và vì định nghĩa tác vụ của máy chủ đọc một thuộc tính của Db, CloudFormation tạo phiên bản trước. Xem Tham chiếu trong cùng stack.

Hai 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

Không có gì trong aggregate.yaml thay đổi. Release đặt cơ sở dữ liệu vào ranh giới data và máy chủ vào ranh giới app, nên mỗi bên được lắp ráp thành một stack riêng, và cạnh từ máy chủ đến cơ sở dữ liệu đi từ stack này sang stack kia. Stack của cơ sở dữ liệu, dist/two-stacks-data/cloudformation/cloudformation-stack.json, công bố mỗi mục mà cạnh tiêu thụ dưới dạng một output có Export. Phần Outputs của nó:

"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 cũng được công bố, và không mang Export vì không có cạnh nào đọc nó. Stack của máy chủ, dist/two-stacks-app/cloudformation/cloudformation-stack.json, đọc lại từng mục trong bốn mục đó theo cùng tên:

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

Mỗi tên export ghép tên Release, thư mục đầu ra của ranh giới bên sản xuất, component và mục, nên nó được cố định tại thời điểm build và bên tiêu thụ có thể gọi tên nó trước khi stack nào tồn tại. Không Release nào ở đây khai báo tài khoản hay vùng, nên việc đọc là một Fn::ImportValue trong cùng tài khoản. Cách tên được tạo, và khi nào bên tiêu thụ đọc xuyên tài khoản thay vào đó, được trình bày trong Kết nối giữa các stack. Một import chỉ được phân giải dựa trên một export đã tồn tại, nên stack của cơ sở dữ liệu được tạo trước stack của máy chủ; việc sắp thứ tự hai stack là việc của người vận hành, nằm ngoài quá trình build.

Mật khẩu thuộc về chính RDS

Aggregate đặt tên người dùng của cơ sở dữ liệu và không nói gì về mật khẩu của nó, và không Release nào gắn thông tin xác thực vào cơ sở dữ liệu. Trên cả hai đích, Recipe mà Manifest chọn giao mật khẩu cho RDS: manage_master_user_password = true trên khối module ở trên, và ManageMasterUserPassword trên instance trong mỗi stack. Properties của cơ sở dữ liệu trong template một 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 tạo mật khẩu quản trị viên khi tạo instance và lưu nó trong AWS Secrets Manager. Không đầu vào build nào mang mật khẩu, nên không bản build nào trong ba bản ghi mật khẩu vào bất kỳ tệp nào. Server nhận tên người dùng chứ không nhận mật khẩu; việc đọc mật khẩu từ Secrets Manager được để lại cho mã mà image của server chạy.

Bản sao lưu là một attachment

RDS tự sao lưu instance và giữ mỗi bản sao lưu tự động trong 7 ngày khi không có gì quy định khác. Mỗi Release giữ chúng trong 14 ngày bằng cách gắn core/backup vào cơ sở dữ liệu, trên mục của nó cho db:

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

Mỗi Manifest gắn Feature với FeatureRecipe cho đích của nó, terraform/backup-native hoặc cloudformation/backup-native, và không cái nào render gì cả: bản sao lưu là một thiết lập của instance, nên Recipe cơ sở dữ liệu đọc attachment và ghi thời hạn lưu giữ vào nơi instance được ghi — backup_retention_period = 14 trên khối module, và "BackupRetentionPeriod": 14 trong Properties của instance ở trên. Đó là lý do template một stack chứa đúng ba tài nguyên.

Build không phải là triển khai

Mỗi lần build ghi các tệp vào dist/ rồi dừng. Nó không bao giờ chạy Terraform, OpenTofu hay CloudFormation, không bao giờ xác thực với AWS, và không tra cứu bất kỳ định danh nào mà các Releases nêu tên. Việc lập kế hoạch và áp dụng cấu hình gốc, cũng như tạo các stack, là những bước bạn thực hiện trên đầu ra, bằng thông tin xác thực của riêng bạn, sau khi thay thế các placeholder.

Đầu vào giống hệt, đầu ra giống hệt

Build hai lần từ các đầu vào không thay đổi sẽ tạo ra đầu ra giống hệt nhau đến từng byte, cho mỗi bản phát hành trong ba bản phát hành. Trình biên dịch không phân giải dữ liệu trực tiếp nào, nên một lần build lại không có gì để phát hiện có thể làm thay đổi các byte. Đó là thuộc tính mà việc review dựa trên diff dựa vào.

dist/, .aggrega/ và các tệp *.lock được sinh ra và không được commit; chúng được sinh lại từ các tệp được commit.