Provider CloudFormation
O fornecedor 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 fornecedor é montado numa única stack, emitida como um só template em JSON puro que usa funções intrínsecas em forma longa. Uma fronteira torna-se, por isso, uma stack no caso comum — e duas fronteiras cujo directory: se resolve para o mesmo caminho são montadas em conjunto numa única stack, partilhando os nomes desse template. Como qualquer fornecedor do Aggrega, funciona offline e é hermético — uma compilação do Aggrega é uma compilação antecipada, pelo que o fornecedor nunca chama a AWS, nunca resolve identificadores gerados pela conta e nunca executa o CloudFormation. Os 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 implementação.
Recipes de fragmentos montadas numa stack
Uma Recipe cloudformation escreve um fragmento — os recursos do CloudFormation com que um único componente contribui — em vez de um template inteiro. Quando os componentes de uma fronteira são renderizados, o fornecedor monta cada fragmento do grupo de despacho num único template de stack: os recursos são fundidos sob um único mapa Resources, os valores provides de cada componente surgem como Outputs da stack, e as restantes secções de nível superior do template são tratadas uma a uma em Secções de nível superior na stack montada. São aceites duas formas de autoria:
- Entrada de fragmentos (artefactos). Uma Recipe escreve fragmentos de recursos diretamente; o fornecedor normaliza-os para JSON puro com funções intrínsecas em forma longa e funde-os na stack montada.
- Entrada proveniente de uma fonte. Uma Recipe referencia um template do CloudFormation existente (YAML ou JSON); o fornecedor normaliza-o para JSON em forma longa e valida a sua estrutura antes da montagem, preenche os parâmetros que o template declara a partir do
valuesMappingda Recipe — ver Valores para os parâmetros de um template de origem — e deixa de fora qualquer recurso que as entradasomits:da Recipe indiquem — ver 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 no momento da compilação — o compilador não pode resolver um valor que só existe depois de a stack ser implementada, e avaliar um quebraria o contrato de compilação antecipada.
Uma Feature anexada a um componente contribui para a mesma stack
Uma Feature anexada a um componente contribui com os seus recursos para a stack na qual o seu componente anfitrião é montado, nos mesmos termos que a própria Recipe do componente anfitrião. Não há nenhum template separado ao lado: a stack montada é a totalidade do que este fornecedor emite para um diretório de saída, pelo que os recursos de uma Feature anexada ou estão nessa stack ou não são de todo implementados. Desanexar a Feature remove exatamente esses recursos e deixa intactos os do próprio componente anfitrião.
Como acabam na stack montada, partilham os nomes dela. Os IDs lógicos dos recursos de uma Feature anexada ficam no mesmo espaço que os do componente anfitrião e que os de qualquer outra Feature anexada ao lado dela, pelo que Nomes na stack montada se aplica a eles sem alterações. Onde dois contribuidores se encontram num mesmo nome, a interrupção indica o componente e a chave sob a qual a Feature está anexada, para que ambas as extremidades da colisão possam ser pesquisadas nos próprios ficheiros.
As saídas de uma Feature anexada são publicadas sob o nome do seu componente anfitrião, e os IDs lógicos dos seus recursos não. As duas metades da stack são nomeadas segundo regras diferentes, pelo que respondem a isto de forma diferente. O ID lógico de um recurso é emitido exatamente como a FeatureRecipe o escreveu, tal como o de qualquer Recipe. Uma saída é nomeada a partir do componente que publica e da entrada em conjunto — e, para uma Feature anexada a um componente, o componente que publica é o anfitrião: uma Feature anexada a payments-db que publica alarm chega a paymentsXzhdbXXalarm, o mesmo nome a que chegaria se o componente anfitrião tivesse publicado essa entrada ele próprio. Assim, um nome de entrada que o anfitrião também publica encontra o do anexo num mesmo nome de saída, e a compilação é interrompida indicando o componente e a chave sob a qual a Feature está anexada, 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 — mantém-nos afastados dos do anfitrião.
Cada recurso com que uma Feature contribui mantém, na proveniência que a compilação escreve nele, a identidade composta para esse anexo em vez da do componente anfitrião, para que os dois continuem distinguíveis dentro de uma stack para a qual ambos contribuíram. Etiquetas e anotações explica como essa identidade é construída.
Secções de nível superior na stack montada
Vários componentes são montados numa única stack, pelo que a montagem tem de dar conta de cada secção de nível superior que um template do CloudFormation admite — incluindo Globals e Hooks, as duas secções que uma transformação alojada pelo CloudFormation acrescenta à linguagem de templates. Cada uma cabe em exatamente um dos grupos abaixo, e uma chave de nível superior que um componente escreve e que não é secção nenhuma recebe um aviso que nomeia o componente e a chave, para que nada seja descartado sem ser dito.
Montados sob nomes a que o fornecedor dá um âmbito, ou lidos tal como estão escritos. Resources e Outputs, que Nomes na stack montada trata na íntegra. AWSTemplateFormatVersion é escrito pelo fornecedor em vez de ser lido de algum componente: a linguagem de templates admite um único valor para ele, pelo que não há nada que um componente tenha de decidir.
Transportados com exatamente os nomes que escreveu. Parameters, Mappings, Conditions, Metadata e Rules. Cada uma destas secções é um mapa com chaves que escolheu, pelo que as entradas de cada componente chegam à stack montada 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 juntamente com eles. Cada uma é transportada por si, porque cada uma é escrita por si: 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 um parâmetro dentro de um mapeamento.
Uma mesma palavra abrange aqui dois sítios diferentes, e só o primeiro é seu. O Metadata na lista acima é a secção de nível superior própria do template, um mapa de nomes que escolheu. Um recurso individual também tem um atributo Metadata próprio, e é aí que a compilação escreve a proveniência — sob uma única chave reservada aggrega.ai/, acrescentada ao lado de tudo o que lá tiver escrito em vez de o substituir. Assim, uma entrada de proveniência que surge dentro de um recurso não é algo que tenha escrito nem algo que a secção de nível superior tenha transportado.
Parameters, Mappings, Conditions e Rules nomeiam as suas entradas com um ID lógico. Como o fornecedor transporta um nome exatamente como foi escrito, o alfabeto que um ID lógico admite chega também a estas secções: um nome numa das quatro que contenha algo além de letras e dígitos interrompe a compilação — veja-se Um nome de secção transportado fora do alfabeto interrompe a compilação. O fornecedor não sujeita os nomes da secção Metadata de nível superior a esse alfabeto: nomeiam informação que está a ser guardada e não algo que o template endereça.
Dois componentes que declaram nomes diferentes numa destas secções chegam ambos. Dois que declaram um mesmo nome com conteúdo idêntico fundem-se numa única entrada e a compilação prossegue. Dois que declaram um mesmo nome com conteúdo diferente interrompem a compilação, nomeando a secção, o nome e ambos os componentes — porque, de outro modo, um dos dois corpos seria descartado, deixando o componente que o escreveu com uma declaração que a stack não transporta. É a mesma conciliação que seguem os nomes de recursos e de saídas, e mudar o nome de qualquer um dos dois resolve-a.
Nomeados em vez de transportados. Description é uma única afirmação sobre um template inteiro e não um mapa de nomes que escolheu, pelo que uma montagem que recorre a vários componentes não tem resposta para ela: duas descrições são duas respostas a uma mesma pergunta e nenhuma delas é a da stack. Hooks só é lido pela transformação AWS::CodeDeployBlueGreen, que a stack montada nunca transporta (ver abaixo). A stack montada não transporta, portanto, nenhuma das duas secções, e cada componente que escreveu uma delas recebe um aviso que nomeia o componente e a secção. O mesmo acontece com 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 silencia-o juntamente com o resto 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 implementar o que quer que seja, pelo que o Transform da stack montada é a união das transformações que os seus componentes declaram — as de um template de origem tal como as de um fragmento — na ordem que o CloudFormation documenta: uma macro definida pela conta antes das transformações que o CloudFormation aloja, 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 pela ordem em que os componentes as declaram pela primeira vez, pelo que os mesmos componentes dão a mesma stack. Uma transformação escreve-se como cadeia de caracteres e várias como lista. Uma stack com um único componente, que declara o seu Transform num template ou fragmento, mantém-no exatamente como foi escrito onde quer que a tabela abaixo o transporte, e uma stack cujos componentes não declaram nenhuma não transporta nenhuma. A transformação de um componente não gera aviso: é transportada, ou a compilação é interrompida com o seu nome.
Como uma transformação processa o template inteiro, transportar uma muda a forma como o conteúdo de todos os outros componentes é implementado, a menos que o que ela faz esteja confinado ao conteúdo escrito para ela. Assim, cada transformação recebe o tratamento que a própria documentação do CloudFormation sobre ela suporta, e uma combinação que a stack não consegue transportar interrompe a compilação, nomeando a transformação e cada componente na stack:
| transformação | na stack montada |
|---|---|
AWS::Serverless-2016-10-31 | transportada, com os Globals do componente que a declara. Interrompe a compilação 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::LanguageExtensions | transportada sozinha, ou ao lado de AWS::Serverless-2016-10-31 do mesmo componente. Interrompe a compilação ao lado do conteúdo serverless de outro componente, porque a transformação serverless nomeia o que gera de forma diferente depois de as extensões de linguagem terem resolvido os seus valores. |
AWS::SecretsManager-2020-07-23, AWS::SecretsManager-2024-09-16 | transportadas: processam apenas os agendamentos de rotação que as pedem. |
AWS::ServiceCatalog | transportada para uma stack com um único componente. Ao lado de qualquer outro, interrompe a compilação, porque substitui o seu padrão de referência em qualquer ponto do template. |
AWS::CodeDeployBlueGreen | interrompe a compilação, mesmo sozinha: o CloudFormation recusa Outputs e Fn::ImportValue em qualquer ponto de um template que a declare, e a stack montada transporta as saídas que os seus componentes publicam. |
AWS::Include | interrompe a compilação, mesmo sozinha: insere conteúdo obtido do S3 quando a stack é implementada, que a compilação não consegue ler. |
| uma macro definida pela conta | transportada para uma stack com um único componente. Ao lado de qualquer outro, interrompe a compilação, porque o que faz ao resto do template é desconhecido para a compilação. |
Dois componentes que declaram um mesmo par de transformações em ordens opostas também interrompem a compilação, nomeando ambas as ordens e ambos os componentes, uma vez que a stack as executa numa única ordem. Um componente que precisa de uma transformação que a stack não consegue transportar fica numa fronteira própria.
Nomes na stack montada
Um ID lógico do CloudFormation é único dentro de um template e admite apenas letras e dígitos, e todos os componentes que são montados nesse template partilham os seus nomes — incluindo componentes de uma segunda fronteira, quando ambas se resolvem para o mesmo diretório de saída. Assim, cada nome pelo qual a stack endereça algo tem de ser distinto entre todos os componentes que para ele contribuíram, e o conjunto de contribuidores nem sempre é uma única fronteira.
Os IDs lógicos de recurso vêm da Recipe. O fornecedor emite-os exatamente como foram escritos e não reescreve nenhum, pelo que o nome que se lê no template montado é o nome que a Recipe escreveu. As Recipes do CloudFormation da biblioteca padrão derivam-no do próprio nome da instância do componente, lendo os separadores desse nome como limites de palavra: a instância payments-db nomeia o seu recurso PaymentsDb. Duas instâncias do mesmo tipo descrevem, portanto, dois recursos em vez de disputarem um.
Os nomes de saída têm o âmbito do componente que os publicou. Cada entrada de provides surge como uma saída nomeada pelo componente que publica e pela entrada em conjunto — o componente payments-db a publicar host surge como paymentsXzhdbXXhost — pelo que 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 se junta à stack. Um consumidor entre stacks na mesma conta e região importa pelo nome de export e não por este, pelo que o nome de export não é afetado; uma leitura entre contas ou entre regiões nomeia esta saída, tal como o fornecedor a escreve pelo utilizador (veja-se Ligação entre stacks).
Como é construído um nome de saída
Um ID lógico não admite nenhum caractere separador, pelo que um nome construído a partir de algo que se escreveu tem de transportar esses separadores de alguma forma. Descartá-los implicaria perda: payments-db e payments_db são dois componentes, e um nome que descartasse a pontuação não identificaria nenhum deles. Por isso, o fornecedor codifica antes o que o alfabeto recusa, escrevendo cada caractere recusado por extenso em caracteres que o alfabeto admite.
O esquema reserva um caractere com que abrir uma sequência de escape — um X maiúsculo — e escreve tudo o resto tal como foi digitado, maiúsculas incluídas. Só a maiúscula é reservada, pelo que o x minúsculo de um nome como nginx-proxy é transportado tal como foi escrito:
| o que foi escrito | o que se torna | porquê |
|---|---|---|
uma letra ou dígito, exceto X | o próprio caractere | o alfabeto admite-o |
- | Xzh | o alfabeto recusa o hífen |
_ | Xzu | o alfabeto recusa o sublinhado |
. | Xzd | o alfabeto recusa o ponto final |
/ | Xzs | o alfabeto recusa a barra, que uma identidade de componente aninhada transporta |
X | Xzx000058 | reservado para abrir uma sequência de escape, pelo que é escrito por extenso pelo seu ponto de código |
| qualquer outra coisa | Xzx e o ponto de código do caractere | uma única regra abrange todos os caracteres restantes |
| o encontro das duas metades | XX | dois caracteres de abertura seguidos, que nenhuma das metades pode conter |
A releitura é inequívoca, e esse é o objetivo e não um pormenor. Um X só é mantido como tal quando o caractere a seguir é um que o alfabeto admite, pelo que uma metade codificada nunca termina com um nem contém dois seguidos — o que deixa XX livre para significar a junção, e apenas a junção.
Assim, três nomes que diferem apenas no sítio onde fica a sua pontuação mantêm-se separados:
component payments-db publishing host → paymentsXzhdbXXhostcomponent payments_db publishing host → paymentsXzudbXXhostcomponent payments publishing db-host → paymentsXXdbXzhhostOs nomes são mais longos e menos imediatamente legíveis do que o nome de componente que foi escrito, e essa é a contrapartida. Um nome que identifica exatamente uma entrada vale mais do que um mais curto que não identifica nenhuma de duas — e uma saída é endereçada pelo nome de export em vez de se digitar este, pelo que o que custa é um segundo olhar ao ler um template emitido.
Os IDs lógicos de recurso seguem uma regra diferente, porque o fornecedor não os constrói: 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 o seu recurso PaymentsDb — e essa derivação descarta os separadores, pelo que dois nomes de instância que diferem apenas na pontuação, ou apenas nas maiúsculas e minúsculas de uma letra, derivam ainda assim um único nome de recurso. A compilação é interrompida, nomeando cada instância que chegou ao nome juntamente com o nome em que foram parar, em vez de emitir um único recurso onde foram declarados dois componentes. Todas são nomeadas, e não apenas algumas, porque nada numa colisão torna a derivação de uma instância a pretendida. Mudar o nome de todas menos uma resolve a interrupção.
Um ID lógico de recurso fora do alfabeto interrompe a compilação
A unicidade e o alfabeto são dois requisitos separados, e um conjunto de nomes pode satisfazer o primeiro e falhar o segundo. Como o fornecedor emite um ID lógico de recurso exatamente como a Recipe o escreveu, o ID que uma Recipe escreve tem de ser um que um template do CloudFormation consiga conter por si só: letras e dígitos, e mais nada.
É aqui que um nome derivado e um nome passado tal como está seguem caminhos diferentes. Um nome de saída é construído pelo fornecedor, que codifica o componente que publica e a entrada, pelo que um nome de saída fica dentro do alfabeto independentemente de como se escreva qualquer uma das metades. Um ID lógico de recurso é passado tal como está, pelo que o que quer que a Recipe tenha escrito é o que o template recebe.
Isso torna-o também uma restrição sobre os nomes dos 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 se direcione para este fornecedor através de uma Recipe assim é, portanto, nomeado apenas com letras e dígitos — paymentsdb em vez de payments-db — e qualquer outra coisa interrompe a compilação.
A interrupção nomeia o contribuidor cuja Recipe escreveu o ID, o próprio ID e cada caractere nele que não pode lá estar, e indica o que se pode escrever em vez disso. Duas coisas resolvem-na, e a primeira é a que está sempre disponível:
- Fazer a Recipe escrever um ID lógico próprio em vez de passar um nome diretamente. As Recipes do CloudFormation da biblioteca padrão seguem este caminho — leem os separadores do nome da instância como limites de palavra, pelo que a instância
payments-dbnomeia o seu recursoPaymentsDbe o nome de componente escolhido mantém-se. Derivar um ID desta 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 passa de facto um nome diretamente, mudar o nome do que ela passa para apenas letras e dígitos. Para a Recipe própria de um componente, trata-se do nome do componente. Uma Feature anexada a um componente nomeia os seus recursos a partir da sua própria FeatureRecipe, pelo que mudar o nome do componente anfitrião não os alcança — é o ID que essa Recipe escreve que tem de mudar.
O fornecedor recusa; não repara às escondidas. Reescrever o ID em nome do autor 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, pelo que mudar um não é uma mudança de nome — endereça um recurso diferente. Um ID que o fornecedor tivesse substituído apontaria para outro sítio que não o recurso já implementado sob o ID escrito, e a substituição é uma que nunca foi pedida e que teria de ser descoberta a partir do template emitido. Uma compilação que é interrompida nomeia o problema enquanto ainda cabe ao autor corrigi-lo.
Um nome de secção transportado fora do alfabeto interrompe a compilação
Os IDs lógicos de recurso não são os únicos nomes que o fornecedor transporta exatamente como foram escritos. Parameters, Mappings, Conditions e Rules também nomeiam as suas entradas com um ID lógico, e cada uma das quatro chega à stack montada com o nome que o seu autor escolheu. O requisito é, portanto, o mesmo, em mais quatro superfícies: o nome tem de ser um que um template do CloudFormation consiga conter por si só — letras e dígitos, e mais nada — e qualquer outra coisa interrompe a compilação.
Há uma consequência que vai além da secção que transporta o nome, e é a razão pela qual isto interrompe a compilação em vez de emitir um aviso. Estes 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 retira, portanto, do template implementável a referência que aponta para ele juntamente com a própria declaração, pelo que um único nome escrito deixa ambos fora de alcance de uma só vez — e, sem a interrupção, isso é descoberto no momento da implementação, por quem está a implementar e não por quem escreveu o nome.
A interrupção nomeia o contribuidor cuja Recipe escreveu o nome, a secção em que foi escrito, o próprio nome e cada caractere nele que não pode lá estar. A secção é o termo a procurar nas Recipes: estes nomes são transportados exatamente sob a secção em que foram escritos, pelo que é a única palavra que aparece tanto na mensagem como nos próprios ficheiros. Mudar o nome da entrada para apenas letras e dígitos resolve-a, e esse é todo o remédio — um ID lógico de recurso oferece a alternativa de a Recipe derivar um ID em vez de passar um nome diretamente, e aqui não há nada a derivar, porque o nome na secção é o que foi escrito.
Só os nomes próprios de uma secção estão sujeitos ao alfabeto, nunca as chaves dentro de uma entrada. As chaves de segundo nível de um mapeamento escolhem-se 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 a 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 escritos em separado mantêm-se separados
Três tipos de nome de entrada estão próximos o suficiente para se encontrarem num único nome de saída, e nenhum deles é exótico. Como as duas metades são codificadas em vez de compactadas, e se encontram numa 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-hostcomodb_hostchega adbXzhhostedbXzuhost. - Entradas que diferem apenas nas maiúsculas e minúsculas de uma letra.
hosteHostchegam ahosteHost, porque uma letra é transportada tal como foi escrita, em maiúscula ou minúscula. - Entradas que se encontram através da junção. O Component
payments-dba publicarhostchega apaymentsXzhdbXXhost; o componentepaymentsa publicardb-hostchega apaymentsXXdbXzhhost.
Duas entradas continuam a encontrar-se onde nomeiam realmente uma mesma coisa. O nome de saída é construído a partir do componente que publica e da entrada, pelo que tudo o que partilha ambos chega a um único nome, seja qual for a codificação. O caso mais provável de se encontrar é uma mesma Feature anexada duas vezes a um único componente: um anexo publica sob o seu anfitrião, pelo que dois anexos de uma Feature num componente publicam ambos alarm-id a partir de payments-db, e não há nada no par que permita distingui-los. A compilação é interrompida em vez de emitir uma única saída onde foram escritas duas, nomeando o componente e a chave de anexo que cada lado transportava, de modo que ambas as extremidades podem ser procuradas nos próprios ficheiros. A solução é anexar a Feature uma única vez, ou usar uma Feature cujos nomes de entrada publicados se leiam como próprios desse anexo.
Isto aplica-se quer as duas entradas transportem o mesmo valor, quer não. Duas entradas com o mesmo valor descrevem ainda assim duas saídas que um autor pediu, pelo que fundi-las numa só deixaria uma das duas saídas escritas ausente da stack.
Um nome que uma Recipe compõe num template não é abrangido por isto
A codificação acima é a do fornecedor, e aplica-se aos nomes de saída que o fornecedor constrói. Não está disponível dentro de um template de Recipe, e um nome que um template compõe não transporta, portanto, nenhuma das suas garantias. Dizê-lo claramente importa porque o risco é invisível a partir do interior do template: a compactação ali disponível lê o seu argumento como palavras e descarta tudo o que está entre elas, pelo que unir dois valores antes de os compactar perde a junção juntamente com a pontuação.
Uma FeatureRecipe que nomeia um recurso a partir de uma instância e de uma chave de anexo, unidas por um espaço e depois compactadas, é a forma a vigiar — app com cache e app-cache com nada são ambos compactados em AppCache, e os dois colidem antes de qualquer propriedade da compactação se aplicar. Duas coisas mantêm um nome assim distinto, e ambas cabem ao autor e não ao fornecedor:
- Manter as partes compostas em letras e dígitos, para que nada seja descartado e nada tenha de ser distinguido.
- Não unir dois valores que possam conter cada um o separador do outro. Onde um nome tiver de transportar duas partes, fazer de uma delas um literal fixo que a outra não possa conter.
Onde um nome composto de facto colide, colide como ID lógico de recurso e não como nome de saída, pelo que a interrupção que se encontra é a dos nomes de recurso descrita acima.
Uma chave escrita duas vezes num mesmo mapeamento interrompe a compilação
Um fragmento do CloudFormation é lido como um mapeamento, e um mapeamento contém um valor por chave, pelo que uma chave escrita duas vezes manteria o corpo que chegou em último lugar 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 na stack.
Em vez disso, a compilação é interrompida, nomeando a chave repetida e as duas linhas em que foi escrita. Esta é uma regra sobre o fragmento inteiro e não uma regra sobre os nomes da stack: aplica-se a qualquer mapeamento no fragmento, incluindo as Properties de um recurso. A forma mais comum de lá chegar é uma Recipe que deriva um ID lógico de um valor escrito pelo autor, em que dois valores escritos diferem apenas na pontuação — app-cache e app_cache derivam ambos AppCache, pelo que o fragmento escreve AppCache duas vezes.
Um nome de chave que se repete em sítios diferentes do documento é comum e não é tocado: Type aparece uma vez por recurso, e Value uma vez por saída, independentemente de quantos recursos e saídas o fragmento transporte. 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 na mesma stack, pelo que os fragmentos próprios de um componente partilham entre si os nomes da stack exatamente como os partilham entre componentes. Dois fragmentos que dão a um mesmo nome dois corpos diferentes interrompem a compilação, e a interrupção nomeia o espaço de chaves em que o nome se encontra — IDs lógicos de recurso ou nomes de saída — juntamente com o componente e o próprio nome. Ambos os espaços podem ser alcançados desta 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 as suas entradas de provides:, pelo que uma entrada de cada um que transporte um mesmo nome também aí se encontra.
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, pelo que as repetições se fundem numa única entrada e a compilação prossegue — uma repetição comum não custa nada. O que interrompe a compilação é 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 na stack. Mudar o nome de qualquer um dos dois resolve-o.
Validação estrutural da entrada
Um template do CloudFormation de origem é validado estruturalmente antes de ser renderizado: o fornecedor analisa o template e normaliza as suas funções intrínsecas, interrompendo a compilação 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 — não contacta a AWS, não resolve referências nem avalia funções intrínsecas.
Um template que passa na análise não é, por isso, transportado na íntegra. A análise diz que o documento está bem formado; o que chega à stack montada é decidido separadamente e secção a secção, em Secções de nível superior na stack montada — 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 a stack montada e não sobre um documento de entrada concreto, e cabe ao CloudFormation responder-lhe no momento da implementação. A compilação declara o que não transportou em vez de julgar a que se refere o resultado. As referências que julga são as que a própria compilação deixou pendentes: uma a um parâmetro que a associação de um template de origem preencheu, de que trata a secção seguinte, e uma a um recurso que uma entrada de omits: deixou de fora do template, de que trata a secção a seguir a essa.
Valores para os parâmetros de um template de origem
Um template de origem recebe valores da forma como o próprio CloudFormation dá valores a um template: através dos Parameters que declara. O valuesMapping daquilo que o usa como fonte — a Recipe de um componente, ou a FeatureRecipe de uma Feature anexada — escreve uma chave por parâmetro que preenche, e o fornecedor associa cada uma em todos os templates da fonte — cada Ref ao parâmetro em Resources, Outputs, Conditions, Rules e nos Globals do SAM torna-se o valor, cada Fn::Sub que nomeia o parâmetro como variável recebe o valor através do seu mapa de variáveis, e o parâmetro sai dos Parameters de cada template que o declara. Um parâmetro que nenhuma chave nomeia é deixado exatamente como o template o escreveu, para um valor passado quando a stack é implementada 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 numa única stack, pelo que um template pode referenciar um parâmetro que outro template da mesma fonte declara. Preencher o parâmetro preenche-o também aí: um template que apenas o referencia recebe o valor tal como o converteu o primeiro template da fonte que o declara, e nada na fonte fica a referenciar um parâmetro cuja declaração a associação removeu.
Nada mais na stack pode referenciar um parâmetro preenchido. Conteúdo fora da fonte — o fragmento ou o template de origem de outro componente na mesma stack — que nomeie um parâmetro que a associação da fonte preencheu, através de Ref, de uma variável de Fn::Sub ou do Fn::ValueOf de uma regra, nomearia algo que a stack montada já não declara, o que o CloudFormation recusa quando a stack é implementada. Assim, a compilação é interrompida, nomeando cada componente, o seu template e o parâmetro, e o componente cujo valuesMapping o preencheu — o de uma Recipe, ou o da FeatureRecipe de uma Feature anexada; uma Feature anexada a um componente é nomeada por esse componente, e uma anexada a uma fronteira pela identidade que os seus recursos transportam como aggrega.ai/component-id, composta a partir do caminho da fronteira e do nome do anexo (bfr--stack--aux para um anexo aux na fronteira stack). O fragmento do componente a que uma Feature está anexada, ou de um componente na fronteira a que está anexada, que referencie um parâmetro que a associação do anexo preencheu também interrompe a compilação. Um nome que a stack ainda declara não é afetado: onde outro componente declara ele próprio um parâmetro com esse nome, ou um recurso o transporta como o seu ID lógico, as suas referências resolvem-se contra essa declaração e são deixadas tal como estão escritas. Para passar o valor adiante, há que fazer o componente que o preenche publicá-lo, declarar o parâmetro no template que o referencia, ou remover 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 escreve são os nomes de parâmetro pretendidos para o template, pelo que cada uma tem de nomear um parâmetro que algum template da fonte declara: uma chave que não nomeia nenhum interrompe a compilação, nomeando a chave e os parâmetros que cada template de facto declara — a falha que o CloudFormation reportaria para um parâmetro desconhecido, reportada enquanto ainda cabe ao autor corrigi-la. Uma Recipe ou FeatureRecipe que não declara nenhum valuesMapping não preenche nada: os valores próprios do componente ou do anexo chegam ao fornecedor com os seus próprios nomes, escritos para as suas outras entradas, e ficam por ler.
O que um valor é decide o que chega ao template.
- Um literal — uma cadeia de caracteres, 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
Typedo parâmetro quando a stack é implementada: umNumbertorna-se a cadeia de caracteres que umRefa ele devolve, pelo que7chega como"7"; um tipoCommaDelimitedListouList<…>torna-se uma lista de cadeias de caracteres, aceitando quer uma lista, quer uma cadeia separada por vírgulas cujos membros são aparados; qualquer outro tipo aceita uma única cadeia de caracteres. Um literal é verificado contra os própriosAllowedValues,AllowedPattern,MinLength,MaxLength,MinValueeMaxValuedo parâmetro, e um que estes recusem interrompe a compilação, nomeando o parâmetro e a restrição, pelo que preencher um parâmetro não remove nenhuma verificação que o template tenha declarado. Um padrão escrito numa sintaxe de expressões regulares que a compilação não consegue ler é deixado para o CloudFormation verificar quando a stack é implementada. - Um valor que é inteiramente uma função intrínseca do CloudFormation chega ao ponto da referência como essa função intrínseca, para que o CloudFormation a avalie quando a stack é implementada: um mapeamento em forma longa como
{"Fn::GetAtt": [Queue, Arn]}, ou uma cadeia de caracteres que é exatamente uma forma curta —!GetAtt Queue.Arn,!Ref Bucket,!Sub …e as outras 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 umvaluesMappingque a lê do contexto de injeção passa-a adiante. Uma referência inserida lê-se da mesma forma entre aspas ou sem elas. Entre aspas —"{{ .context.inject.env.BUCKET_NAME }}"— o mapeamento passa adiante a cadeia de caracteres!GetAtt Queue.Arn; sem aspas, o próprio YAML do mapeamento lê!GetAtt Queue.Arncomo uma tag, e a tag é mantida com o seu argumento em vez de ser descartada. Qualquer uma delas 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 a ser texto. - Uma referência dinâmica —
{{resolve:ssm:…}},{{resolve:ssm-secure:…}}ou{{resolve:secretsmanager:…}}— chega ao ponto da referência tal como está escrita, para que o CloudFormation a resolva quando a stack é implementada, pelo que o valor que nomeia nunca está no template. - Um valor que outro componente publica a partir de uma stack diferente chega ao template como uma referência entre stacks, o mesmo
Fn::ImportValueouFn::GetStackOutputque um fragmento recebe (veja-se Ligação entre stacks), em cada ponto 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, pelo que um literal associado a um destes interrompe a compilação; o que se associa é uma referência {{resolve:ssm:…}} ou uma função intrínseca, ou então deixa-se o parâmetro sem associação. Uma lista associada a um parâmetro que o template nomeia como variável de Fn::Sub também interrompe a compilação, porque uma variável substitui uma única cadeia de caracteres. Uma chave que o valuesMapping define como null interrompe igualmente a compilação, 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 a stack é implementada ou para o seu Default, deixa-se a sua chave fora do mapeamento.
Uma regra que lê um parâmetro pelo nome mantém-no sem associação. Fn::ValueOf nas Rules de um template nomeia um parâmetro declarado pelo seu ID lógico em vez de através de Ref, e preencher o parâmetro remove a sua declaração, pelo que associar um parâmetro que uma regra lê dessa forma interrompe a compilação, nomeando a regra e o parâmetro.
Um literal que possa transportar um segredo é recusado; uma função intrínseca é escrita tal como é dada. Um valor escrito no template pode ser lido por qualquer pessoa que consiga ler o template da stack:
- Um parâmetro que o template declara
NoEchoaceita uma referência dinâmica ou uma função intrínseca, e um literal associado a ele interrompe a compilação. - Onde o
valuesMappinglê um valor que um autor declarou sensível, nada da sua saída pode ser rastreado até ao valor de que veio, pelo que cada literal que associa interrompe a compilação. Uma referência dinâmica e uma função intrínseca que associa são escritas tal como são dadas — incluindo o texto dentro de uma função intrínseca. Um segredo que o mapeamento insere no texto de umFn::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 uma compilação assim prossegue, imprime também um aviso por folha declarada, tanto para o mapeamento de uma Recipe como para o da FeatureRecipe de uma Feature anexada a um componente, nomeando a folha e a entidade a que pertence o mapeamento — veja-se A declared-sensitive value reaches the target through a values mapping (Um valor declarado sensível chega ao destino através de um mapeamento de values). - Uma referência dinâmica interrompe a compilação onde o seu parâmetro é referenciado na propriedade
UserDatade um recurso, nos metadados deAWS::CloudFormation::Initou emOutputs: o CloudFormation não resolve uma referência dinâmica nos dados de utilizador do EC2 nem nesses metadados, e mostraOutputsa quem quer que leia a stack.
Cada recusa deste tipo nomeia os parâmetros e não cita nenhum valor.
Deixar recursos de fora de um template de origem
Os recursos de um template de origem pertencem-lhe: os valores só o alcançam através dos parâmetros que declara, pelo que 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 gere noutro lugar — não pode ser alterado por um valor. É para isso que servem as entradas omits: de uma Recipe ou de uma FeatureRecipe. Este fornecedor respeita-as num 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: StoreLogsUma 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 em Resources; ambos são comparados exatamente como estão escritos, e ambos têm de corresponder, pelo que 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, pelo que uma entrada que traz um namespace interrompe a compilação quando o componente é renderizado, nomeando a entrada; cada entrada é verificada antes de qualquer coisa ser deixada de fora.
Cada template da origem é comparado. Uma origem de ficheiro único tem um template. Uma origem de diretório — uma origem obtida de um repositório git é-o sempre — tem cada ficheiro terminado em .yaml, .yml, .json ou .template, e uma entrada deixa de fora cada recurso que nomeia em qualquer um deles; um ficheiro transportado juntamente com os templates nunca é lido. O fornecedor indica quantos recursos cada entrada deixou de fora em todos eles, e uma entrada que não deixou nenhum de fora interrompe a compilação; veja-se 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 desaparece antes de qualquer outra coisa ler o template. Não é marcado com proveniência, não é contado entre os nomes que a stack transporta — pelo que outro componente pode contribuir com um recurso sob o mesmo ID lógico sem que os dois se encontrem — e nunca chega à stack montada. Tudo 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 secção Resources vazia.
Um recurso deixado de fora não pode continuar a ser nomeado pelo que resta, porque o CloudFormation recusa um template que nomeia um recurso que não declara. Depois de os recursos serem removidos, cada referência que os templates restantes ainda fazem a um deles interrompe a compilação, e a mensagem nomeia o template, o recurso, a forma como a referência o nomeia e o local onde a referência se encontra, como um caminho a partir da raiz do template — /Resources/Store/Properties/LoggingConfiguration/DestinationBucketName, por exemplo. Uma referência é aquilo 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 as suas propriedades, os seus metadados e as 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 cadeia —!GetAtt StoreLogs.Arn— cujo texto antes do primeiro ponto o é;- o
DependsOnde um recurso, como um ID lógico ou uma lista deles; - cada variável de
Fn::Sub, na sua forma de cadeia e na sua forma de lista:${StoreLogs}e${StoreLogs.Arn}nomeiam ambasStoreLogs.
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 outra stack e Fn::GetAZs uma região. As secções Conditions, Mappings, Parameters e Rules não podem nomear um recurso, e a secção Metadata de nível superior do próprio template é informação que o CloudFormation armazena em vez de ler, pelo que nenhuma delas é verificada. Um Ref ou um Fn::GetAtt cujo ID lógico está ele próprio escrito como uma função intrínseca só é válido sob a transformação AWS::LanguageExtensions, que o resolve quando a stack é implementada (veja-se Secções de nível superior na stack montada), pelo que 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 origem nunca declarou.
A verificação lê em conjunto os templates da própria Recipe ou FeatureRecipe que declara. São montados numa única stack, pelo que uma referência a um ID lógico que outro desses templates ainda declara não é travada. Nada mais é lido: uma referência a um recurso deixado de fora interrompe a compilação mesmo onde outro componente declara um recurso com esse ID lógico, e uma referência feita por qualquer outra coisa que é montada na stack — outro componente, uma Feature anexada ou as próprias entradas artifacts: da Recipe — fica fora do que esta verificação vê, pelo que o CloudFormation recusa a stack quando esta é implementada. Para manter uma referência, mantenha-se o recurso. Um valor associado a um parâmetro substitui apenas uma referência a esse parâmetro, pelo que uma referência a um recurso pertence ao template e não pode ser alterada por um valor: deixe-se também de fora o recurso que a faz, ou remova-se a entrada. Uma saída não é um recurso e nenhuma entrada nomeia uma, pelo que um recurso que as Outputs do template nomeiam não pode ser deixado de fora dele: deixá-lo de fora interrompe a compilação.
Anotações de destino de nuvem
Três anotações de fronteira indicam ao fornecedor onde uma stack é implementada, para que possa ligar corretamente as referências entre stacks:
aggrega.ai/aws-account— a conta da AWS na qual a stack é implementada.aggrega.ai/aws-region— a região da AWS na qual a stack é implementada.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 uma stack correspondente.
Estas anotações são opacas para o compilador — este canaliza os seus valores até ao fornecedor sem os interpretar (veja-se well-known-annotations.md). São escritas na fronteira do produtor — a stack que detém o valor exportado. Uma leitura entre contas assume uma função na conta do produtor, pelo que a conta, a região e a função que descrevem a leitura vêm todas das anotações da fronteira do produtor, e não das do consumidor.
Referências dentro da stack
Quando uma aresta uses une dois componentes que ficam na mesma fronteira — a mesma 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 da stack; não é necessário nenhum export nem import. 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 cadeia que é exatamente uma forma curta chega à stack como essa função intrínseca num fragmento tal como num valuesMapping. O exemplo aws-rds-and-ecs-service mostra-o numa definição de tarefa do Amazon ECS que lê o endereço de uma instância do RDS numa única stack.
Ligação entre stacks
Quando uma aresta uses atravessa 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é a stack do produtor ser implementada. O fornecedor liga-a como uma referência entre stacks do CloudFormation. A stack produtora publica o valor como um Output da stack com um Export sob um nome de export determinístico (derivado da release, da fronteira, do componente e da chave fornecida). A stack consumidora lê-o 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 verdadeira leitura entre contas ou entre regiões. O consumidor lê diretamente a saída da stack produtora, assumindo a funçãoaws-assume-role-arnda fronteira do produtor na conta e na região do produtor.
Semântica de deteção. O fornecedor encaminha para Fn::GetStackOutput apenas quando ambos os extremos 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 — usa Fn::ImportValue. Esta é uma regra conservadora: uma leitura entre stacks na mesma conta continua a ser um import simples, e a função intrínseca de leitura direta fica reservada para um salto real entre contas ou entre regiões.
A stack produtora publica sempre o Export, mesmo quando um determinado consumidor o lê entre contas através de Fn::GetStackOutput. Um export não utilizado é inerte, e publicá-lo incondicionalmente mantém o template do produtor independente da forma 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 numa stack, ou consumidores em várias stacks — a stack produtora 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 colocado noutra conta ou região lê a mesma saída através 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: a stack de uma instância do RDS exporta cada entrada que a aresta de um servidor consome, e a stack do servidor volta a ler cada uma 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 usaFn::ImportValue, que está disponível em todo o lado.
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, através de .context.uses.<alias>.provides, em vez de os receber pelo bloco inject da conexão. Através de um limite de stack, essa leitura é ligada da mesma forma que um valor injetado:
- Um valor que é uma função intrínseca do CloudFormation — uma etiqueta de forma curta como
!GetAtt Db.Endpoint.Address, ou umRefou um mapeamentoFn::de forma longa — nomeia algo que só a stack do produtor declara, pelo que o consumidor recebe a mesma referência entre stacks que um valor injetado recebe: a stack produtora publica umExportpara essa chave, e o consumidor lê-o comFn::ImportValue, ou comFn::GetStackOutputonde as duas fronteiras declaram posicionamentos que diferem. - Um valor que é texto simples — uma porta, um protocolo, um nome de base de dados — significa o mesmo em qualquer uma das stacks, pelo que o consumidor recebe o próprio valor e não é publicado nenhum export para 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 fornecedor, lendo o valor da forma como lê o próprio bloco provides do produtor. O compilador entrega o valor tal como a Recipe do produtor o escreveu e não o interpreta.
Um template só pode copiar um valor deste tipo. Pode escrever o valor inteiro, ou dentro de uma cadeia 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 numa conexão deste tipo o template recebe um substituto que o fornecedor troca assim que ambas as stacks estão montadas. Em vez disso, a compilação é interrompida, nomeando o template e cada valor que leu, com a conexão da qual o leu e o componente em cada extremo; ramifique-se sobre um valor do próprio componente consumidor. O mesmo vale para o injectMapping de uma FeatureRecipe anexada e para uma FeatureRecipe de âmbito de fronteira que lê as conexões da fronteira. Um valor escrito dentro de uma cadeia maior depara-se também com o limite próprio do fornecedor: uma referência entre stacks só pode figurar como um valor inteiro, pelo que uma função intrínseca escrita dentro de uma cadeia maior interrompe a compilação, tal como acontece com um valor injetado.
Como é construído um nome de export
As quatro partes são unidas com um hífen duplo, e cada parte é escrita nas letras, dígitos e hífenes de que um nome de export é feito. Uma letra ou um dígito é transportado tal como está 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 por -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 a partir 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--hostA releitura é inequívoca, e é esse o objetivo, não um pormenor de cortesia: como uma parte nunca contém dois hífenes seguidos e nunca termina com um, os hífenes duplos são sempre as junções. Dois conjuntos diferentes de partes produzem, portanto, sempre dois nomes diferentes. payments-db e payments_db chegam a dois exports separados em vez de convergirem num só, e um hífen na extremidade de uma parte não pode ser lido como pertencente à vizinha.
Em relação a quê um nome de export é único, e onde isso termina
Dentro de uma compilação, um nome de export identifica exatamente uma release, uma fronteira, um componente e uma chave fornecida — dois deles nunca convergem num mesmo nome, pelo que uma compilação não pode perder um valor exportado atrás de outro.
O CloudFormation exige ainda que um nome de export seja único em relação a tudo o que já está implementado na conta e na região em que a stack fica. Essa é uma propriedade da implementação, e não da compilação, e fica além do que qualquer derivação em tempo de compilação consegue alcançar: o compilador não se autentica na AWS, não a consulta e não pode ler a saída de outra compilação, pelo que nada calculado antecipadamente pode observar o que já está implementado ali.
O que leva a distinção para além dessa linha é a identidade da release que abre cada nome de export e de stack. Duas implementações que partilham uma conta e uma região mantêm os seus exports separados por serem publicadas com nomes diferentes — essa é a alavanca que se tem na mão, e a razão pela qual a identidade da release abre o nome em vez de o fechar.
Uma entrada de Outputs pode declarar o seu próprio nome de export
O bloco Outputs: de uma Recipe é CloudFormation escrito pelo autor, e uma entrada nele pode ter o seu próprio Export: com um Name:. Esse nome chega à stack montada exatamente como está escrito — o fornecedor não o reescreve, não lhe acrescenta prefixo e não exige que 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 fornecedor deriva é publicado ao lado dos derivados e nunca é assinalado. A escrita é suportada; só uma coincidência não o é.
A compilação é interrompida quando um nome de export escrito pelo autor é igual a um que o fornecedor deriva para uma ligação entre fronteiras na mesma compilação. Ambas as declarações chegariam ao template montado, deixando um nome de export declarado duas vezes numa mesma stack — e um nome de export tem de ser único, pelo que as duas não podem coexistir. A interrupção indica o nome de export derivado e as quatro partes a partir das quais foi construído, para que se possa ver que ligação o produziu, e nomeia a saída da stack sob a qual está a declaração escrita pelo autor, marcada como um nome que o fornecedor 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 escreve-o exatamente como a interrupção — é essa identidade que faz das duas uma colisão —, pelo que é a única cadeia que aparece tanto na mensagem como nos seus próprios ficheiros. Mudar o nome de export que essa entrada declara elimina a interrupção, tal como remover o bloco Export: dessa entrada e deixar a ligação entre stacks publicar ela própria o export.
A verificação tem âmbito de compilação, e o seu âmbito é uma stack. Compara os nomes de export que uma stack montada declara com os nomes que o fornecedor deriva para as ligações entre fronteiras que publicam nessa mesma stack — a comparação que a compilação pode fazer a partir do que montou. Duas stacks não são comparadas entre si. E aquilo que um nome escrito pelo autor encontra entre os exports já implementados numa conta e numa região é uma propriedade da implementação, que fica além do que qualquer derivação em tempo de compilação consegue alcançar, pela razão exposta 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 outra compilação. Um nome de export escrito como função intrínseca em vez de como cadeia simples fica do outro lado da mesma linha — é resolvido no momento da implementação, e nada aqui avalia uma função intrínseca, pelo que não há nenhum nome que a compilação possa comparar.
A compilação é também interrompida quando a saída na qual uma ligação entre fronteiras publica já tem um Export que a ligação não escreveu. Essa saída é a que o fornecedor monta para a chave fornecida que um consumidor lê, pelo que uma Recipe cujo bloco Outputs: escreve uma entrada sob essa mesma chave, com um Export: próprio, coloca o seu export exatamente onde vai o da ligação. A menos que o nome desse export seja exatamente o que o fornecedor deriva — caso em que é o próprio export da ligação e todos os consumidores o importam —, os dois não podem coexistir ali: escrever o export da ligação substituiria o seu, e manter o seu deixaria todos os consumidores a importar um nome que a ligação não publicou. A interrupção indica o nome de export derivado e as quatro partes a partir das quais 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 elimina-a, e a ligação entre stacks publica então o export que todos os consumidores importam.
Ordem de implementação
O valor syncWave: de uma fronteira de uma Release ordena o aprovisionamento da stack na qual essa fronteira é montada. Cada componente da fronteira herda a wave da fronteira e, onde várias fronteiras se resolvem para o mesmo diretório de saída — de modo que os seus fragmentos são montados num único template —, a stack contém mais de uma wave e o fornecedor exprime a ordem entre elas como DependsOn.
Cada recurso nomeia todos os recursos da wave imediatamente anterior que tenha recursos, e nenhuma wave anterior a essa. O CloudFormation encadeia o resto: um recurso na wave 2 depende da wave 1, que depende da wave 0, pelo que toda a sequência fica ordenada enquanto a lista própria de cada recurso mantém o tamanho de uma wave e não o da stack inteira. As waves não têm de ser contíguas, e os valores negativos são normais — -1 é uma escolha comum para um bucket ou uma função que o resto da stack lê. A wave mais baixa não nomeia nada, porque nada a precede.
O que a ordem é: ordem de criação e, inversamente, ordem de eliminaçã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 numa ordem declarada. O atributo rege os dois sentidos, pelo que uma wave que cria um recurso mais cedo também o elimina mais tarde — a sequência correta de desmontagem vem com a ordem, sem precisar de mais nada.
Não é uma ordem de prontidão. Um template de stack não exprime nenhuma noção de um recurso estar operacional, pelo que nada aqui espera que um fique pronto — apenas que o CloudFormation termine de o criar. Essa é uma diferença real em relação à mesma wave no compose, onde um serviço que declara um healthcheck é aguardado até comunicar 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 não pode cumprir.
Um DependsOn escrito pelo autor é estendido, nunca substituído. Um fragmento que declara a sua própria restrição de ordem mantém-na: as entradas que escreveu ficam primeiro, pela ordem em que as escreveu, e as entradas da wave vêm a seguir. Ambos os requisitos valem e nenhum esconde o outro. São lidos tanto um ID lógico único como uma lista, e o valor combinado é emitido como lista, que é a única grafia que serve para quantas entradas a combinação produzir.
Uma stack cujos recursos têm todos uma mesma wave não ganha nada com isto. O mesmo vale para uma Release que não declara nenhum syncWave: cada contribuidor tem o valor predefinido do campo, 0, o template montado contém uma única wave, e a saída é exatamente a que seria se o fornecedor não exprimisse nenhuma ordem de waves.
A ordem entre duas stacks não é exprimível, e não é aproximada. DependsOn nomeia um recurso dentro do mesmo template, e os componentes que são montados noutra stack ficam fora dele. Assim, uma wave ordena todos os recursos da stack na qual é montada e nada além dela. Sequenciar duas stacks é assunto do operador, da mesma forma que uma referência entre stacks é uma resolução no momento da implementação e não no momento da compilação.
A ordem que as waves não exprimem continua a ser assunto do próprio CloudFormation, e as referências entre recursos já transportam boa parte dela: um Fn::GetAtt sobre um recurso do produtor indica ao CloudFormation que crie primeiro esse recurso. Um fragmento que precise de uma restrição que nem as referências nem as waves impliquem escreve ele próprio DependsOn, que é o caso que a combinação acima preserva.
Determinismo
Com as mesmas entradas, o fornecedor emite um template de stack idêntico byte a byte entre execuções: os IDs lógicos, as chaves de saída, os nomes de export e a ordem dos recursos são todos determinísticos, pelo que um template de stack do CloudFormation produz diffs limpos na revisão GitOps.