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

Provider CloudFormation

O provedor cloudformation renderiza Recipes do Aggrega em templates de stack do AWS CloudFormation. Cada componente que renderiza para o mesmo diretório de saída com este provedor é montado em um único stack, emitido como um só template em JSON puro que usa funções intrínsecas em forma longa. Uma fronteira, portanto, se torna um stack no caso comum — e duas fronteiras cujo directory: se resolve para o mesmo caminho são montadas juntas em um único stack, compartilhando os nomes desse template. Como todo provedor do Aggrega, ele é offline e hermético — um build do Aggrega é uma compilação antecipada, então o provedor nunca chama a AWS, nunca resolve identificadores gerados pela conta e nunca executa o CloudFormation. Valores que só existem em tempo de execução permanecem como referências intrínsecas do CloudFormation (Fn::GetAtt, Fn::ImportValue, Fn::GetStackOutput) que o CloudFormation resolve no momento da implantação.

Recipes de fragmentos montadas em um stack

Uma Recipe cloudformation escreve um fragmento — os recursos do CloudFormation contribuídos por um único componente — em vez de um template inteiro. Quando os componentes de uma fronteira são renderizados, o provedor monta cada fragmento do grupo de despacho em um único template de stack: os recursos são mesclados sob um único mapa Resources, os valores provides de cada componente aparecem como Outputs do stack, e as demais seções de nível superior do template são tratadas uma a uma em Seções de nível superior no stack montado. Duas formas de autoria são aceitas:

  • Entrada de fragmentos (artefatos). Uma Recipe escreve fragmentos de recursos diretamente; o provedor os normaliza para JSON puro com funções intrínsecas em forma longa e os mescla no stack montado.
  • Entrada proveniente de uma fonte. Uma Recipe referencia um template do CloudFormation existente (YAML ou JSON); o provedor o normaliza para JSON em forma longa e valida sua estrutura antes da montagem, preenche os parâmetros que o template declara a partir do valuesMapping da Recipe — veja Valores para os parâmetros de um template de origem — e deixa de fora qualquer recurso que as entradas omits: da Recipe nomeiem — veja Deixar de fora recursos de um template de origem.

O template montado é JSON puro. As funções intrínsecas são emitidas literalmente e nunca avaliadas em tempo de build — o compilador não pode resolver um valor que só existe depois que o stack é implantado, e avaliar um quebraria o contrato de compilação antecipada.

Uma Feature vinculada a um componente contribui para o mesmo stack

Uma Feature vinculada a um componente contribui com seus recursos para o stack no qual seu componente hospedeiro é montado, nos mesmos termos que a própria Recipe do componente hospedeiro. Não há nenhum template separado ao lado dele: o stack montado é a totalidade do que este provedor emite para um diretório de saída, então os recursos de uma Feature vinculada ou estão nesse stack ou não são implantados de forma alguma. Desvincular a Feature remove exatamente esses recursos e deixa intactos os do próprio componente hospedeiro.

Como eles vão parar no stack montado, compartilham seus nomes. Os IDs lógicos dos recursos de uma Feature vinculada ficam no mesmo espaço que os do componente hospedeiro e que os de qualquer outra Feature vinculada ao lado dela, então Nomes no stack montado se aplica a eles sem alterações. Onde dois contribuidores se encontram em um mesmo nome, a interrupção nomeia o componente e a chave sob a qual a Feature está vinculada, de modo que as duas pontas da colisão podem ser pesquisadas nos seus próprios arquivos.

As saídas de uma Feature vinculada são publicadas sob o nome do seu componente hospedeiro, e os IDs lógicos dos seus recursos não. As duas metades do stack são nomeadas por regras diferentes, então respondem a isso de forma diferente. O ID lógico de um recurso é emitido exatamente como a FeatureRecipe o escreveu, como o de qualquer Recipe. Uma saída é nomeada a partir do componente que publica e da entrada juntos — e, para uma Feature vinculada a um componente, o componente que publica é o hospedeiro: uma Feature vinculada a payments-db que publica alarm chega a paymentsXzhdbXXalarm, o mesmo nome a que chegaria se o componente hospedeiro tivesse publicado essa entrada ele mesmo. Assim, um nome de entrada que o hospedeiro também publica encontra o da vinculação em um mesmo nome de saída, e o build é interrompido nomeando o componente e a chave sob a qual a Feature está vinculada ao lado do componente por si só. Escolher nomes de entrada que se leiam como próprios da Feature — backup-alarm em vez de alarm — os mantém afastados dos do hospedeiro.

Cada recurso com que uma Feature contribui mantém, na proveniência que o build grava nele, a identidade composta para essa vinculação em vez da do componente hospedeiro, de modo que os dois continuam distinguíveis dentro de um stack para o qual ambos contribuíram. Rótulos e anotações explica como essa identidade é construída.

Seções de nível superior no stack montado

Vários componentes são montados em um único stack, então a montagem precisa dar conta de cada seção de nível superior que um template do CloudFormation admite — incluindo Globals e Hooks, as duas seções que uma transformação hospedada pelo CloudFormation acrescenta à linguagem de templates. Cada uma se enquadra em exatamente um dos grupos abaixo, e uma chave de nível superior que um componente escreve e que não é seção nenhuma recebe um aviso que nomeia o componente e a chave, para que nada seja descartado sem ser dito.

Montados sob nomes aos quais o provedor dá um escopo, ou lidos como estão escritos. Resources e Outputs, que Nomes no stack montado aborda por completo. AWSTemplateFormatVersion é escrito pelo provedor em vez de lido de algum componente: a linguagem de templates admite um único valor para ele, então não há nada para um componente decidir.

Carregados com exatamente os nomes que você escreveu. Parameters, Mappings, Conditions, Metadata e Rules. Cada uma dessas seções é um mapa com chaves que você escolheu, então as entradas de cada componente chegam ao stack montado com esses nomes, sem reescrita — e é isso que permite que uma Condition: de um recurso, um Fn::FindInMap ou um Ref a um parâmetro se resolvam contra a declaração que chegou junto com eles. Cada uma é carregada separadamente, porque cada uma é escrita separadamente: uma regra faz asserções sobre um parâmetro do mesmo documento, uma condição pode não referenciar parâmetro algum, e o CloudFormation não permite uma referência a parâmetro dentro de um mapeamento.

Uma mesma palavra cobre aqui dois lugares diferentes, e só o primeiro é seu. O Metadata na lista acima é a seção de nível superior própria do template, um mapa de nomes que você escolheu. Um recurso individual também carrega um atributo Metadata próprio, e é ali que o build escreve a proveniência — sob uma única chave reservada aggrega.ai/, acrescentada ao lado de qualquer coisa que você tenha escrito ali em vez de substituí-la. Então uma entrada de proveniência que aparece dentro de um recurso não é algo que você escreveu nem algo que a seção de nível superior carregou.

Parameters, Mappings, Conditions e Rules nomeiam suas entradas com um ID lógico. Como o provedor carrega um nome exatamente como você o escreveu, o alfabeto que um ID lógico admite também alcança essas seções: um nome em uma das quatro que contenha qualquer coisa além de letras e dígitos interrompe o build — veja Um nome de seção carregado fora do alfabeto interrompe o build. O provedor não submete os nomes da seção Metadata de nível superior a esse alfabeto: eles nomeiam informações que você está armazenando, e não algo que o template endereça.

Dois componentes que declaram nomes diferentes em uma dessas seções chegam ambos. Dois que declaram um mesmo nome com conteúdo idêntico se fundem em uma única entrada e o build prossegue. Dois que declaram um mesmo nome com conteúdo diferente interrompem o build, nomeando a seção, o nome e ambos os componentes — porque, do contrário, um dos dois corpos seria descartado, deixando o componente que o escreveu com uma declaração que o stack não carrega. É a mesma conciliação que os nomes de recursos e de saídas seguem, e renomear qualquer um dos dois a resolve.

Nomeados em vez de carregados. Description é uma única afirmação sobre um template inteiro, e não um mapa de nomes que você escolheu, então uma montagem que se vale de vários componentes não tem resposta para ela: duas descrições são duas respostas a uma mesma pergunta e nenhuma delas é a do stack. Hooks é lido apenas pela transformação AWS::CodeDeployBlueGreen, que o stack montado nunca carrega (veja abaixo). Portanto, o stack montado não carrega nenhuma das duas seções, e todo componente que escreveu uma delas recebe um aviso que nomeia o componente e a seção. O mesmo vale para um componente que escreve Globals sem declarar a transformação AWS::Serverless-2016-10-31 que a lê. O aviso é consultivo e fora de banda: o template emitido é byte a byte o que seria sem ele, e --no-unsupported-field-warnings o silencia junto com o restante dessa classe.

Transform é construído a partir do de cada componente. Uma transformação é uma macro que o CloudFormation executa sobre o template inteiro antes de implantar qualquer coisa, então o Transform do stack montado é a união das transformações que seus componentes declaram — as de um template de origem assim como as de um fragmento — na ordem que o CloudFormation documenta: uma macro que a sua conta define antes das transformações que o CloudFormation hospeda, e AWS::LanguageExtensions antes de AWS::Serverless-2016-10-31. A ordem própria de cada componente é mantida, e duas transformações que nada ordena são executadas na ordem em que os componentes as declaram pela primeira vez, de modo que os mesmos componentes dão o mesmo stack. Uma transformação é escrita como string e várias como lista. Um stack com um único componente, que declara seu Transform em um template ou fragmento, o mantém exatamente como foi escrito onde quer que a tabela abaixo o carregue, e um stack cujos componentes não declaram nenhuma não carrega nenhuma. A transformação de um componente não gera aviso: ela é carregada, ou o build é interrompido nomeando-a.

Como uma transformação processa o template inteiro, carregar uma muda como o conteúdo de todos os outros componentes é implantado, a menos que o que ela faz esteja restrito ao conteúdo escrito para ela. Assim, cada transformação recebe o tratamento que a própria documentação do CloudFormation sobre ela sustenta, e uma combinação que o stack não consegue carregar interrompe o build, nomeando a transformação e cada componente no stack:

transformaçãono stack montado
AWS::Serverless-2016-10-31carregada, com os Globals do componente que a declara. Interrompe o build onde esses Globals alcançariam os recursos serverless de outro componente, e onde uma das fontes de eventos dos seus recursos nomeia um recurso que outro componente declara, porque a transformação reescreve o recurso que um evento nomeia.
AWS::LanguageExtensionscarregada sozinha, ou ao lado de AWS::Serverless-2016-10-31 do mesmo componente. Interrompe o build ao lado do conteúdo serverless de outro componente, porque a transformação serverless nomeia o que gera de outra forma depois que as extensões de linguagem resolveram seus valores.
AWS::SecretsManager-2020-07-23, AWS::SecretsManager-2024-09-16carregadas: processam apenas os agendamentos de rotação que as solicitam.
AWS::ServiceCatalogcarregada para um stack com um único componente. Ao lado de qualquer outro, interrompe o build, porque substitui seu padrão de referência em qualquer parte do template.
AWS::CodeDeployBlueGreeninterrompe o build, mesmo sozinha: o CloudFormation recusa Outputs e Fn::ImportValue em qualquer parte de um template que a declare, e o stack montado carrega as saídas que seus componentes publicam.
AWS::Includeinterrompe o build, mesmo sozinha: insere conteúdo buscado no S3 quando o stack é implantado, que o build não consegue ler.
uma macro que a sua conta definecarregada para um stack com um único componente. Ao lado de qualquer outro, interrompe o build, porque o que ela faz com o restante do template é desconhecido para o build.

Dois componentes que declaram um mesmo par de transformações em ordens opostas também interrompem o build, nomeando ambas as ordens e ambos os componentes, já que o stack as executa em uma única ordem. Um componente que precisa de uma transformação que o stack não consegue carregar vai em uma fronteira própria.

Nomes no stack montado

Um ID lógico do CloudFormation é único dentro de um template e admite apenas letras e dígitos, e todo componente que é montado nesse template compartilha seus nomes — incluindo componentes de uma segunda fronteira, quando ambas resolvem para o mesmo diretório de saída. Então cada nome pelo qual o stack endereça algo precisa ser distinto entre todos os componentes que contribuíram para ele, e o conjunto de contribuidores nem sempre é uma única fronteira.

IDs lógicos de recurso vêm da Recipe. O provedor os emite exatamente como foram escritos e não reescreve nenhum, então o nome que você lê no template montado é o nome que a Recipe escreveu. As Recipes do CloudFormation da biblioteca padrão o derivam do próprio nome da instância do componente, lendo os separadores desse nome como limites de palavra: a instância payments-db nomeia seu recurso PaymentsDb. Duas instâncias do mesmo tipo descrevem, portanto, dois recursos em vez de disputarem um.

Nomes de saída têm o escopo do componente que os publicou. Cada entrada de provides aparece como uma saída nomeada pelo componente que publica e pela entrada juntos — o componente payments-db publicando host aparece como paymentsXzhdbXXhost — então dois componentes que publicam a mesma entrada chegam a duas saídas separadas, e o significado de uma saída não muda quando outro componente entra no stack. Um consumidor entre stacks na mesma conta e região importa pelo nome de export, e não por este, então o nome de export não é afetado; uma leitura entre contas ou entre regiões nomeia esta saída, como o provedor a escreve para você (veja Ligação entre stacks).

Como um nome de saída é construído

Um ID lógico não admite nenhum caractere separador, então um nome construído a partir de algo que você escreveu precisa levar seus separadores de alguma forma. Descartá-los causaria perda: payments-db e payments_db são dois componentes, e um nome que descartasse a pontuação não identificaria nenhum dos dois. Então o provedor codifica em vez disso o que o alfabeto recusa, escrevendo cada caractere recusado por extenso em caracteres que o alfabeto admite.

O esquema reserva um caractere com o qual abrir uma sequência de escape — um X maiúsculo — e escreve todo o resto como você digitou, maiúsculas incluídas. Só a maiúscula é reservada, então o x minúsculo de um nome como nginx-proxy é carregado como você o escreveu:

o que você escreveuo que se tornapor quê
uma letra ou dígito, exceto Xo próprio caractereo alfabeto o admite
-Xzho alfabeto recusa o hífen
_Xzuo alfabeto recusa o sublinhado
.Xzdo alfabeto recusa o ponto final
/Xzso alfabeto recusa a barra, que uma identidade de componente aninhada carrega
XXzx000058reservado para abrir uma sequência de escape, então é escrito por extenso pelo seu ponto de código
qualquer outra coisaXzx e o ponto de código do caractereuma única regra cobre todos os caracteres restantes
o encontro das duas metadesXXdois caracteres de abertura seguidos, que nenhuma das metades pode conter

A releitura é inequívoca, e esse é o objetivo, não um detalhe. Um X é mantido como ele mesmo apenas quando o caractere depois dele é um que o alfabeto admite, então uma metade codificada nunca termina com um e nunca carrega dois seguidos — o que deixa XX livre para significar a junção, e apenas a junção.

Assim, três nomes que diferem apenas em onde fica sua pontuação continuam separados:

component payments-db publishing host → paymentsXzhdbXXhost
component payments_db publishing host → paymentsXzudbXXhost
component payments publishing db-host → paymentsXXdbXzhhost

Os nomes são mais longos e menos imediatamente legíveis do que o nome de componente que você escreveu, e essa é a troca. Um nome que identifica exatamente uma entrada vale mais do que um mais curto que não identifica nenhuma de duas — e você endereça uma saída pelo nome de export em vez de digitar este, então o que ele custa é uma segunda olhada ao ler um template emitido.

IDs lógicos de recurso seguem uma regra diferente, porque o provedor não os constrói: ele emite o que a Recipe escreveu. As Recipes do CloudFormation da biblioteca padrão derivam um lendo os separadores do nome da instância como limites de palavra — a instância payments-db nomeia seu recurso PaymentsDb — e essa derivação descarta os separadores, então dois nomes de instância que diferem apenas na pontuação, ou apenas em maiúsculas e minúsculas de uma letra, ainda assim derivam um único nome de recurso. O build é interrompido, nomeando cada instância que chegou ao nome junto com o nome em que elas foram parar, em vez de emitir um único recurso onde dois componentes foram declarados. Todas elas são nomeadas, e não apenas algumas, porque nada em uma colisão torna a derivação de uma instância a pretendida. Renomear todas menos uma resolve a interrupção.

Um ID lógico de recurso fora do alfabeto interrompe o build

A unicidade e o alfabeto são dois requisitos separados, e um conjunto de nomes pode satisfazer o primeiro e falhar no segundo. Como o provedor emite um ID lógico de recurso exatamente como a Recipe o escreveu, o ID que uma Recipe escreve precisa ser um que um template do CloudFormation consiga conter por si só: letras e dígitos, e nada mais.

É aqui que um nome derivado e um repassado como está se separam. Um nome de saída é construído pelo provedor, que codifica o componente que publica e a entrada, então um nome de saída fica dentro do alfabeto independentemente de como você escreva qualquer uma das metades. Um ID lógico de recurso é repassado como está, então o que quer que a Recipe tenha escrito é o que o template recebe.

Isso o torna também uma restrição sobre nomes de componentes, sempre que uma Recipe escreve o nome de uma instância de componente diretamente no ID lógico. Um nome de componente pode conter um hífen ou um sublinhado; um ID lógico não. Um componente que você direciona a este provedor por meio de uma Recipe assim é, portanto, nomeado só com letras e dígitos — paymentsdb em vez de payments-db — e qualquer outra coisa interrompe o build.

A interrupção nomeia o contribuidor cuja Recipe escreveu o ID, o próprio ID e cada caractere nele que não pode estar ali, e diz o que você pode escrever em vez disso. Duas coisas a resolvem, e a primeira é a que está sempre disponível para você:

  • Faça a Recipe escrever um ID lógico próprio em vez de repassar um nome diretamente. As Recipes do CloudFormation da biblioteca padrão seguem esse caminho — elas leem os separadores do nome da instância como limites de palavra, então a instância payments-db nomeia seu recurso PaymentsDb e você mantém o nome de componente que escolheu. Derivar um ID dessa forma troca esta interrupção pela regra de colisão acima: dois nomes de instância que diferem apenas na pontuação derivam um único nome de recurso.
  • Onde uma Recipe de fato repassa um nome diretamente, renomeie o que ela repassa usando só letras e dígitos. Para a Recipe própria de um componente, isso é o nome do componente. Uma Feature vinculada a um componente nomeia seus recursos a partir da sua própria FeatureRecipe, então renomear o componente hospedeiro não os alcança — é o ID que essa Recipe escreve que precisa mudar.

O provedor recusa; ele não conserta silenciosamente. Reescrever o ID por você pareceria a coisa útil a fazer, e não é. Um ID lógico é a forma como o CloudFormation identifica um recurso ao longo das atualizações, então mudar um não é uma renomeação — ele endereça um recurso diferente. Um ID que o provedor substituísse apontaria para outro lugar que não o recurso já implantado sob o ID que você escreveu, e a substituição é uma que você nunca pediu e que teria de descobrir pelo template emitido. Um build que é interrompido nomeia o problema enquanto ainda cabe a você corrigi-lo.

Um nome de seção carregado fora do alfabeto interrompe o build

IDs lógicos de recurso não são os únicos nomes que o provedor carrega exatamente como você os escreveu. Parameters, Mappings, Conditions e Rules também nomeiam suas entradas com um ID lógico, e cada uma das quatro chega ao stack montado com o nome que seu autor escolheu. Então o requisito é o mesmo, em mais quatro superfícies: o nome precisa ser um que um template do CloudFormation consiga conter por si só — letras e dígitos, e nada mais — e qualquer outra coisa interrompe o build.

Há uma consequência que vai além da seção que carrega o nome, e é o motivo pelo qual isso interrompe o build em vez de emitir um aviso. Esses nomes são aquilo contra o qual se resolvem a Condition: de um recurso, um Fn::FindInMap ou um Ref a um parâmetro. Um nome que o alfabeto não admite, portanto, tira do template implantável a referência que aponta para ele junto com a própria declaração, de modo que um único nome escrito deixa ambos fora de alcance de uma vez — e, sem a interrupção, isso é descoberto no momento da implantação, por quem está implantando e não por quem escreveu o nome.

A interrupção nomeia o contribuidor cuja Recipe escreveu o nome, a seção em que ele foi escrito, o próprio nome e cada caractere nele que não pode estar ali. A seção é o termo a procurar nas suas Recipes: esses nomes são carregados exatamente sob a seção em que você os escreveu, então ela é a única palavra que aparece tanto na mensagem quanto nos seus próprios arquivos. Renomear a entrada usando só letras e dígitos a resolve, e esse é todo o remédio — um ID lógico de recurso oferece a alternativa de fazer a Recipe derivar um ID em vez de repassar um nome diretamente, e aqui não há nada a derivar, porque o nome na seção é o que você escreveu.

Só os nomes próprios de uma seção estão sujeitos ao alfabeto, nunca as chaves dentro de uma entrada. As chaves de segundo nível de um mapeamento são suas para escolher livremente — us-east-1 sob um mapa RegionCidr é o caso comum, e chega intacta ao template emitido. As chaves dentro do corpo de um parâmetro, de uma condição ou de uma regra nomeiam atributos, asserções e funções intrínsecas, e não algo que o stack endereça: os Assertions de uma regra, e um Fn::Contains escrito dentro dela, são chaves desse tipo. Nenhuma delas é um ID lógico, e nenhuma é verificada.

Dois nomes de entrada que você escreveu separados continuam separados

Três tipos de nome de entrada ficam próximos o bastante para se encontrar em um único nome de saída, e nenhum deles é exótico. Como as duas metades são codificadas em vez de compactadas, e se encontram em uma sequência que nenhuma das metades pode conter, os três chegam a nomes próprios:

  • Entradas que diferem apenas na pontuação. Um componente que publica tanto db-host quanto db_host chega a dbXzhhost e dbXzuhost.
  • Entradas que diferem apenas em maiúsculas e minúsculas de uma letra. host e Host chegam a host e Host, porque uma letra é carregada em maiúscula ou minúscula, como você a escreveu.
  • Entradas que se encontram através da junção. O Component payments-db publicando host chega a paymentsXzhdbXXhost; o componente payments publicando db-host chega a paymentsXXdbXzhhost.

Duas entradas ainda se encontram onde de fato nomeiam uma mesma coisa. O nome de saída é construído a partir do componente que publica e da entrada, então tudo o que compartilha os dois chega a um único nome, como quer que seja codificado. O caso que você mais provavelmente vai encontrar é uma mesma Feature vinculada duas vezes a um único componente: uma vinculação publica sob seu hospedeiro, então duas vinculações de uma Feature em um componente publicam ambas alarm-id a partir de payments-db, e não há nada no par que permita distingui-las. O build é interrompido em vez de emitir uma única saída onde duas foram escritas, nomeando o componente e a chave de vinculação que cada lado carregava, de modo que as duas pontas podem ser buscadas nos seus próprios arquivos. Vincule a Feature uma única vez ou use uma Feature cujos nomes de entrada publicados se leiam como próprios daquela vinculação.

Isso vale quer as duas entradas carreguem o mesmo valor, quer não. Duas entradas com o mesmo valor ainda descrevem duas saídas que um autor pediu, então fundi-las em uma deixaria uma das duas saídas escritas ausente do stack.

Um nome que uma Recipe compõe em um template não é coberto por isso

A codificação acima é do provedor, e se aplica aos nomes de saída que o provedor constrói. Ela não está disponível para você dentro de um template de Recipe, e um nome que o seu template compõe, portanto, não carrega nenhuma das suas garantias. Dizer isso claramente importa porque o risco é invisível de dentro do template: a compactação disponível ali lê seu argumento como palavras e descarta tudo o que há entre elas, então unir dois valores antes de compactá-los perde a junção junto com a pontuação.

Uma FeatureRecipe que nomeia um recurso a partir de uma instância e de uma chave de vinculação, unidas por um espaço e depois compactadas, é a forma a observar — app com cache e app-cache com nada são ambos compactados em AppCache, e os dois colidem antes que qualquer propriedade da compactação se aplique. Duas coisas mantêm um nome assim distinto, e ambas cabem a você, e não ao provedor:

  • Mantenha as partes compostas em letras e dígitos, para que nada seja descartado e nada precise ser distinguido.
  • Não una dois valores que possam conter cada um o separador do outro. Onde um nome precisar carregar duas partes, faça de uma delas um literal fixo que a outra não possa conter.

Onde um nome composto de fato colide, ele colide como ID lógico de recurso, e não como nome de saída, então a interrupção que você encontra é a de nomes de recurso descrita acima.

Uma chave escrita duas vezes em um mesmo mapeamento interrompe o build

Um fragmento do CloudFormation é lido como um mapeamento, e um mapeamento contém um valor por chave, então uma chave escrita duas vezes manteria o corpo que veio por último e descartaria o outro. Onde o mapeamento é um bloco Resources ou Outputs, o corpo descartado é um recurso ou uma saída que foi escrito e que simplesmente não estaria no stack.

Em vez disso, o build é interrompido, nomeando a chave repetida e as duas linhas em que ela foi escrita. Esta é uma regra sobre o fragmento inteiro, e não uma regra sobre os nomes do stack: ela se aplica a qualquer mapeamento no fragmento, incluindo as Properties de um recurso. A forma mais comum de chegar a ela é uma Recipe que deriva um ID lógico de um valor escrito por um autor, quando dois valores escritos diferem apenas na pontuação — app-cache e app_cache derivam ambos AppCache, então o fragmento escreve AppCache duas vezes.

Um nome de chave que se repete em lugares diferentes do documento é comum e não é tocado: Type aparece uma vez por recurso, e Value uma vez por saída, quantos recursos e saídas o fragmento carregar. Só uma repetição dentro de um mesmo mapeamento perde um corpo.

Um único componente pode reivindicar um mesmo nome duas vezes. Uma Recipe contribui com vários fragmentos — várias entradas de artifacts:, ou um diretório de origem com vários templates — e cada um deles é montado no mesmo stack, então os fragmentos próprios de um componente compartilham entre si os nomes do stack exatamente como os compartilham entre componentes. Dois fragmentos que dão a um mesmo nome dois corpos diferentes interrompem o build, e a interrupção nomeia o espaço de chaves em que o nome está — IDs lógicos de recurso ou nomes de saída — junto com o componente e o próprio nome. Os dois espaços podem ser alcançados dessa forma: dois fragmentos podem escrever um mesmo ID lógico de recurso sobre recursos diferentes, e um componente chega aos seus nomes de saída por dois caminhos, um bloco Outputs: explícito e suas entradas de provides:, então uma entrada de cada um carregando um mesmo nome também se encontra ali.

Repetir um nome não é, por si só, um conflito. Um nome escrito mais de uma vez com conteúdo idêntico endereça uma única coisa de qualquer forma, então as repetições se fundem em uma única entrada e o build prossegue — uma repetição comum não custa nada. O que interrompe o build é o caso que perde conteúdo: um dos dois corpos teria de ser descartado, e o recurso ou a saída que a Recipe declarou faltaria então no stack. Renomear qualquer um dos dois resolve isso.

Validação estrutural da entrada

Um template do CloudFormation de origem é validado estruturalmente antes de ser renderizado: o provedor analisa o template e normaliza suas funções intrínsecas, interrompendo o build com uma mensagem clara que nomeia o nó problemático quando um template está malformado. A análise verifica a forma, não a semântica — ela não contata a AWS, não resolve referências nem avalia funções intrínsecas.

Um template que passa na análise não é, por isso, carregado inteiro. A análise diz que o documento está bem formado; o que chega ao stack montado é decidido separadamente e seção por seção, em Seções de nível superior no stack montado — um template de origem passa pela mesma contabilização que um fragmento.

A análise também não pergunta se as referências do template se resolvem. Se um Ref nomeia um parâmetro, ou um Fn::FindInMap um mapa, é uma pergunta sobre o stack montado, e não sobre um documento de entrada específico, e cabe ao CloudFormation respondê-la no momento da implantação. O build declara o que não carregou em vez de julgar a que o resultado se refere. As referências que ele julga são as que o próprio build deixou pendentes: uma a um parâmetro que o binding de um template de origem preencheu, de que trata a próxima seção, e uma a um recurso que uma entrada de omits: deixou de fora do template, de que trata a seção seguinte a ela.

Valores para os parâmetros de um template de origem

Um template de origem recebe valores do modo como o próprio CloudFormation dá valores a um template: por meio dos Parameters que ele declara. O valuesMapping daquilo que o usa como fonte — a Recipe de um componente, ou a FeatureRecipe de uma Feature vinculada — escreve uma chave por parâmetro que preenche, e o provedor associa cada uma em todos os templates da fonte — todo Ref ao parâmetro em Resources, Outputs, Conditions, Rules e nos Globals do SAM se torna o valor, todo Fn::Sub que nomeia o parâmetro como variável recebe o valor por meio do seu mapa de variáveis, e o parâmetro sai dos Parameters de todo template que o declara. Um parâmetro que nenhuma chave nomeia é deixado exatamente como o template o escreveu, para um valor passado quando o stack é implantado ou para o seu Default.

A fonte é a unidade que declara um parâmetro. Os templates de uma fonte de diretório são montados em um único stack, então um template pode referenciar um parâmetro que outro template da mesma fonte declara. Preencher o parâmetro o preenche também ali: um template que apenas o referencia recebe o valor como o converteu o primeiro template da fonte que o declara, e nada na fonte continua referenciando um parâmetro cuja declaração o binding removeu.

Nada mais no stack pode referenciar um parâmetro preenchido. Conteúdo fora da fonte — o fragmento ou o template de origem de outro componente no mesmo stack — que nomeie um parâmetro que o binding da fonte preencheu, por meio de Ref, de uma variável de Fn::Sub ou do Fn::ValueOf de uma regra, nomearia algo que o stack montado não declara mais, o que o CloudFormation recusa quando o stack é implantado. Então o build é interrompido, nomeando cada componente, seu template e o parâmetro, e o componente cujo valuesMapping o preencheu — o de uma Recipe, ou o da FeatureRecipe de uma Feature vinculada; uma Feature vinculada a um componente é nomeada por esse componente, e uma vinculada a uma fronteira pela identidade que seus recursos carregam como aggrega.ai/component-id, composta a partir do caminho da fronteira e do nome da vinculação (bfr--stack--aux para uma vinculação aux na fronteira stack). O fragmento do componente ao qual uma Feature está vinculada, ou de um componente na fronteira à qual ela está vinculada, que referencie um parâmetro que o binding da vinculação preencheu também interrompe o build. Um nome que o stack ainda declara não é afetado: onde outro componente declara ele mesmo um parâmetro com esse nome, ou um recurso o carrega como seu ID lógico, suas referências se resolvem contra essa declaração e são deixadas como estão escritas. Para repassar o valor, faça o componente que o preenche publicá-lo, declare o parâmetro no template que o referencia ou remova a chave do valuesMapping.

spec:
capability: cloudformation
implements: core/delivery-stream:1.0.0
source:
kind: git-repository
url: https://github.com/aws-cloudformation/aws-cloudformation-templates.git
ref: a0f43bc6d20813052892546f445037cf84c75b54
module_subdir: DataFirehose
valuesMapping: |
CloudWatchLogGroupRetention: {{ .values.retention_days }}
DestinationBucketName: "{{ .context.inject.env.BUCKET_NAME }}"

Só um valuesMapping preenche parâmetros. As chaves que ele escreve são os nomes de parâmetro que você pretendia para o template, então cada uma precisa nomear um parâmetro que algum template da fonte declara: uma chave que não nomeia nenhum interrompe o build, nomeando a chave e os parâmetros que cada template de fato declara — a falha que o CloudFormation relataria para um parâmetro desconhecido, relatada enquanto ainda cabe a você corrigi-la. Uma Recipe ou FeatureRecipe que não declara nenhum valuesMapping não preenche nada: os valores próprios do componente ou da vinculação chegam ao provedor com seus próprios nomes, escritos para suas outras entradas, e ficam sem ser lidos.

O que um valor é decide o que chega ao template.

  • Um literal — uma string, um número, um booleano ou uma lista deles — é escrito no template, convertido da forma como o CloudFormation converte o mesmo valor passado para o Type do parâmetro quando o stack é implantado: um Number se torna a string que um Ref a ele retorna, então 7 chega como "7"; um tipo CommaDelimitedList ou List<…> se torna uma lista de strings, aceitando uma lista ou uma string separada por vírgulas cujos membros têm os espaços removidos; todo outro tipo aceita uma única string. Um literal é verificado contra os próprios AllowedValues, AllowedPattern, MinLength, MaxLength, MinValue e MaxValue do parâmetro, e um que eles recusem interrompe o build, nomeando o parâmetro e a restrição, de modo que preencher um parâmetro não remove nenhuma verificação que o template declarou. Um padrão escrito em uma sintaxe de expressões regulares que o build não consegue ler é deixado para o CloudFormation verificar quando o stack é implantado.
  • Um valor que é inteiramente uma função intrínseca do CloudFormation chega ao ponto da referência como essa função intrínseca, para o CloudFormation avaliá-la quando o stack é implantado: um mapeamento em forma longa como {"Fn::GetAtt": [Queue, Arn]}, ou uma string que é exatamente uma forma curta — !GetAtt Queue.Arn, !Ref Bucket, !Sub … e as demais formas que o CloudFormation define. É assim que a referência publicada por outro componente chega a um parâmetro: as Recipes do CloudFormation do catálogo publicam uma referência assim como texto em forma curta, e um valuesMapping que a lê do contexto de injeção a repassa. Uma referência inserida é lida da mesma forma entre aspas ou sem elas. Entre aspas — "{{ .context.inject.env.BUCKET_NAME }}" — o mapeamento repassa a string !GetAtt Queue.Arn; sem aspas, o próprio YAML do mapeamento lê !GetAtt Queue.Arn como uma tag, e a tag é mantida com seu argumento em vez de ser descartada. Qualquer uma das duas chega ao parâmetro como a função intrínseca. Um valor que apenas começa com um ponto de exclamação, ou que não nomeia nenhuma forma curta do CloudFormation, continua sendo texto.
  • Uma referência dinâmica — {{resolve:ssm:…}}, {{resolve:ssm-secure:…}} ou {{resolve:secretsmanager:…}} — chega ao ponto da referência como está escrita, para o CloudFormation resolvê-la quando o stack é implantado, então o valor que ela nomeia nunca está no template.
  • Um valor que outro componente publica a partir de um stack diferente chega ao template como uma referência entre stacks, o mesmo Fn::ImportValue ou Fn::GetStackOutput que um fragmento recebe (veja Ligação entre stacks), em cada lugar em que o template referenciava o parâmetro.

Um parâmetro cujo tipo o CloudFormation lê do Parameter Store — AWS::SSM::Parameter::Value<…> — não tem nenhum literal que reproduza o que o CloudFormation faria com ele, então um literal associado a um deles interrompe o build; associe uma referência {{resolve:ssm:…}} ou uma função intrínseca, ou deixe-o sem associação. Uma lista associada a um parâmetro que o template nomeia como variável de Fn::Sub também interrompe o build, porque uma variável substitui uma única string. Uma chave que o valuesMapping define como null interrompe o build da mesma forma, nomeando o parâmetro, porque um parâmetro recebe um valor e null não é nenhum; para deixar um parâmetro para um valor passado quando o stack é implantado ou para o seu Default, deixe a chave dele fora do mapeamento.

Uma regra que lê um parâmetro pelo nome o mantém sem associação. Fn::ValueOf nas Rules de um template nomeia um parâmetro declarado pelo seu ID lógico em vez de por meio de Ref, e preencher o parâmetro remove sua declaração, então associar um parâmetro que uma regra lê dessa forma interrompe o build, nomeando a regra e o parâmetro.

Um literal que possa carregar um segredo é recusado; uma função intrínseca é escrita como é fornecida. Um valor escrito no template pode ser lido por qualquer pessoa que consiga ler o template do stack:

  • Um parâmetro que o template declara NoEcho aceita uma referência dinâmica ou uma função intrínseca, e um literal associado a ele interrompe o build.
  • Onde o valuesMapping lê um valor que um autor declarou sensível, nada da sua saída pode ser rastreado até o valor de que veio, então todo literal que ele associa interrompe o build. Uma referência dinâmica e uma função intrínseca que ele associa são escritas como são fornecidas — incluindo o texto dentro de uma função intrínseca. Um segredo que o mapeamento insere no texto de um Fn::Sub, por exemplo, chega, portanto, ao template como esse texto: só uma referência dinâmica mantém o próprio segredo fora do template. Onde um build assim prossegue, ele também imprime um aviso por folha declarada, tanto para o mapeamento de uma Recipe quanto para o da FeatureRecipe de uma Feature vinculada a um componente, nomeando a folha e a entidade a que pertence o mapeamento — veja A declared-sensitive value reaches the target through a values mapping (Um valor declarado sensível chega ao destino por meio de um mapeamento de values).
  • Uma referência dinâmica interrompe o build onde seu parâmetro é referenciado na propriedade UserData de um recurso, nos metadados de AWS::CloudFormation::Init ou em Outputs: o CloudFormation não resolve uma referência dinâmica nos dados de usuário do EC2 nem nesses metadados, e mostra Outputs a quem quer que leia o stack.

Toda recusa desse tipo nomeia os parâmetros e não cita nenhum valor.

Deixando recursos de fora de um template de origem

Os recursos de um template de origem são dele: os valores só chegam a ele por meio dos parâmetros que ele declara, então um template obtido de um repositório git que declara um recurso que a Release não deve criar — um bucket que o operador já fornece, uma chave que a plataforma gerencia em outro lugar — não pode ser alterado por um valor. É para isso que servem as entradas omits: de uma Recipe ou de uma FeatureRecipe. Este provedor as respeita em um template de origem e em nada mais: os fragmentos que uma entrada artifacts: escreve são renderizados sem elas.

spec:
capability: cloudformation
implements: core/store:1.0.0
source:
kind: git-repository
url: https://git.example.com/platform/templates.git
ref: v3.2.0
module_subdir: store
omits:
# The template bundles an access-log bucket; this Release logs elsewhere.
- kind: AWS::S3::Bucket
name: StoreLogs

Uma entrada nomeia um recurso pelo seu Type e pelo seu ID lógico. O kind da entrada é o Type do recurso, como AWS::S3::Bucket, e o seu name é o ID lógico do recurso, a sua chave sob Resources; ambos são comparados exatamente como escritos, e ambos precisam corresponder, então uma entrada cujo Type está certo e cujo ID lógico não está não deixa nada de fora. Um template não tem namespaces, então uma entrada que traz um namespace interrompe o build quando o componente é renderizado, nomeando a entrada; toda entrada é verificada antes que qualquer coisa seja deixada de fora.

Todo template da fonte é comparado. Uma fonte de arquivo único tem um template. Uma fonte de diretório — uma fonte obtida de um repositório git sempre é uma — tem todo arquivo terminado em .yaml, .yml, .json ou .template, e uma entrada deixa de fora todo recurso que nomeia em qualquer um deles; um arquivo carregado junto com os templates nunca é lido. O provedor informa quantos recursos cada entrada deixou de fora em todos eles, e uma entrada que não deixou nenhum de fora interrompe o build; veja An omits entry left out nothing the source rendered (Uma entrada omits não deixou de fora nada do que a fonte renderizou).

Um recurso deixado de fora some antes que qualquer outra coisa leia o template. Ele não é marcado com proveniência, não é contado entre os nomes que o stack carrega — então outro componente pode contribuir com um recurso sob o mesmo ID lógico sem que os dois se encontrem — e nunca chega ao stack montado. Todo o resto do template é escrito exatamente como seria se o template tivesse sido criado sem o recurso, e um template do qual todos os recursos são deixados de fora mantém uma seção Resources vazia.

Um recurso deixado de fora não deve continuar nomeado pelo que resta, porque o CloudFormation recusa um template que nomeia um recurso que ele não declara. Depois que os recursos são removidos, toda referência que os templates restantes ainda fazem a um deles interrompe o build, e a mensagem nomeia o template, o recurso, como a referência o nomeia e onde a referência está, como um caminho a partir da raiz do template — /Resources/Store/Properties/LoggingConfiguration/DestinationBucketName, por exemplo. Uma referência é o que a referência de templates do CloudFormation define como nomear um recurso pelo seu ID lógico, lido no corpo de cada recurso — incluindo suas propriedades, seus metadados e suas políticas — e em cada saída:

  • Ref, com o ID lógico como argumento;
  • Fn::GetAtt, como uma lista cujo primeiro item é o ID lógico, ou como uma string — !GetAtt StoreLogs.Arn — cujo texto antes do primeiro ponto é;
  • o DependsOn de um recurso, como um ID lógico ou uma lista deles;
  • cada variável de Fn::Sub, na sua forma de string e na sua forma de lista: ${StoreLogs} e ${StoreLogs.Arn} nomeiam ambas StoreLogs.

Alguns valores apenas parecem referências e não são lidos como tal. ${!StoreLogs} é texto literal, e uma variável que o mapa da forma de lista nomeia é o valor desse mapa. A Condition de um recurso e o primeiro argumento de Fn::If nomeiam uma condição, Fn::FindInMap nomeia um mapeamento, Fn::ImportValue um export de outro stack e Fn::GetAZs uma região. As seções Conditions, Mappings, Parameters e Rules não podem nomear um recurso, e a seção Metadata de nível superior do próprio template é informação que o CloudFormation armazena em vez de ler, então nenhuma delas é verificada. Um Ref ou um Fn::GetAtt cujo ID lógico é ele próprio escrito como uma função intrínseca só é válido sob a transformação AWS::LanguageExtensions, que o resolve quando o stack é implantado (veja Seções de nível superior no stack montado), então ele não nomeia nenhum recurso que a verificação possa ler e é deixado como está; o mesmo vale para uma referência a um recurso que a fonte nunca declarou.

A verificação lê juntos os templates da própria Recipe ou FeatureRecipe que declara. Eles são montados em um único stack, então uma referência a um ID lógico que outro desses templates ainda declara não é barrada. Nada mais é lido: uma referência a um recurso deixado de fora interrompe o build mesmo onde outro componente declara um recurso com esse ID lógico, e uma referência feita por qualquer outra coisa que é montada no stack — outro componente, uma Feature vinculada ou as próprias entradas artifacts: da Recipe — fica fora do que esta verificação vê, então o CloudFormation recusa o stack quando ele é implantado. Para manter uma referência, mantenha o recurso. Um valor vinculado a um parâmetro substitui apenas uma referência a esse parâmetro, então uma referência a um recurso é do próprio template e não pode ser alterada por um valor: deixe de fora também o recurso que a faz, ou remova a entrada. Uma saída não é um recurso e nenhuma entrada nomeia uma, então um recurso que as Outputs do template nomeiam não pode ser deixado de fora dele: deixá-lo de fora interrompe o build.

Anotações de destino de nuvem

Três anotações de fronteira dizem ao provedor onde um stack é implantado, para que ele possa ligar corretamente as referências entre stacks:

  • aggrega.ai/aws-account — a conta da AWS na qual o stack é implantado.
  • aggrega.ai/aws-region — a região da AWS na qual o stack é implantado.
  • aggrega.ai/aws-assume-role-arn — o ARN da função do IAM que uma leitura de stack entre contas assume para alcançar os valores exportados de um stack correspondente.

Essas anotações são opacas para o compilador — ele canaliza seus valores até o provedor sem interpretá-los (veja well-known-annotations.md). Elas são escritas na fronteira do produtor — o stack que possui o valor exportado. Uma leitura entre contas assume uma função na conta do produtor, então a conta, a região e a função que descrevem a leitura vêm todas das anotações da fronteira do produtor, não das do consumidor.

Referências dentro do stack

Quando uma aresta uses conecta dois componentes que caem na mesma fronteira — o mesmo stack — o valor consumido é ligado como um Fn::GetAtt contra o ID lógico do recurso do produtor dentro do único template. O valor provides do produtor flui para a entrada renderizada do consumidor como uma referência nativa dentro do stack; nenhum export ou import é necessário. O fragmento do consumidor pode escrever esse valor sem aspas — Value: {{ .context.inject.env.DB_HOST }} — ou entre aspas — Value: "{{ .context.inject.env.DB_HOST }}": de qualquer forma o template lê !GetAtt Db.Endpoint.Address como a função intrínseca, porque uma string que é exatamente uma forma curta chega ao stack como essa função intrínseca em um fragmento assim como em um valuesMapping. O exemplo aws-rds-and-ecs-service mostra isso em uma definição de tarefa do Amazon ECS que lê o endereço de uma instância do RDS em um único stack.

Ligação entre stacks

Quando uma aresta uses cruza de uma fronteira para outra — os dois componentes são montados em stacks diferentes — a referência não pode ser um valor simples, porque o valor produzido não existe até que o stack do produtor seja implantado. O provedor a liga como uma referência entre stacks do CloudFormation. O stack produtor publica o valor como um Output do stack com um Export sob um nome de export determinístico (derivado da release, da fronteira, do componente e da chave fornecida). O stack consumidor o lê com uma de duas funções intrínsecas, escolhida comparando o posicionamento declarado das duas fronteiras:

  • Fn::ImportValue — o caso de mesma conta e mesma região. O CloudFormation resolve o import contra o nome de export correspondente dentro da conta e da região.
  • Fn::GetStackOutput — uma leitura genuína entre contas ou entre regiões. O consumidor lê diretamente a saída do stack produtor, assumindo a função aws-assume-role-arn da fronteira do produtor na conta e na região do produtor.

Semântica de detecção. O provedor encaminha para Fn::GetStackOutput somente quando ambos os endpoints declaram um posicionamento (conta/região) e esses posicionamentos diferem. Em todos os outros casos — nenhum declara, apenas um declara, ou ambos declaram o mesmo posicionamento — ele usa Fn::ImportValue. Esta é uma regra conservadora: uma leitura entre stacks na mesma conta continua sendo um import simples, e a função intrínseca de leitura direta fica reservada para um salto real entre contas ou entre regiões.

O stack produtor sempre publica o Export, mesmo quando um determinado consumidor o lê entre contas por meio de Fn::GetStackOutput. Um export não usado é inerte, e publicá-lo incondicionalmente mantém o template do produtor independente de como cada consumidor escolhe ler o valor.

Vários consumidores de um valor leem um único export. Quando mais de um componente lê o mesmo valor fornecido através de uma fronteira — dois consumidores em um stack, ou consumidores em vários stacks — o stack produtor publica o Export desse valor uma única vez, e cada consumidor lê o único nome: cada Fn::ImportValue importa o mesmo export, e um consumidor posicionado em outra conta ou região lê a mesma saída por meio de Fn::GetStackOutput. Um consumidor que também lê um valor que nenhum outro consumidor lê acrescenta apenas o export desse valor.

O exemplo aws-rds-and-ecs-service constrói o caso de mesma conta: o stack de uma instância do RDS exporta cada entrada que a aresta de um servidor consome, e o stack do servidor lê cada uma de volta com Fn::ImportValue.

Nota de versão. Fn::GetStackOutput é uma função intrínseca nativa do CloudFormation. Uma referência entre contas renderizada com ela requer ferramentas do CloudFormation que reconheçam a função intrínseca. O caminho de mesma conta usa Fn::ImportValue, que está disponível em todo lugar.

Um valor lido da conexão em vez de injetado

A Recipe de um consumidor pode ler os valores de um produtor diretamente da conexão, por meio de .context.uses.<alias>.provides, em vez de recebê-los pelo bloco inject da conexão. Através de uma borda de stack, essa leitura é ligada da mesma forma que um valor injetado:

  • Um valor que é uma função intrínseca do CloudFormation — uma tag de forma curta como !GetAtt Db.Endpoint.Address, ou um Ref ou um mapeamento Fn:: de forma longa — nomeia algo que só o stack do produtor declara, então o consumidor recebe a mesma referência entre stacks que um valor injetado recebe: o stack produtor publica um Export para essa chave, e o consumidor o lê com Fn::ImportValue, ou com Fn::GetStackOutput onde as duas fronteiras declaram posicionamentos que diferem.
  • Um valor que é texto simples — uma porta, um protocolo, um nome de banco de dados — significa o mesmo em qualquer um dos stacks, então o consumidor recebe o próprio valor e nenhum export é publicado para ele. Ele chega na forma em que o CloudFormation o lê: um valor escrito inteiro é renderizado como seria sem a fronteira, e um valor com formato de número escrito entre aspas chega como número.

Se um valor é uma função intrínseca é decidido por este provedor, lendo o valor da forma como lê o próprio bloco provides do produtor. O compilador entrega o valor como a Recipe do produtor o escreveu e não o interpreta.

Um template só pode copiar um valor assim. Ele pode escrever o valor inteiro, ou dentro de uma string maior, ou passá-lo por uma função que o deixa como está, como quote. Uma comparação, uma ramificação, um comprimento ou uma função que altera o valor — eq, if, len, upper — seria decidido contra algo diferente do valor, porque em uma conexão assim o template recebe um substituto que o provedor troca depois que ambos os stacks são montados. Em vez disso, o build é interrompido, nomeando o template e cada valor que ele leu, com a conexão da qual o leu e o componente em cada ponta; ramifique sobre um valor do próprio componente consumidor. O mesmo vale para o injectMapping de uma FeatureRecipe vinculada e para uma FeatureRecipe de escopo de fronteira que lê as conexões da fronteira. Um valor escrito dentro de uma string maior também esbarra no limite próprio do provedor: uma referência entre stacks só pode aparecer como um valor inteiro, então uma função intrínseca escrita dentro de uma string maior interrompe o build, como acontece com um valor injetado.

Como um nome de export é construído

As quatro partes são unidas com um hífen duplo, e cada parte é escrita nas letras, dígitos e hifens de que um nome de export é feito. Uma letra ou um dígito é carregado como escrito, e o mesmo vale para um hífen dentro de uma parte — payments-db continua payments-db. Qualquer outro caractere é escrito como um escape curto que começa com -z: uma barra como -zs, um sublinhado como -zu, um ponto como -zd. Uma parte sem nenhum valor é escrita -ze. Um nome de stack é construído da mesma forma a partir da release e da fronteira.

Assim, o export que publica host do componente db, na fronteira cujo diretório de saída sob dist/ é stack-a/cloudformation, da release orders, é:

aggrega--orders--stack-a-zscloudformation--db--host

A releitura é inequívoca, e esse é o objetivo, não um detalhe de cortesia: como uma parte nunca contém dois hifens seguidos e nunca termina com um, os hifens duplos são sempre as junções. Dois conjuntos diferentes de partes, portanto, sempre produzem dois nomes diferentes. payments-db e payments_db chegam a dois exports separados em vez de convergirem em um, e um hífen na borda de uma parte não pode ser lido como pertencente à sua vizinha.

Em relação a quê um nome de export é único, e onde isso termina

Dentro de um build, um nome de export identifica exatamente uma release, uma fronteira, um componente e uma chave fornecida — dois deles nunca convergem em um mesmo nome, então um build não pode perder um valor exportado atrás de outro.

O CloudFormation exige ainda que um nome de export seja único entre tudo o que já está implantado na conta e na região em que o stack cai. Essa é uma propriedade da implantação, e não do build, e fica além do que qualquer derivação em tempo de build consegue alcançar: o compilador não se autentica na AWS, não a consulta e não pode ler a saída de outro build, então nada calculado antecipadamente pode observar o que já está implantado ali.

O que leva a distinção através dessa linha é a identidade da release que abre cada nome de export e de stack. Duas implantações que compartilham uma conta e uma região mantêm seus exports separados por serem publicadas com nomes diferentes — essa é a alavanca que você tem nas mãos, e o motivo pelo qual a identidade da release abre o nome em vez de fechá-lo.

Uma entrada de Outputs pode declarar seu próprio nome de export

O bloco Outputs: de uma Recipe é CloudFormation escrito pelo autor, e uma entrada nele pode trazer seu próprio Export: com um Name:. Esse nome chega ao stack montado exatamente como está escrito — o provedor não o reescreve, não lhe acrescenta prefixo e não exige que ele se pareça com um derivado.

Normalmente não há mais nada a dizer sobre isso. Um nome de export escrito pelo autor que não corresponde a nenhum nome que o provedor deriva é publicado ao lado dos derivados e nunca é apontado. Escrevê-lo é suportado; só uma coincidência não é.

O build é interrompido quando um nome de export escrito pelo autor é igual a um que o provedor deriva para um vínculo entre fronteiras no mesmo build. Ambas as declarações chegariam ao template montado, deixando um nome de export declarado duas vezes em um mesmo stack — e um nome de export precisa ser único, então as duas não podem coexistir. A interrupção informa o nome de export derivado e as quatro partes a partir das quais ele foi construído, para que você veja qual vínculo o produziu, e nomeia a saída do stack sob a qual está a declaração escrita pelo autor, marcada como um nome que o provedor monta, e não um que uma Recipe escreveu. O nome de export é o termo a procurar nas suas Recipes. A entrada escrita pelo autor o escreve exatamente como a interrupção — é essa identidade que faz das duas uma colisão —, então ele é a única string que aparece tanto na mensagem quanto nos seus próprios arquivos. Renomear o nome de export que essa entrada declara elimina a interrupção, assim como remover o bloco Export: dessa entrada e deixar a ligação entre stacks publicar o export por conta própria.

A verificação tem escopo de build, e seu escopo é um stack. Ela compara os nomes de export que um stack montado declara com os nomes que o provedor deriva para os vínculos entre fronteiras que publicam nesse mesmo stack — a comparação que o build consegue fazer a partir do que montou. Dois stacks não são comparados entre si. E o que um nome escrito pelo autor encontra entre os exports já implantados em uma conta e uma região é uma propriedade da implantação, que fica além do que qualquer derivação em tempo de build consegue alcançar, pelo motivo exposto em Em relação a quê um nome de export é único, e onde isso termina: o compilador não se autentica na AWS, não a consulta e não pode ler a saída de outro build. Um nome de export escrito como função intrínseca em vez de como string simples fica do outro lado da mesma linha — ele é resolvido no momento da implantação, e nada aqui avalia uma função intrínseca, então não há nenhum nome para o build comparar.

O build também é interrompido quando a saída na qual um vínculo entre fronteiras publica já traz um Export que o vínculo não escreveu. Essa saída é a que o provedor monta para a chave fornecida que um consumidor lê, então uma Recipe cujo bloco Outputs: escreve uma entrada sob essa mesma chave, com um Export: próprio, coloca seu export exatamente onde vai o do vínculo. A menos que o nome desse export seja exatamente o que o provedor deriva — caso em que ele é o próprio export do vínculo e todo consumidor o importa —, os dois não podem coexistir ali: escrever o export do vínculo sobrescreveria o seu, e manter o seu deixaria todo consumidor importando um nome que o vínculo não publicou. A interrupção informa o nome de export derivado e as quatro partes a partir das quais ele foi construído, e diz o que encontrou nessa saída: o nome de export que a entrada declara, um nome escrito como função intrínseca, um bloco Export: que não nomeia nada, ou um Export: escrito como valor simples em vez de como bloco. Remover o bloco Export: dessa entrada a elimina, e a ligação entre stacks então publica o export que todo consumidor importa.

Ordem de implantação

O valor syncWave: de uma fronteira de uma Release ordena o provisionamento do stack no qual essa fronteira é montada. Cada componente da fronteira herda a onda da fronteira e, onde várias fronteiras são resolvidas para o mesmo diretório de saída — de modo que seus fragmentos são montados em um único template —, o stack contém mais de uma onda e o provedor expressa a ordem entre elas como DependsOn.

Cada recurso nomeia todos os recursos da onda imediatamente anterior que tenha recursos, e nenhuma onda anterior a essa. O CloudFormation encadeia o resto: um recurso na onda 2 depende da onda 1, que depende da onda 0, então toda a sequência fica ordenada enquanto a lista própria de cada recurso permanece do tamanho de uma onda, e não do stack inteiro. As ondas não precisam ser contíguas, e valores negativos são comuns — -1 é uma escolha frequente para um bucket ou uma função que o resto do stack lê. A onda mais baixa não nomeia nada, porque nada a precede.

O que a ordem é: ordem de criação e, ao contrário, ordem de exclusão. O CloudFormation opera sobre os recursos em paralelo na medida do possível, e DependsOn anula esse paralelismo para operar sobre os recursos nomeados em uma ordem declarada. O atributo rege as duas direções, então uma onda que cria um recurso antes também o exclui depois — o sequenciamento correto da desmontagem vem com a ordem, sem precisar de mais nada.

Não é uma ordem de prontidão. Um template de stack não expressa nenhuma noção de um recurso estar operacional, então nada aqui espera que um fique pronto — apenas que o CloudFormation termine de criá-lo. Essa é uma diferença real em relação à mesma onda no compose, onde um serviço que declara um healthcheck é aguardado até informar que está saudável: o compose tem uma primitiva de prontidão pela qual esperar e um template de stack não tem nenhuma. A ordem de criação é o que este destino oferece, e dizê-lo claramente é mais útil do que uma ressalva presa a uma promessa que ele não pode cumprir.

Um DependsOn escrito pelo autor é estendido, nunca substituído. Um fragmento que declara sua própria restrição de ordem a mantém: as entradas que ele escreveu ficam primeiro, na ordem em que as escreveu, e as entradas da onda vêm depois. Ambos os requisitos valem e nenhum esconde o outro. Tanto um ID lógico único quanto uma lista são lidos, e o valor mesclado é emitido como lista, que é a única grafia que funciona para quantas entradas a mesclagem produzir.

Um stack cujos recursos carregam todos uma mesma onda não ganha nada com isso. O mesmo vale para uma Release que não declara nenhum syncWave: cada contribuidor carrega o valor padrão do campo, 0, o template montado contém uma única onda, e a saída é exatamente a que seria se o provedor não expressasse nenhuma ordem de ondas.

A ordem entre dois stacks não é expressável, e não é aproximada. DependsOn nomeia um recurso dentro do mesmo template, e componentes que são montados em outro stack ficam fora dele. Assim, uma onda ordena cada recurso do stack no qual é montada e nada além dele. Sequenciar dois stacks é responsabilidade do operador, da mesma forma que uma referência entre stacks é uma resolução no momento da implantação, e não no momento do build.

A ordem que as ondas não expressam continua a cargo do próprio CloudFormation, e as referências entre recursos já carregam boa parte dela: um Fn::GetAtt sobre um recurso do produtor diz ao CloudFormation para criar esse recurso primeiro. Um fragmento que precisa de uma restrição que nem as referências nem as ondas implicam escreve DependsOn por conta própria, que é o caso que a mesclagem acima preserva.

Determinismo

Com as mesmas entradas, o provedor emite um template de stack idêntico byte a byte entre execuções: IDs lógicos, chaves de saída, nomes de export e ordem dos recursos são todos determinísticos, então um template de stack do CloudFormation gera diffs limpos na revisão GitOps.