관리형 데이터베이스와 이를 읽는 서비스, Terraform과 CloudFormation에서
하나의 Aggregate에 PostgreSQL 데이터베이스와 이를 읽는 서버가 들어 있습니다. 같은 Aggregate를 AWS를 대상으로 세 가지 방식으로 빌드합니다. 하나의 Terraform 루트 구성으로 빌드하는 방식에서는 terraform-aws-modules 프로젝트가 공개한 RDS 모듈로 데이터베이스를 프로비저닝하고 서버를 Fargate 위의 Amazon ECS 서비스로 실행합니다. 둘을 모두 담은 하나의 CloudFormation 스택으로 빌드하는 방식도 있고, 데이터베이스와 서버를 각각 다른 스택에 둔 두 개의 CloudFormation 스택으로 빌드하는 방식도 있습니다.
각 대상에서 서버는 데이터베이스의 주소를 그 대상이 스스로 해석하는 형태로
받습니다. 루트 구성에서는 모듈 출력 참조로, 하나의 스택 안에서는 Fn::GetAtt로, 두 스택 사이에서는 Fn::ImportValue로 받습니다.
컴파일러는 이 중 어느 것도 평가하지 않습니다. 주소는 인스턴스가
생성되기 전에는 존재하지 않으므로, 빌드는 참조를 그대로 전달하고 대상이 배포할 때
이를 해석합니다.
이 페이지의 출력 블록은 이 페이지의 출력 읽기에 따라 실제 실행에서 복사한 것입니다.
파일
aggregate.yaml— 개발자 의도: 역할orders_admin이 소유한 논리 데이터베이스orders를 가진core/datastore/postgres유형의db컴포넌트와, 이를 사용하는core/compute/server유형의api컴포넌트입니다. 이 파일의 어떤 키나 값도 AWS에 관한 것이 아닙니다.manifest-terraform.yaml— 데이터베이스를 Recipeterraform/postgres-rds-terraform-aws-modules에, 서버를terraform/server-ecs에,core/backupFeature를terraform/backup-native에 바인딩합니다.manifest-cloudformation.yaml— 데이터베이스를cloudformation/postgres-rds에, 서버를cloudformation/server-ecs에,core/backupFeature를cloudformation/backup-native에 바인딩합니다.release-terraform.yaml— 두 컴포넌트를 하나의 경계에 두고, Terraform Manifest를 통해 빌드합니다.release-one-stack.yaml— 두 컴포넌트를 하나의 경계에 두고 CloudFormation Manifest를 통해 빌드하므로, 둘 다 하나의 스택으로 조립됩니다.release-two-stacks.yaml— 같은 의도를 두 경계로 나누므로, 데이터베이스에 대한 서버의 참조가 스택 경계를 넘습니다..aggrega-config.yaml— 표준 라이브러리 카탈로그를 해석해 오는 hub 레지스트리를 지정합니다.
이 예제가 사용하는 엔티티는 모두 그 카탈로그에 있습니다. release 파일 옆에 복사해 둔 것은 없습니다.
서버가 요청하는 것
서버는 database라는 이름을 붙인 소켓에 하나의 엣지를 선언하고, 데이터베이스가 게시하는 항목 중 네 개를 자체 구성이 읽는 환경 변수
이름으로 요청합니다:
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: databasecore/compute/server는 자체 소켓을 선언하지 않으므로 database는 임시(ad-hoc) 소켓입니다. 엣지에는 셀렉터도 inject 허용 목록도 없으며,
각 from: 키는 여전히 데이터베이스가 게시하는 키여야 합니다. 이 계약에 대해서는
adhoc-uses-socket을 참조하십시오. Aggregate는
주소, 포트 번호, 클라우드 공급자를 전혀 명시하지 않으며, 아래의 세 가지 빌드 모두에 대해 같은
파일입니다.
운영자가 제공하는 것
각 Release는 infra.overrides 아래에 운영자가 이미 운영하고 있으며 Recipes가 읽는 것들을 지정합니다. 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)으로 키를 읽습니다. 따라서 같은 운영자 값이라도 두 대상에서 표기가 다릅니다.
예제 생성하기
아래 명령으로 이 예제를 빌드하거나, AI 어시스턴트에게 대신 빌드하게 할 수 있습니다.
예제 이름을 딴 새 폴더에 예제를 씁니다:
aggrega scaffold --example aws-rds-and-ecs-service그런 다음 이어서 실행할 명령을 출력합니다. 첫 번째 명령은 새 폴더로 이동합니다:
cd aws-rds-and-ecs-service빌드
이 예제에는 세 개의 release가 포함되어 있으므로 원하는 release를 지정하십시오. 한 번 실행할 때 하나의 release가 빌드됩니다. 새 복사본에서는 각 release를 처음 빌드할 때 --auto-pull을 전달하여 빌드 중에 lockfile이 채워지도록 하십시오. 첫 번째 Terraform 빌드는 Recipe 자체의 pin이 기록한 commit에서 RDS 모듈을 git 저장소로부터 가져옵니다.
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.4sBuild completed: 151 files written to <workspace>/distlockfile이 생성된 후에는 일반 명령으로 해당 lockfile에 따라 빌드합니다.
aggrega build --release release-terraform.yamlTotal build time: 5.7sBuild completed: 151 files written to <workspace>/distAI 어시스턴트 사용
Aggrega 도구로 설정한 AI 어시스턴트도 같은 작업을 할 수 있습니다. 다음 프롬프트를 붙여 넣으십시오.
Aggrega 도구만 사용하고 폴더를 직접 만들지 마십시오. 워크스페이스 폴더에 아직 `aws-rds-and-ecs-service` 폴더가 없으면 `example`에 `aws-rds-and-ecs-service`를 지정하고 `dir` 없이 `scaffold` 도구를 한 번 호출하십시오. 그러면 예제가 새 `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/` 아래에 있습니다.하나의 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 인수는 엣지가 요청한 네 가지 값을 전달합니다.
DB_HOST는 ${module.db.db_instance_address}입니다. 데이터베이스 Recipe는
이 루트가 module "db"로 선언하는 모듈 호출을 통해 RDS 모듈 자체의 db_instance_address 출력에 대한
참조를 게시하므로, Terraform은 이를 이곳에서 plan 및 apply 시점에 평가하고,
서버의 모듈은 인스턴스의 주소를 일반 입력으로 받습니다. 나머지 세 값은
컴파일러가 미리 알고 있던 일반 텍스트로, Release가 구성하는 포트와 Aggregate가
작성한 두 이름입니다.
이것이 동작하는 이유는 서버의 Recipe가 source: Recipe이기 때문입니다. 그 매핑은
서버의 module 블록의 인수가 되며, 이 위치는 Terraform이 이웃 모듈이 선언된
스코프에서 평가하는 유일한 위치입니다. 동작 방식과, 소비자가 참조를 다른 곳에
작성할 때 무엇이 잘못되는지는
다른 컴포넌트의 게시된 값 소비하기
및 작동하는 한 쌍의 예를 참조하십시오.
같은 이유로, 어느 한 모듈 디렉터리만 따로 plan하지 말고 이 디렉터리, 즉
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.하나의 CloudFormation 스택
aggrega build --release release-one-stack.yaml --auto-pullPull complete: release-one-stack.lock (entities=11, source_artifacts=0, external_inputs=0)Total build time: 6.2sBuild completed: 1 file written to <workspace>/dist조립된 스택은
dist/one-stack/cloudformation/cloudformation-stack.json에 생성되며, 세 개의 리소스를 담고 있습니다. 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는 데이터베이스 Recipe가 컴포넌트 이름 db에서 도출한 논리 ID Db를 대상으로, 인스턴스의 Endpoint.Address에 대한 Fn::GetAtt입니다.
CloudFormation은 스택을 생성할 때 이를 해석하며, 서버의 태스크 정의가 Db의 속성을 읽으므로 인스턴스를 먼저 생성합니다.
스택 내 참조를 참고하십시오.
두 개의 CloudFormation 스택
aggrega build --release release-two-stacks.yaml --auto-pullPull complete: release-two-stacks.lock (entities=11, source_artifacts=0, external_inputs=0)Total build time: 6.2sBuild completed: 2 files written to <workspace>/distaggregate.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은
네 항목을 각각 같은 이름으로 다시 읽습니다.
"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"} } ],각 export 이름은 Release 이름, 생산자 경계의 출력
디렉터리, component, 항목을 결합한 것이므로 빌드 시점에 고정되며,
소비자는 두 스택이 존재하기 전에 이를 지정할 수 있습니다. 여기서는 어느 Release도
계정이나 리전을 선언하지 않으므로, 읽기는 같은 계정 내의 Fn::ImportValue입니다.
이름이 만들어지는 방식과 소비자가 대신 계정을 넘어 읽는 경우는
스택 간 연결에 설명되어 있습니다.
import는 이미 존재하는 export에 대해서만 해석되므로,
데이터베이스의 스택이 서버의 스택보다 먼저 생성됩니다. 두 스택의 순서를 정하는 것은
빌드 밖에서 운영자가 맡습니다.
비밀번호는 RDS가 관리합니다
Aggregate는 데이터베이스의 사용자를 지정할 뿐 비밀번호에 대해서는 아무것도 지정하지 않으며, 어떤 Release도 데이터베이스에 자격 증명을 연결하지 않습니다. 두 대상 모두에서 Manifest가 선택하는 Recipe는 비밀번호를 RDS에 맡깁니다. 위의 모듈 블록에서는 manage_master_user_password = true로, 각 스택의 인스턴스에서는 ManageMasterUserPassword로 지정합니다. 단일 스택 템플릿에 있는 데이터베이스의 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에 보관합니다. 어떤 빌드 입력도 비밀번호를 담고 있지 않으므로, 세 빌드 중 어느 것도 비밀번호를 파일에 기록하지 않습니다. 서버는 사용자 이름을 받을 뿐 비밀번호는 받지 않습니다. Secrets Manager에서 비밀번호를 읽는 일은 서버 이미지가 실행하는 코드에 맡겨집니다.
백업은 attachment입니다
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가 attachment를 읽고 인스턴스가 기록되는 곳에 보존 기간을 기록합니다. 모듈 블록의 backup_retention_period = 14, 그리고 위 인스턴스의 Properties에 있는 "BackupRetentionPeriod": 14입니다. 단일 스택 템플릿이 정확히 세 개의 리소스를 담는 이유가 이것입니다.
빌드는 배포가 아닙니다
각 빌드는 dist/ 아래에 파일을 쓰고 멈춥니다. Terraform, OpenTofu 또는 CloudFormation을 실행하지 않고, AWS에 인증하지 않으며, Releases가 지정하는 식별자를 하나도 조회하지 않습니다. 루트 구성을 plan하고 apply하는 일과 스택을 생성하는 일은 자리 표시자를 바꾼 뒤 직접 자신의 자격 증명으로 출력물에 대해 수행하는 단계입니다.
동일한 입력, 동일한 출력
변경되지 않은 입력으로 두 번 빌드하면 세 릴리스 각각에 대해 바이트 단위로 동일한 출력이 생성됩니다. 컴파일러는 실시간 데이터를 조회하지 않으므로, 다시 빌드해도 바이트를 바꿀 만한 새로운 정보를 발견할 여지가 없습니다. 이것이 diff 기반 검토가 의존하는 속성입니다.
dist/, .aggrega/ 및 *.lock 파일은 생성되는 파일이며 커밋하지 않습니다.
이 파일들은 커밋된 파일로부터 다시 생성됩니다.