Pular para o conteúdo
AggregaAggrega
Selecionar língua: Português (Brasil)
Esta página foi traduzida automaticamente. Leia o original em inglês.

Um banco de dados gerenciado e o serviço que o lê, no Terraform e no CloudFormation

Um Aggregate contém um banco de dados PostgreSQL e o servidor que o lê. O mesmo Aggregate é compilado de três formas para a AWS: como uma única configuração raiz do Terraform, com o banco de dados provisionado pelo módulo RDS publicado do projeto terraform-aws-modules e o servidor executado como um serviço do Amazon ECS no Fargate; como um único stack do CloudFormation contendo os dois; e como dois stacks do CloudFormation, o banco de dados em um e o servidor no outro.

Em cada destino, o servidor recebe o endereço do banco de dados na forma que esse destino resolve por conta própria: uma referência a uma saída de módulo na configuração raiz, um Fn::GetAtt dentro de um único stack, um Fn::ImportValue entre dois. O compilador não avalia nenhuma delas. O endereço não existe até que a instância seja criada, então o build canaliza uma referência sem resolvê-la e o destino a resolve quando faz a implantação.

Os blocos de saída desta página são copiados de uma execução real, conforme Lendo a saída nestas páginas.

Arquivos

  • aggregate.yaml — intenção do desenvolvedor: um componente db do tipo core/datastore/postgres com um banco de dados lógico orders pertencente ao papel orders_admin, e um componente api do tipo core/compute/server que o usa. Nenhuma chave ou valor nele diz respeito à AWS.
  • manifest-terraform.yaml — vincula o banco de dados à Recipe terraform/postgres-rds-terraform-aws-modules, o servidor a terraform/server-ecs e a Feature core/backup a terraform/backup-native.
  • manifest-cloudformation.yaml — vincula o banco de dados a cloudformation/postgres-rds, o servidor a cloudformation/server-ecs e a Feature core/backup a cloudformation/backup-native.
  • release-terraform.yaml — ambos os componentes em uma única fronteira, compilados por meio do Manifest do Terraform.
  • release-one-stack.yaml — ambos os componentes em uma única fronteira, compilados por meio do Manifest do CloudFormation, então ambos são montados em um único stack.
  • release-two-stacks.yaml — a mesma intenção dividida em duas fronteiras, então a referência do servidor ao banco de dados atravessa uma borda de stack.
  • .aggrega-config.yaml — nomeia o registro do hub a partir do qual o catálogo da biblioteca padrão é resolvido.

Todas as entidades que este exemplo usa ficam nesse catálogo. Nada é copiado ao lado dos arquivos de release.

O que o servidor pede

O servidor declara uma aresta, em um socket que ele chama de database, e pede quatro das entradas que o banco de dados publica, com os nomes de variáveis de ambiente que a sua própria configuração lê:

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 não declara nenhum socket próprio, então database é um socket ad hoc: a aresta não traz nenhum seletor nem nenhuma allowlist de inject, e cada chave from: ainda precisa ser uma que o banco de dados publica — veja adhoc-uses-socket para esse contrato. O Aggregate nunca nomeia um endereço, um número de porta ou um provedor de nuvem, e é o mesmo arquivo para os três builds abaixo.

O que o operador fornece

Cada Release nomeia, em infra.overrides, coisas que o operador já executa e que as Recipes leem: o grupo de sub-redes de banco de dados do RDS e os grupos de segurança do banco de dados, e o cluster do ECS, as sub-redes e os grupos de segurança aos quais as tarefas se conectam, e a função de execução com a qual o ECS baixa a imagem e escreve os logs. A imagem do servidor é infra.image. Ambas as Recipes do servidor exigem a imagem, o cluster, as sub-redes, os grupos de segurança e a função de execução, e a Recipe do Terraform do banco de dados exige o grupo de sub-redes: um build ao qual falte um deles é interrompido, nomeando a chave, em vez de escolher uma rede ou uma função por você.

Cada um desses valores é um placeholder — 123456789012 é o número de conta que a documentação da AWS usa em exemplos, e example-cluster, example-private-db-subnets, os IDs subnet-… e sg-…, a função e registry.example.com/orders-api:1.0.0 representam recursos da sua própria conta. O build os aceita porque nunca os consulta; substitua-os antes de planejar ou implantar.

As Recipes do Terraform leem as suas chaves na grafia terraform do catálogo (subnet_group, subnet_ids, vpc_security_groups, cluster, execution_role_arn); as Recipes do CloudFormation as leem sob os nomes próprios das propriedades dos recursos (DBSubnetGroupName, VPCSecurityGroups, Cluster, Subnets, SecurityGroups, ExecutionRoleArn), então os mesmos valores do operador são escritos de forma diferente nos dois destinos.

Gerar o exemplo

Você pode fazer o build deste exemplo com os comandos abaixo, ou pedir ao seu assistente de IA que faça o build por você.

Escreva o exemplo em uma nova pasta com o nome dele:

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

Em seguida ele imprime os próximos comandos a executar. O primeiro entra na pasta nova:

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

Build

Este exemplo traz três releases, então nomeie a que você quer. Uma release é compilada por execução. Em uma cópia recém-feita, passe --auto-pull na primeira vez que cada release for compilada, para que o seu lockfile seja preenchido durante o build. O primeiro build do Terraform obtém o módulo RDS do seu repositório git, no commit que a fixação própria da Recipe registra:

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

Ele imprime, com <workspace> representando a pasta deste exemplo:

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

Depois que o lockfile existe, o comando simples faz o build com base nele:

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

Com um assistente de IA

Um assistente de IA configurado com as ferramentas do Aggrega pode fazer o mesmo: cole este prompt nele.

Use apenas as ferramentas do Aggrega e não crie nenhuma pasta você mesmo. Se a pasta do workspace ainda não contiver uma pasta `aws-rds-and-ecs-service`, chame a ferramenta `scaffold` uma única vez com `example` definido como `aws-rds-and-ecs-service` e sem `dir`: ela escreve o exemplo em uma nova pasta `aws-rds-and-ecs-service`. Em seguida, chame a ferramenta `build` com `workspace_root` definido como `aws-rds-and-ecs-service`, `release` definido como `release-terraform.yaml`, `auto_pull` definido como true e `write` definido como true. Diga-me quais arquivos o build escreveu; eles ficam em `aws-rds-and-ecs-service/dist/`.

Uma única configuração raiz do Terraform

A configuração raiz da fronteira fica em dist/one-root/terraform/aggrega.modules.tf, e os arquivos próprios de cada componente ficam no diretório para o qual o seu bloco module aponta: o módulo RDS copiado localmente em modules/db/, e o módulo ECS do servidor, mantido ao lado da sua Recipe no catálogo, em modules/api/. A configuração raiz inteira:

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

O argumento environment do servidor traz os quatro valores que a aresta pediu. DB_HOST é ${module.db.db_instance_address}: a Recipe do banco de dados publica uma referência à saída db_instance_address própria do módulo RDS por meio da chamada de módulo que esta mesma raiz declara como module "db", então o Terraform a avalia aqui, no momento do plan e do apply, e o módulo do servidor recebe o endereço da instância como uma entrada comum. Os outros três são texto simples que o compilador conhecia antecipadamente — a porta que a Release configura e os dois nomes que o Aggregate escreveu.

Isso funciona porque a Recipe do servidor é uma Recipe source:: o seu mapeamento se torna os argumentos do bloco module do servidor, que é a única posição que o Terraform avalia em um escopo onde o módulo vizinho está declarado — veja Consumindo o valor publicado de outro componente e Um par detalhado para a mecânica, e para o que dá errado quando um consumidor escreve a referência em qualquer outro lugar. Pelo mesmo motivo, faça o plan deste diretório — o que contém aggrega.modules.tf — em vez de qualquer um dos diretórios de módulo isoladamente.

Em uma cópia de rascunho desse diretório, tofu init -backend=false carrega do disco a raiz e os módulos copiados localmente e obtém apenas os provedores:

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]

e tofu validate então imprime:

Success! The configuration is valid.

Um único stack do 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

O stack montado fica em dist/one-stack/cloudformation/cloudformation-stack.json, com três recursos: Db, a instância RDS; Api, o serviço do ECS; e ApiTaskDefinition, a definição de tarefa que ele executa. O ambiente do contêiner em 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 é um Fn::GetAtt sobre o Endpoint.Address da instância, contra o ID lógico Db que a Recipe do banco de dados deriva do nome de componente db. O CloudFormation o resolve quando cria o stack e, como a definição de tarefa do servidor lê um atributo de Db, cria a instância primeiro. Veja Referências dentro do stack.

Dois stacks do 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

Nada muda em aggregate.yaml. A Release coloca o banco de dados na fronteira data e o servidor na fronteira app, então cada um é montado em um stack próprio, e a aresta do servidor para o banco de dados cruza de um stack para o outro. O stack do banco de dados, dist/two-stacks-data/cloudformation/cloudformation-stack.json, publica cada entrada que a aresta consome como uma saída com um Export. Os seus 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 também é publicado, e não traz nenhum Export porque nenhuma aresta o lê. O stack do servidor, dist/two-stacks-app/cloudformation/cloudformation-stack.json, lê de volta cada uma das quatro pelo mesmo nome:

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

Cada nome de export junta o nome da Release, o diretório de saída da fronteira produtora, o componente e a entrada, então ele é fixado no momento do build e o consumidor pode nomeá-lo antes que qualquer um dos stacks exista. Nenhuma Release aqui declara uma conta ou uma região, então a leitura é um Fn::ImportValue na mesma conta. Como o nome é construído, e quando o consumidor lê entre contas em vez disso, é explicado em Ligação entre stacks. Um import só é resolvido contra um export que já existe, então o stack do banco de dados é criado antes do stack do servidor; ordenar os dois stacks cabe ao operador, fora do build.

A senha é do próprio RDS

O Aggregate nomeia o usuário do banco de dados e nada sobre a sua senha, e nenhuma Release vincula uma credencial ao banco de dados. Nos dois destinos, a Recipe que o Manifest seleciona entrega a senha ao RDS: manage_master_user_password = true no bloco de módulo acima, e ManageMasterUserPassword na instância em cada stack. As Properties do banco de dados no template de um único 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"
]
},

O RDS gera a senha de administrador quando cria a instância e a guarda no AWS Secrets Manager. Nenhuma entrada do build traz uma senha, então nenhum dos três builds escreve uma em qualquer arquivo. O servidor recebe o nome do usuário e não a sua senha; ler a senha do Secrets Manager fica a cargo do código que a imagem do servidor executa.

O backup é uma vinculação

O RDS faz o backup da instância por conta própria e mantém cada backup automatizado por 7 dias quando nada diz o contrário. Cada Release os mantém por 14 vinculando core/backup ao banco de dados, na sua entrada para db:

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

Cada Manifest vincula a Feature à FeatureRecipe do seu destino, terraform/backup-native ou cloudformation/backup-native, e nenhuma das duas renderiza nada: o backup é uma configuração da instância, então a Recipe do banco de dados lê a vinculação e escreve a retenção onde a instância é escrita — backup_retention_period = 14 no bloco de módulo, e "BackupRetentionPeriod": 14 nas Properties da instância acima. É por isso que o template de um único stack contém exatamente três recursos.

Fazer o build não é implantar

Cada build escreve arquivos em dist/ e para. Ele nunca executa Terraform, OpenTofu ou CloudFormation, nunca se autentica na AWS e não consulta nenhum dos identificadores que as Releases nomeiam. Planejar e aplicar a configuração raiz, e criar os stacks, são etapas que você executa sobre a saída, com as suas próprias credenciais, depois de substituir os placeholders.

Entrada idêntica, saída idêntica

Fazer o build duas vezes a partir de entradas inalteradas produz uma saída idêntica byte a byte, para cada uma das três releases. O compilador não resolve nenhum dado em tempo real, então um novo build não tem nada a descobrir que possa mover os bytes. Essa é a propriedade em que uma revisão baseada em diffs se apoia.

dist/, .aggrega/ e os arquivos *.lock são gerados e não entram em commits; eles são regenerados a partir dos arquivos que entram.