Stack do CloudFormation com vinculações
Um banco de dados gerenciado e a aplicação que o lê, escritos uma única vez como intenção do desenvolvedor e montados em templates de stacks do AWS CloudFormation. Duas vinculações trazem recursos próprios — um alarme no banco de dados e um parâmetro de configurações compartilhadas na fronteira —, então este exemplo mostra onde os recursos de uma vinculação ficam no stack montado e como são nomeados ao lado dos do componente.
A mesma intenção do desenvolvedor é compilada de três maneiras: como um stack, como dois stacks com uma referência que cruza entre eles, e — deliberadamente — como um build que é interrompido.
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 banco de dadospayments-dbdo tipocore/datastore/mariadbe umreporting-appdo tipoexample/compute/db-readerque declara que usa o banco de dados. Nada sobre a AWS fica aqui. O blocofeatures:do banco de dados trazstorage-headroom, que vinculaexample/storage-alarm.release-one-stack.yaml— ambos os componentes em uma única fronteira, então ambos são montados em um único stack. Vinculacore/shared-configa toda a fronteira.release-two-stacks.yaml— a mesma intenção dividida em duas fronteiras, então a referência da aplicação ao banco de dados atravessa uma borda de stack.release-negative-name-collision.yamlcomaggregate-name-collision.yaml— feita para falhar. Vincula o alarme duas vezes a um mesmo componente.manifest.yaml— vincula cada tipo de componente e cada Feature vinculada à Recipe que o implementa neste destino..aggrega-config.yaml— nomeia o registro do hub a partir do qual as entidades do catálogo são resolvidas.
Toda release vincula o slot root_password do banco de dados na sua entrada para payments-db, com core/generated-secret. Neste destino, o RDS é dono da senha de administrador, e a Recipe de banco de dados que o Manifest escolhe traz a diretiva que diz isso; isso torna o vínculo uma decisão do operador, escrita na Release, e o Aggregate não diz nada sobre ele.
Toda release também vincula core/backup a payments-db, com infra.retention_days: 14, e o Manifest a vincula a cloudformation/backup-native. O RDS mantém os backups automatizados da instância por 7 dias quando nada diz o contrário; esta vinculação mantém cada um por 14. A FeatureRecipe não renderiza nada: o backup é uma configuração da instância, então a Recipe do banco de dados lê a vinculação e escreve "BackupRetentionPeriod": 14 nas Properties da própria instância.
Todas as entidades que este exemplo usa ficam no catálogo publicado. Nada é copiado ao lado dos arquivos de release, então o exemplo é resolvido contra o catálogo como ele está, e não contra um snapshot privado dele.
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:
aggrega scaffold --example cloudformation-rds-stackEm seguida ele imprime os próximos comandos a executar. O primeiro entra na pasta nova:
cd cloudformation-rds-stackBuild
Este exemplo traz três releases, então nomeie a que você quer. Uma release é compilada por execução. O primeiro build de cada release precisa do seu lockfile, que o comando pull escreve:
aggrega pull --release release-one-stack.yamlaggrega build --release release-one-stack.yamlO build imprime, com <workspace> representando a pasta deste exemplo:
Total build time: 4.1sBuild completed: 1 file written to <workspace>/distO stack montado fica em dist/one-stack/cloudformation/cloudformation-stack.json. Cada componente e cada vinculação que renderiza para esse diretório contribui para esse único template — o provedor emite um único stack em JSON puro em vez de um arquivo por contribuidor.
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 por conta própria. Se a pasta do workspace ainda não contiver uma pasta `cloudformation-rds-stack`, chame a ferramenta `scaffold` uma vez com `example` definido como `cloudformation-rds-stack` e sem `dir`: ela escreve o exemplo em uma nova pasta `cloudformation-rds-stack`. Depois chame a ferramenta `build` com `workspace_root` definido como `cloudformation-rds-stack`, `release` definido como `release-one-stack.yaml`, `auto_pull` definido como true e `write` definido como true. Diga-me quais arquivos o build escreveu; eles ficam em `cloudformation-rds-stack/dist/`.O que chega ao stack, e quem o forneceu
O build de um único stack monta quatro recursos de quatro contribuidores diferentes:
| Recurso | Fornecido por |
|---|---|
PaymentsDb | a própria Recipe do componente de banco de dados |
PaymentsDbStorageHeadroom | a vinculação storage-headroom nesse componente |
AppSharedConfig | a vinculação shared-settings na fronteira |
ReportingApp | a própria Recipe do componente de aplicação |
A vinculação backup em payments-db não está na tabela porque não fornece nenhum recurso próprio: o que ela define vai parar dentro de PaymentsDb.
Cada recurso traz um bloco de proveniência que nomeia o contribuidor de onde veio, então as duas metades continuam distinguíveis dentro de um stack para o qual ambas contribuíram:
"PaymentsDbStorageHeadroom": { "Metadata": { "aggrega.ai/provenance": { "aggrega.ai/aggregate-name": "aggregate", "aggrega.ai/boundary-path": "app", [… omitted: a compiler-version entry, which moves with the build] "aggrega.ai/component-id": "cfr--payments-db--storage-headroom", "aggrega.ai/environment": "production", "aggrega.ai/provider": "cloudformation", [… omitted: a provider-version entry, which moves with the build] "aggrega.ai/recipe-uri": "storage-alarm:1.0.0" } }, [… omitted: the alarm's Properties, printed in full just below] "Type": "AWS::CloudWatch::Alarm" },As duas entradas de versão são as únicas linhas deste bloco que mudam entre builds, e é por isso que ficam de fora; a terceira omissão são apenas as Properties do alarme, impressas à parte abaixo. Tudo o que é mostrado é o que o seu próprio build escreve.
O alarme é o recurso da vinculação, não o do banco de dados. Desvincular storage-headroom do Aggregate remove exatamente esse recurso e a única saída que ele publica, e deixa PaymentsDb byte a byte como estava.
O nome de recurso de uma vinculação traz o escopo que traz a vinculação
Uma Feature é escrita uma vez e vinculada muitas vezes, então o nome que uma FeatureRecipe deriva precisa ser distinto por vinculação. Esta compõe o componente host e o nome da vinculação: o host payments-db, levado sob storage-headroom, dá PaymentsDbStorageHeadroom.
Compor apenas o host bastaria para manter o alarme separado do recurso que ele monitora, e não bastaria para impedir que a mesma Feature vinculada duas vezes a um componente colida consigo mesma — que é do que trata a release com falha abaixo.
As propriedades do próprio alarme se referem ao host pelo nome derivado do host:
"Properties": { "AlarmDescription": "Free storage below 21474836480 bytes on payments-db", "ComparisonOperator": "LessThanThreshold", "Dimensions": [ { "Name": "DBInstanceIdentifier", "Value": { "Ref": "PaymentsDb" } } ], "EvaluationPeriods": 2, "MetricName": "FreeStorageSpace", "Namespace": "AWS/RDS", "Period": 300, "Statistic": "Minimum", "Threshold": 21474836480, "TreatMissingData": "breaching" },Ref no recurso do banco de dados é resolvido para o identificador dessa instância quando o stack é implantado. As duas metades derivam PaymentsDb do mesmo nome de componente, e é isso que as faz concordar — nada aqui é consultado.
Quem decide o quê, em uma única vinculação
A vinculação divide as suas entradas como um componente faz. Quanta folga a aplicação precisa é intenção do desenvolvedor, escrita na vinculação em aggregate.yaml — é uma propriedade da aplicação. Para onde o alarme notifica, e quanto tempo uma queda precisa persistir antes que ele dispare, são dimensionamento do operador, fornecido pela Release:
payments-db: features: storage-headroom: infra: evaluation_periods: 3 notify_target: "arn:aws:sns:eu-west-1:123456789012:payments-oncall"Uma Release fornece infra para uma vinculação que o Aggregate declarou, e nunca values. A release de dois stacks define ambos; a release de um único stack não define nenhum, e a diferença pode ser lida na saída. Definidos:
"Properties": { "AlarmActions": [ "arn:aws:sns:eu-west-1:123456789012:payments-oncall" ],Sem definição, o campo fica ausente em vez de vazio — o alarme é emitido sem nenhuma ação de notificação, e EvaluationPeriods cai no 2 que a Recipe traz em vez de em algo que a Feature declarou. Uma Release que não fornece nenhum dos dois ainda obtém um alarme funcional, e fornecer um adiciona exatamente um campo.
As saídas de uma vinculação são nomeadas pelo seu host, não por ela mesma
As duas metades do stack são nomeadas segundo regras diferentes, e esta é a metade que surpreende.
O ID lógico de um recurso vem da própria Recipe da vinculação — o nome acima. Uma saída é nomeada pelo componente que publica e pela entrada juntos, e, para uma vinculação, o componente que publica é o host. O alarme publica uma entrada, alarm-id, e ela aparece como:
"paymentsXzhdbXXalarmXzhid": { "Value": { "Ref": "PaymentsDbStorageHeadroom" } },As duas metades são legíveis depois que você conhece a regra: um ID lógico admite apenas letras e dígitos, então o provedor escreve por extenso o que esse alfabeto recusa em vez de descartá-lo — Xzh é o hífen que você escreveu, e XX é onde o nome do componente termina e o nome da entrada começa. payments-db publicando alarm-id, e nada mais, chega a esse nome. Nomes no stack montado expõe o esquema por completo.
É o mesmo nome de saída a que se chegaria se o próprio banco de dados tivesse publicado alarm-id. Então um nome de entrada que o host também publica se encontraria com o da vinculação em um único nome de saída — e é por isso que nomes de entrada que se leem como próprios da vinculação os mantêm separados dos do host.
Uma vinculação de toda a fronteira é renderizada uma única vez para a fronteira
core/shared-config é vinculada na Release, na fronteira em vez de em um componente, e é renderizada uma vez para essa fronteira — não uma vez por componente nela. O build de um único stack contém dois componentes e exatamente um AppSharedConfig:
"AppSharedConfig": { [… omitted: the provenance Metadata, whose shape is shown above] "Properties": { "Description": "Settings shared by every component in the app boundary", "Name": "/app/shared-config", "Type": "String", "Value": "tier=production" }, "Type": "AWS::SSM::Parameter" },Faça o build da release de dois stacks e a questão fica mais nítida: cada fronteira recebe o seu, trazendo as configurações resolvidas próprias dessa fronteira. As Properties daquele em cada um dos dois templates que esse build escreve:
"Properties": { "Description": "Settings shared by every component in the data boundary", "Name": "/data/shared-config", "Type": "String", "Value": "tier=production-data" }, "Properties": { "Description": "Settings shared by every component in the app boundary", "Name": "/app/shared-config", "Type": "String", "Value": "tier=production-app" },Ela é vinculada na Release porque o que traz é um arranjo próprio do operador, e não algo que o Aggregate declara. Uma vinculação de fronteira define infra: e nunca values: — o Aggregate continua sendo onde os valores do desenvolvedor são escritos.
Dividir a mesma intenção entre dois stacks
aggrega pull --release release-two-stacks.yamlaggrega build --release release-two-stacks.yamlNada muda em aggregate.yaml. A aplicação ainda declara que usa o banco de dados; o operador decide na Release que os dois são provisionados separadamente, e a referência entre eles atravessa uma borda de stack como resultado.
No build de um único stack, a aplicação recebe o endpoint como uma referência dentro do único template:
"Properties": { "Name": "/reporting/db-host", "Tier": "Standard", "Type": "String", "Value": { "Fn::GetAtt": [ "PaymentsDb", "Endpoint.Address" ] } },No build de dois stacks, o stack produtor publica esse valor como um export:
"paymentsXzhdbXXhost": { "Value": { "Fn::GetAtt": [ "PaymentsDb", "Endpoint.Address" ] }, "Export": { "Name": "aggrega--cloudformation-two-stacks--two-stacks-data-zscloudformation--payments-db--host" } },e o stack consumidor o lê de volta por esse mesmo nome:
"Properties": { "Name": "/reporting/db-host", "Tier": "Standard", "Type": "String", "Value": {"Fn::ImportValue":"aggrega--cloudformation-two-stacks--two-stacks-data-zscloudformation--payments-db--host"} },Apenas host traz um Export, porque essa é a entrada que uma aresta realmente consome; as outras entradas publicadas do banco de dados aparecem como saídas simples. O alarme de escopo de componente segue o seu host para o stack produtor, e cada fronteira mantém a sua própria vinculação de toda a fronteira.
Nenhuma das duas funções intrínsecas é avaliada no momento do build. O endpoint não existe até que o stack seja implantado, então o compilador canaliza a referência adiante e o CloudFormation a resolve — e é por isso que a aplicação nunca nomeia um endereço.
Para saber como o nome de export é construído, e quando o consumidor lê por meio de Fn::ImportValue em vez de uma leitura direta entre contas, veja Ligação entre stacks.
O build que é interrompido
aggrega pull --release release-negative-name-collision.yamlaggrega build --release release-negative-name-collision.yamlaggregate-name-collision.yaml vincula o alarme duas vezes a um componente, sob dois nomes de vinculação. O nome de recurso de cada vinculação compõe o seu próprio nome de vinculação, então os dois alarmes são dois recursos distintos e não colidem aí. As suas saídas colidem: cada uma publica alarm-id, uma saída é nomeada pelo componente host e pela entrada, e o host é o mesmo componente para ambas.
[… omitted: the pull's lines, which report the same collision while writing the lockfile][TRANSLATION_ERROR E0038] dispatch groups whose contributors derive one name more than once in one key space caused by (2): [TRANSLATION_ERROR] release-negative-name-collision.yaml derived name collision: one name is derived more than once in one key space ("paymentsXzhdbXXalarmXzhid", key space "output-logical-ids", derived by component "payments-db", carrying attachment "storage-headroom", provider "cloudformation", dispatch path "name-collision/cloudformation") --- [TRANSLATION_ERROR] release-negative-name-collision.yaml derived name collision: one name is derived more than once in one key space ("paymentsXzhdbXXalarmXzhid", key space "output-logical-ids", derived by component "payments-db", carrying attachment "storage-headroom-strict", provider "cloudformation", dispatch path "name-collision/cloudformation")Quatro coisas a ler aí, e cada uma é deliberada.
- As duas pontas são nomeadas. Cada entrada informa o componente e o nome de vinculação que ele carregava, então ambos podem ser buscados nos arquivos que você escreveu. Nada em uma colisão torna o nome de um contribuidor o pretendido, então ambos são reportados em vez do primeiro.
- O espaço de chaves é nomeado.
output-logical-idsdiz a você qual dos dois espaços de nomes do stack foi atingido e — como o espaço de nomes dos recursos está ausente desta interrupção — que os nomes dos recursos estavam corretos. - Nada é emitido. O build para em vez de escrever um stack em que um dos dois alarmes fica silenciosamente sem saída.
- Dar nomes distintos aos recursos não resolve este caso. O nome de saída é construído a partir do componente host e da entrada, então é a entrada que precisa ser diferente — ou uma única vinculação em vez de duas, ou uma Feature cujos nomes de entrada publicados se leem como próprios dessa vinculação.
Entrada idêntica, saída idêntica
Fazer o build duas vezes a partir de entradas inalteradas produz templates idênticos byte a byte. O compilador não resolve nenhum dado em tempo real — ele nunca chama a AWS, nunca consulta um identificador de conta e nunca executa o CloudFormation —, 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/ e os arquivos *.lock são gerados e não entram em commits; eles são regenerados a partir dos arquivos que entram.