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

Uma base de dados gerida e o serviço que a lê, no Terraform e no CloudFormation

Um Aggregate contém uma base de dados PostgreSQL e o servidor que a lê. O mesmo Aggregate é compilado de três formas para a AWS: como uma única configuração raiz do Terraform, com a base de dados aprovisionada pelo módulo RDS publicado do projeto terraform-aws-modules e o servidor executado como um serviço do Amazon ECS no Fargate; como uma única stack do CloudFormation que contém ambos; e como duas stacks do CloudFormation, a base de dados numa e o servidor na outra.

Em cada destino, o servidor recebe o endereço da base de dados na forma que esse destino resolve por si: uma referência a uma saída de módulo na configuração raiz, um Fn::GetAtt dentro de uma única stack, um Fn::ImportValue entre duas. O compilador não avalia nenhuma delas. O endereço não existe até a instância ser criada, pelo que a compilação canaliza uma referência sem a resolver e o destino resolve-a quando faz a implementação.

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

Ficheiros

  • aggregate.yaml — intenção do programador: um componente db do tipo core/datastore/postgres com uma base de dados lógica orders pertencente à função 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 a base 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 a base 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 numa única fronteira, compilados através do Manifest do Terraform.
  • release-one-stack.yaml — ambos os componentes numa única fronteira, compilados através do Manifest do CloudFormation, pelo que ambos são montados numa única stack.
  • release-two-stacks.yaml — a mesma intenção dividida por duas fronteiras, pelo que a referência do servidor à base de dados atravessa um limite de stack.
  • .aggrega-config.yaml — nomeia o registo do hub a partir do qual o catálogo da biblioteca standard é resolvido.

Todas as entidades que este exemplo usa residem nesse catálogo. Nada é copiado para junto dos ficheiros de release.

O que o servidor pede

O servidor declara uma aresta, num socket a que chama database, e pede quatro das entradas que a base 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, pelo que database é um socket ad hoc: a aresta não traz nenhum seletor nem nenhuma allowlist de inject, e cada chave from: tem ainda assim de ser uma que a base de dados publica — veja-se adhoc-uses-socket para esse contrato. O Aggregate nunca nomeia um endereço, um número de porta ou um fornecedor de cloud, e é o mesmo ficheiro para as três compilações 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 base de dados do RDS e os grupos de segurança da base de dados, e o cluster do ECS, as sub-redes e os grupos de segurança a que as tarefas se ligam, e a função de execução com a qual o ECS obtém a imagem e escreve os registos. 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 da base de dados exige o grupo de sub-redes: uma compilação à qual falte um deles é interrompida, nomeando a chave, em vez de escolher uma rede ou uma função pelo utilizador.

Cada um desses valores é um marcador de posição — 123456789012 é o número de conta que a documentação da AWS usa nos 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 própria conta do utilizador. A compilação aceita-os porque nunca os consulta; devem ser substituídos antes de planear ou implementar.

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 leem-nas sob os nomes próprios das propriedades dos recursos (DBSubnetGroupName, VPCSecurityGroups, Cluster, Subnets, SecurityGroups, ExecutionRoleArn), pelo que os mesmos valores do operador são escritos de forma diferente nos dois destinos.

Gerar o exemplo

É possível compilar este exemplo com os comandos abaixo, ou pedir ao assistente de IA que o compile.

Escreva o exemplo numa nova pasta com o nome dele:

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

Depois, imprime os próximos comandos a executar. O primeiro entra na nova pasta:

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

Compilação

Este exemplo inclui três releases, pelo que é necessário nomear a pretendida. É compilada uma release por execução. Numa cópia nova, é necessário passar --auto-pull da primeira vez que cada release é compilada, para que o seu lockfile seja preenchido durante a compilação. A primeira compilação do Terraform obtém o módulo RDS a partir do seu repositório git, no commit que a fixação própria da Recipe regista:

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

Imprime, com <workspace> a representar 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

Assim que o lockfile existe, o comando simples compila 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-lhe este prompt.

Utilize apenas as ferramentas do Aggrega e não crie nenhuma pasta por si. Se a pasta do espaço de trabalho 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`: esta escreve o exemplo numa 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 que ficheiros a compilação escreveu; encontram-se 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 ficheiros próprios de cada componente ficam no diretório para o qual aponta o seu bloco module: 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 completa:

# 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 da base de dados publica uma referência à saída db_instance_address própria do módulo RDS através da chamada de módulo que esta mesma raiz declara como module "db", pelo que 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.

Isto funciona porque a Recipe do servidor é uma Recipe source:: o seu mapeamento torna-se os argumentos do bloco module do servidor, que é a única posição que o Terraform avalia num âmbito onde o módulo vizinho está declarado — veja-se Consumir o valor publicado de outro componente e Um par desenvolvido para a mecânica, e para o que corre mal quando um consumidor escreve a referência noutro sítio. Pela mesma razão, deve fazer-se o plan deste diretório — o que contém aggrega.modules.tf — e não de qualquer um dos diretórios de módulo isoladamente.

Numa cópia de trabalho desse diretório, tofu init -backend=false carrega a partir do disco a raiz e os módulos copiados localmente e obtém apenas os fornecedores:

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 imprime então:

Success! The configuration is valid.

Uma única 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

A stack montada 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 executa. O ambiente do contentor 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, relativo ao ID lógico Db que a Recipe da base de dados deriva do nome de componente db. O CloudFormation resolve-o quando cria a stack e, como a definição de tarefa do servidor lê um atributo de Db, cria primeiro a instância. Veja-se Referências dentro da stack.

Duas 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 a base de dados na fronteira data e o servidor na fronteira app, pelo que cada um é montado numa stack própria, e a aresta do servidor para a base de dados passa de uma stack para a outra. A stack da base 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ê. A stack do servidor, dist/two-stacks-app/cloudformation/cloudformation-stack.json, volta a ler 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, pelo que é fixado no momento da compilação e o consumidor pode nomeá-lo antes de qualquer uma das stacks existir. Nenhuma Release aqui declara uma conta ou uma região, pelo que a leitura é um Fn::ImportValue na mesma conta. A forma como o nome é construído, e quando o consumidor lê antes entre contas, é exposta em Ligação entre stacks. Um import só é resolvido contra um export que já existe, pelo que a stack da base de dados é criada antes da do servidor; ordenar as duas stacks cabe ao operador, fora da compilação.

A palavra-passe é do próprio RDS

O Aggregate nomeia o utilizador da base de dados e nada sobre a sua palavra-passe, e nenhuma Release anexa uma credencial à base de dados. Nos dois destinos, a Recipe que o Manifest seleciona entrega a palavra-passe ao RDS: manage_master_user_password = true no bloco de módulo acima, e ManageMasterUserPassword na instância em cada stack. As Properties da base de dados no modelo de uma única 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 palavra-passe de administrador quando cria a instância e guarda-a no AWS Secrets Manager. Nenhuma entrada da compilação traz uma palavra-passe, pelo que nenhuma das três compilações escreve uma em qualquer ficheiro. O servidor recebe o nome do utilizador e não a sua palavra-passe; ler a palavra-passe do Secrets Manager fica a cargo do código que a imagem do servidor executa.

A cópia de segurança é um anexo

O RDS faz a cópia de segurança da instância por si e mantém cada cópia de segurança automatizada durante 7 dias quando nada indica o contrário. Cada Release mantém-nas durante 14 ao anexar core/backup à base de dados, na sua entrada para db:

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

Cada Manifest vincula a Feature à FeatureRecipe do respetivo destino, terraform/backup-native ou cloudformation/backup-native, e nenhuma das duas renderiza nada: a cópia de segurança é uma definição da instância, pelo que a Recipe da base de dados lê o anexo 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 modelo de uma única stack contém exatamente três recursos.

Compilar não é implementar

Cada compilação escreve ficheiros em dist/ e termina. Nunca executa Terraform, OpenTofu ou CloudFormation, nunca se autentica na AWS e não consulta nenhum dos identificadores que as Releases nomeiam. Planear e aplicar a configuração raiz, e criar as stacks, são passos executados sobre a saída, com as próprias credenciais, depois de substituir os marcadores de posição.

Entrada idêntica, saída idêntica

Compilar 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, pelo que uma nova compilação não tem nada a descobrir que possa mover os bytes. Essa é a propriedade em que assenta uma revisão baseada em diffs.

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