Stack do CloudFormation com anexos
Uma base de dados gerida e a aplicação que a lê, escritas uma única vez como intenção do programador e montadas em templates de stacks do AWS CloudFormation. Dois anexos trazem recursos próprios — um alarme na base de dados e um parâmetro de definições partilhadas na fronteira —, pelo que este exemplo mostra onde os recursos de um anexo ficam na stack montada e como são nomeados ao lado dos do componente.
A mesma intenção do programador é compilada de três formas: como uma stack, como duas stacks com uma referência que passa entre elas, e — deliberadamente — como uma compilação que é interrompida.
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: uma base de dadospayments-dbdo tipocore/datastore/mariadbe umreporting-appdo tipoexample/compute/db-readerque declara que usa a base de dados. Nada sobre a AWS está aqui. O blocofeatures:da base de dados trazstorage-headroom, que anexaexample/storage-alarm.release-one-stack.yaml— ambos os componentes numa única fronteira, pelo que ambos são montados numa única stack. Anexacore/shared-configa toda a fronteira.release-two-stacks.yaml— a mesma intenção dividida por duas fronteiras, pelo que a referência da aplicação à base de dados atravessa um limite de stack.release-negative-name-collision.yamlcomaggregate-name-collision.yaml— concebida para falhar. Anexa o alarme duas vezes a um mesmo componente.manifest.yaml— vincula cada tipo de componente e cada Feature anexada à Recipe que o implementa neste destino..aggrega-config.yaml— nomeia o registo do hub a partir do qual as entidades do catálogo são resolvidas.
Cada release vincula o slot root_password da base de dados na sua entrada para payments-db, com core/generated-secret. Neste destino, o RDS é dono da palavra-passe de administrador, e a Recipe de base de dados que o Manifest escolhe traz a diretiva que o diz; isso torna o vínculo uma decisão do operador, escrita na Release, e o Aggregate nada diz sobre ele.
Cada release anexa também core/backup a payments-db, com infra.retention_days: 14, e o Manifest vincula-a a cloudformation/backup-native. O RDS mantém as cópias de segurança automatizadas da instância durante 7 dias quando nada indica o contrário; este anexo mantém cada uma durante 14. A FeatureRecipe não 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 "BackupRetentionPeriod": 14 nas Properties da própria instância.
Todas as entidades que este exemplo usa residem no catálogo publicado. Nada é copiado para junto dos ficheiros de release, pelo que o exemplo é resolvido contra o catálogo tal como está, e não contra um instantâneo privado dele.
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:
aggrega scaffold --example cloudformation-rds-stackDepois, imprime os próximos comandos a executar. O primeiro entra na nova pasta:
cd cloudformation-rds-stackCompilação
Este exemplo inclui três releases, pelo que é necessário nomear a pretendida. É compilada uma release por execução. A primeira compilação de cada release precisa do seu lockfile, que o comando pull escreve:
aggrega pull --release release-one-stack.yamlaggrega build --release release-one-stack.yamlA compilação imprime, com <workspace> a representar a pasta deste exemplo:
Total build time: 4.1sBuild completed: 1 file written to <workspace>/distA stack montada fica em dist/one-stack/cloudformation/cloudformation-stack.json. Cada componente e cada anexo que renderiza para esse diretório contribui para esse único template — o fornecedor emite uma única stack em JSON puro em vez de um ficheiro por contribuidor.
Com um assistente de IA
Um assistente de IA configurado com as ferramentas do Aggrega pode fazer o mesmo: cole-lhe este prompt.
Use apenas as ferramentas do Aggrega e não crie nenhuma pasta por iniciativa própria. Se a pasta do espaço de trabalho ainda não contiver uma pasta `cloudformation-rds-stack`, chame uma vez a ferramenta `scaffold` com `example` definido como `cloudformation-rds-stack` e sem `dir`: esta escreve o exemplo numa 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. Indique-me que ficheiros o build escreveu; encontram-se em `cloudformation-rds-stack/dist/`.O que chega à stack, e quem o forneceu
A compilação de uma única stack monta quatro recursos de quatro contribuidores diferentes:
| Recurso | Fornecido por |
|---|---|
PaymentsDb | a própria Recipe do componente de base de dados |
PaymentsDbStorageHeadroom | o anexo storage-headroom nesse componente |
AppSharedConfig | o anexo shared-settings na fronteira |
ReportingApp | a própria Recipe do componente de aplicação |
O anexo backup em payments-db não está na tabela porque não fornece nenhum recurso próprio: o que define fica dentro de PaymentsDb.
Cada recurso traz um bloco de proveniência que nomeia o contribuidor de onde veio, pelo que as duas metades continuam distinguíveis dentro de uma stack para a 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 compilações, 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 a sua própria compilação escreve.
O alarme é o recurso do anexo, não o da base de dados. Desanexar storage-headroom do Aggregate remove exatamente esse recurso e a única saída que publica, e deixa PaymentsDb byte a byte como estava.
O nome de recurso de um anexo traz o âmbito que traz o anexo
Uma Feature é escrita uma vez e anexada muitas vezes, pelo que o nome que uma FeatureRecipe deriva tem de ser distinto por anexo. Esta compõe o componente anfitrião e o nome do anexo: o anfitrião payments-db, transportado sob storage-headroom, dá PaymentsDbStorageHeadroom.
Compor apenas o anfitrião bastaria para manter o alarme separado do recurso que vigia, e não bastaria para impedir que a mesma Feature anexada duas vezes a um componente colida consigo própria — que é aquilo de que trata a release que falha abaixo.
As propriedades do próprio alarme referem-se ao anfitrião pelo nome derivado do anfitrião:
"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 da base de dados é resolvido para o identificador dessa instância quando a stack é implementada. As duas metades derivam PaymentsDb do mesmo nome de componente, e é isso que as faz concordar — nada aqui é consultado.
Quem decide o quê, num único anexo
O anexo divide as suas entradas como faz um componente. A margem de que a aplicação precisa é intenção do programador, escrita no anexo em aggregate.yaml — é uma propriedade da aplicação. Para onde o alarme notifica, e quanto tempo uma descida tem de persistir antes de disparar, 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 um anexo que o Aggregate declarou, e nunca values. A release de duas stacks define ambos; a release de uma única stack não define nenhum, e a diferença lê-se 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 qualquer ação de notificação, e EvaluationPeriods recai no 2 que a Recipe traz em vez de em algo que a Feature tenha declarado. Uma Release que não forneça nenhum dos dois obtém ainda assim um alarme funcional, e fornecer um acrescenta exatamente um campo.
As saídas de um anexo são nomeadas pelo seu anfitrião, não por ele próprio
As duas metades da 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 do anexo — o nome acima. Uma saída é nomeada pelo componente que publica e pela entrada em conjunto, e, para um anexo, o componente que publica é o anfitrião. O alarme publica uma entrada, alarm-id, que aparece como:
"paymentsXzhdbXXalarmXzhid": { "Value": { "Ref": "PaymentsDbStorageHeadroom" } },As duas metades leem-se depois de conhecida a regra: um ID lógico admite apenas letras e dígitos, pelo que o fornecedor escreve por extenso o que esse alfabeto recusa em vez de o descartar — Xzh é o hífen que foi escrito, e XX é onde o nome do componente termina e o nome da entrada começa. payments-db a publicar alarm-id, e nada mais, chega a esse nome. Nomes na stack montada expõe o esquema na íntegra.
É o mesmo nome de saída a que se chegaria se a própria base de dados tivesse publicado alarm-id. Assim, um nome de entrada que o anfitrião também publique encontraria o do anexo num único nome de saída — e é por isso que nomes de entrada que se leem como próprios do anexo os mantêm separados dos do anfitrião.
Um anexo de toda a fronteira é renderizado uma única vez para a fronteira
core/shared-config é anexada na Release, na fronteira em vez de num componente, e é renderizada uma vez para essa fronteira — não uma vez por cada componente que contém. A compilação de uma única 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" },Compile-se a release de duas stacks e a questão fica mais nítida: cada fronteira recebe o seu, com as definições resolvidas próprias dessa fronteira. As Properties daquele em cada um dos dois templates que essa compilação 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" },É anexada na Release porque o que traz é uma disposição própria do operador, e não algo que o Aggregate declare. Um anexo de fronteira define infra: e nunca values: — o Aggregate continua a ser onde os valores do programador são escritos.
Dividir a mesma intenção por duas stacks
aggrega pull --release release-two-stacks.yamlaggrega build --release release-two-stacks.yamlNada muda em aggregate.yaml. A aplicação continua a declarar que usa a base de dados; o operador decide na Release que as duas são aprovisionadas separadamente, e a referência entre elas atravessa, em consequência, um limite de stack.
Na compilação de uma única 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" ] } },Na compilação de duas stacks, a stack produtora 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 a stack consumidora volta a lê-lo pelo 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 da base de dados surgem como saídas simples. O alarme de âmbito de componente segue o seu anfitrião para a stack produtora, e cada fronteira mantém o seu próprio anexo de toda a fronteira.
Nenhuma das duas funções intrínsecas é avaliada no momento da compilação. O endpoint não existe até a stack ser implementada, pelo que o compilador canaliza a referência tal como está e o CloudFormation resolve-a — e é por isso que a aplicação nunca nomeia um endereço.
Para a forma como o nome de export é construído, e para quando o consumidor lê através de Fn::ImportValue em vez de uma leitura direta entre contas, veja-se Ligação entre stacks.
A compilação que é interrompida
aggrega pull --release release-negative-name-collision.yamlaggrega build --release release-negative-name-collision.yamlaggregate-name-collision.yaml anexa o alarme duas vezes a um componente, sob dois nomes de anexo. O nome de recurso de cada anexo compõe o seu próprio nome de anexo, pelo que 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 anfitrião e pela entrada, e o anfitrião é 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 indica o componente e o nome de anexo que este transportava, pelo que ambos podem ser pesquisados nos ficheiros escritos. Nada numa colisão torna o nome de um contribuidor o pretendido, pelo que ambos são reportados em vez do primeiro.
- O espaço de chaves é nomeado.
output-logical-idsindica qual dos dois espaços de nomes da 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. A compilação para em vez de escrever uma 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 anfitrião e da entrada, pelo que é a entrada que tem de ser diferente — ou um único anexo em vez de dois, ou uma Feature cujos nomes de entrada publicados se leiam como próprios desse anexo.
Entrada idêntica, saída idêntica
Compilar duas vezes a partir de entradas inalteradas produz templates idênticos byte a byte. O compilador não resolve nenhum dado em tempo real — nunca chama a AWS, nunca consulta um identificador de conta e nunca executa o CloudFormation —, 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/ e os ficheiros *.lock são gerados e não entram em commits; são regenerados a partir dos ficheiros que entram.