Salta ai contenuti
AggregaAggrega
Seleziona lingua: Italiano
Questa pagina è stata tradotta automaticamente. Leggi l’originale in inglese.

Provider CloudFormation

Il provider cloudformation esegue il rendering delle Recipes di Aggrega in template di stack AWS CloudFormation. Ogni componente che esegue il rendering nella stessa directory di output con questo provider viene assemblato in un unico stack, emesso come un singolo template in JSON puro che usa funzioni intrinseche in forma lunga. Un confine diventa quindi uno stack nel caso ordinario — e due confini la cui directory: si risolve nello stesso percorso vengono assemblati insieme in un unico stack, condividendo i nomi di quel template. Come ogni provider di Aggrega è offline ed ermetico — una build di Aggrega è una compilazione anticipata, quindi il provider non chiama mai AWS, non risolve mai identificatori generati dall’account e non esegue mai CloudFormation. I valori disponibili solo a runtime restano riferimenti intrinseci di CloudFormation (Fn::GetAtt, Fn::ImportValue, Fn::GetStackOutput) che CloudFormation risolve al momento della distribuzione.

Recipe di frammenti assemblate in uno stack

Una Recipe cloudformation scrive un frammento — le risorse CloudFormation apportate da un singolo componente — anziché un template intero. Quando i componenti di un confine eseguono il rendering, il provider assembla ogni frammento del gruppo di smistamento in un unico template di stack: le risorse si uniscono sotto un’unica mappa Resources, i valori provides di ciascun componente emergono come Outputs dello stack, e le altre sezioni di primo livello del template vengono considerate una per una in Sezioni di primo livello nello stack assemblato. Sono accettate due forme di authoring:

  • Input a frammenti (artefatti). Una Recipe scrive direttamente frammenti di risorse; il provider li normalizza in JSON puro con funzioni intrinseche in forma lunga e li unisce nello stack assemblato.
  • Input da sorgente. Una Recipe fa riferimento a un template CloudFormation esistente (YAML o JSON); il provider lo normalizza in JSON in forma lunga e ne convalida la struttura prima dell’assemblaggio, riempie i parametri che il template dichiara a partire dal valuesMapping della Recipe — vedi Valori per i parametri di un template di origine — e lascia fuori ogni risorsa nominata dalle voci omits: della Recipe — vedi Lasciare fuori risorse da un template di origine.

Il template assemblato è JSON puro. Le funzioni intrinseche vengono emesse alla lettera e mai valutate al momento della build — il compilatore non può risolvere un valore che esiste solo dopo che lo stack è stato distribuito, e valutarne uno violerebbe il contratto della compilazione anticipata.

Una Feature associata a un componente contribuisce allo stesso stack

Una Feature associata a un componente apporta le proprie risorse allo stack in cui viene assemblato il suo componente ospitante, alle stesse condizioni della Recipe del componente ospitante stesso. Non c’è alcun template separato accanto: lo stack assemblato è tutto ciò che questo provider emette per una directory di output, quindi le risorse di una Feature associata o si trovano in quello stack o non vengono distribuite affatto. Dissociare la Feature rimuove esattamente quelle risorse e lascia intatte quelle proprie del componente ospitante.

Poiché finiscono nello stack assemblato, ne condividono i nomi. Gli ID logici delle risorse di una Feature associata si trovano nello stesso spazio di quelli del componente ospitante e di quelli di ogni altra Feature associata accanto a essa, quindi Nomi nello stack assemblato si applica a essi senza modifiche. Dove due contributori si incontrano su un unico nome, l’arresto nomina il componente e la chiave sotto cui la Feature è associata, così entrambe le estremità della collisione sono ricercabili nei tuoi file.

Gli output di una Feature associata vengono pubblicati sotto il nome del suo componente ospitante, e gli ID logici delle sue risorse no. Le due metà dello stack prendono il nome secondo regole diverse, quindi su questo rispondono in modo diverso. L’ID logico di una risorsa viene emesso esattamente come la FeatureRecipe lo ha scritto, come quello di qualsiasi Recipe. Un output prende il nome dal componente che pubblica e dalla voce insieme — e per una Feature associata a un componente, il componente che pubblica è l’ospitante: una Feature associata a payments-db che pubblica alarm raggiunge paymentsXzhdbXXalarm, lo stesso nome che raggiungerebbe se il componente ospitante avesse pubblicato quella voce da sé. Quindi un nome di voce che anche l’ospitante pubblica incontra quello dell’associazione su un unico nome di output, e la build si arresta nominando il componente e la chiave sotto cui la Feature è associata accanto al componente considerato da solo. Scegliere nomi di voce che si leggano come propri della Feature — backup-alarm anziché alarm — li tiene distinti da quelli dell’ospitante.

Ogni risorsa che una Feature apporta conserva, nella provenienza che la build vi scrive, l’identità composta per quell’associazione anziché quella del componente ospitante, così le due restano distinguibili all’interno di uno stack a cui entrambe hanno contribuito. Etichette e annotazioni spiega come viene costruita quell’identità.

Sezioni di primo livello nello stack assemblato

Diversi componenti si assemblano in un unico stack, quindi l’assemblaggio deve rendere conto di ogni sezione di primo livello che un template CloudFormation ammette — compresi Globals e Hooks, le due sezioni che una trasformazione ospitata da CloudFormation aggiunge al linguaggio dei template. Ciascuna rientra esattamente in uno dei gruppi qui sotto, e una chiave di primo livello scritta da un componente che non è affatto una sezione riceve un avviso che nomina il componente e la chiave, così nulla viene scartato senza che venga detto.

Assemblati sotto nomi a cui il provider assegna un ambito, o letti così come sono scritti. Resources e Outputs, che Nomi nello stack assemblato tratta per intero. AWSTemplateFormatVersion viene scritto dal provider anziché letto da un componente: il linguaggio dei template ammette per esso un unico valore, quindi non c’è nulla che un componente debba decidere.

Portati con esattamente i nomi che hai scritto. Parameters, Mappings, Conditions, Metadata e Rules. Ciascuna di queste è una mappa con chiavi che hai scelto tu, quindi le voci di ogni componente raggiungono lo stack assemblato con quei nomi, senza riscritture — ed è questo che permette a un Condition: di una risorsa, a un Fn::FindInMap o a un Ref a un parametro di risolversi rispetto alla dichiarazione arrivata insieme a essi. Ciascuna viene portata a sé, perché ciascuna viene scritta a sé: una regola fa asserzioni su un parametro dello stesso documento, una condizione può non fare riferimento ad alcun parametro, e CloudFormation non consente un riferimento a un parametro all’interno di una mappatura.

Qui una stessa parola copre due posti diversi, e solo il primo è tuo. Il Metadata nell’elenco sopra è la sezione di primo livello propria del template, una mappa di nomi che hai scelto tu. Anche una singola risorsa porta un proprio attributo Metadata, ed è lì che la build scrive la provenienza — sotto un’unica chiave riservata aggrega.ai/, aggiunta accanto a qualunque cosa tu abbia scritto lì anziché sostituirla. Quindi una voce di provenienza che compare all’interno di una risorsa non è qualcosa che hai scritto tu né qualcosa che la sezione di primo livello ha portato.

Parameters, Mappings, Conditions e Rules nominano le loro voci con un ID logico. Poiché il provider porta un nome esattamente come lo hai scritto, l’alfabeto che un ID logico ammette raggiunge anche queste sezioni: un nome in una delle quattro che contiene qualcosa di diverso da lettere e cifre arresta la build — vedi Un nome di sezione portato fuori dall’alfabeto arresta la build. Il provider non vincola a quell’alfabeto i nomi della sezione Metadata di primo livello: nominano informazioni che stai conservando anziché qualcosa a cui il template fa riferimento.

Due componenti che dichiarano nomi diversi in una di queste sezioni arrivano entrambi. Due che dichiarano uno stesso nome con contenuto identico si fondono in un’unica voce e la build prosegue. Due che dichiarano uno stesso nome con contenuto diverso arrestano la build, nominando la sezione, il nome ed entrambi i componenti — perché altrimenti uno dei due corpi verrebbe scartato, lasciando al componente che l’ha scritto una dichiarazione che lo stack non porta. È la stessa riconciliazione che seguono i nomi delle risorse e degli output, e rinominare l’uno o l’altro la risolve.

Nominati anziché portati. Description è un’unica affermazione su un intero template anziché una mappa di nomi che hai scelto tu, quindi un assemblaggio che attinge a più componenti non ha una risposta per essa: due descrizioni sono due risposte a una stessa domanda e nessuna delle due è quella dello stack. Hooks viene letto solo dalla trasformazione AWS::CodeDeployBlueGreen, che lo stack assemblato non porta mai (vedi sotto). Lo stack assemblato quindi non porta nessuna delle due, e ogni componente che ne ha scritta una riceve un avviso che nomina il componente e la sezione. Lo stesso vale per un componente che scrive Globals senza dichiarare la trasformazione AWS::Serverless-2016-10-31 che li legge. L’avviso è consultivo e fuori banda: il template emesso è byte per byte ciò che sarebbe senza di esso, e --no-unsupported-field-warnings lo silenzia insieme al resto di quella classe.

Transform viene costruito a partire da quello di ogni componente. Una trasformazione è una macro che CloudFormation esegue sull’intero template prima di distribuire qualsiasi cosa, quindi il Transform dello stack assemblato è l’unione delle trasformazioni che i suoi componenti dichiarano — quelle di un template di origine come quelle di un frammento — nell’ordine che CloudFormation documenta: una macro definita dal tuo account prima delle trasformazioni ospitate da CloudFormation, e AWS::LanguageExtensions prima di AWS::Serverless-2016-10-31. L’ordine proprio di ciascun componente viene mantenuto, e due trasformazioni che nulla ordina vengono eseguite nell’ordine in cui i componenti le dichiarano per la prima volta, così gli stessi componenti danno lo stesso stack. Una sola trasformazione viene scritta come stringa e più trasformazioni come lista. Uno stack con un solo componente, che dichiara il suo Transform in un template o in un frammento, lo mantiene esattamente come è stato scritto ovunque la tabella qui sotto lo porti, e uno stack i cui componenti non ne dichiarano alcuna non ne porta alcuna. La trasformazione di un componente non solleva alcun avviso: viene portata, oppure la build si arresta nominandola.

Poiché una trasformazione elabora l’intero template, portarne una cambia il modo in cui viene distribuito il contenuto di ogni altro componente, a meno che ciò che fa non sia circoscritto al contenuto scritto per essa. Quindi ogni trasformazione riceve il trattamento che la documentazione stessa di CloudFormation su di essa sostiene, e una combinazione che lo stack non può portare arresta la build, nominando la trasformazione e ogni componente nello stack:

trasformazionenello stack assemblato
AWS::Serverless-2016-10-31portata, con i Globals del componente che la dichiara. Arresta la build dove quei Globals raggiungerebbero le risorse serverless di un altro componente, e dove una delle sorgenti di eventi delle sue risorse nomina una risorsa che un altro componente dichiara, perché la trasformazione riscrive la risorsa che un evento nomina.
AWS::LanguageExtensionsportata da sola, oppure accanto a AWS::Serverless-2016-10-31 dello stesso componente. Arresta la build accanto al contenuto serverless di un altro componente, perché la trasformazione serverless nomina ciò che genera in modo diverso una volta che le estensioni del linguaggio hanno risolto i suoi valori.
AWS::SecretsManager-2020-07-23, AWS::SecretsManager-2024-09-16portate: elaborano solo le pianificazioni di rotazione che le richiedono.
AWS::ServiceCatalogportata per uno stack con un solo componente. Accanto a qualsiasi altro arresta la build, perché sostituisce il suo schema di riferimento ovunque nel template.
AWS::CodeDeployBlueGreenarresta la build, anche da sola: CloudFormation rifiuta Outputs e Fn::ImportValue ovunque in un template che la dichiara, e lo stack assemblato porta gli output pubblicati dai suoi componenti.
AWS::Includearresta la build, anche da sola: inserisce contenuto recuperato da S3 quando lo stack viene distribuito, che la build non può leggere.
una macro definita dal tuo accountportata per uno stack con un solo componente. Accanto a qualsiasi altro arresta la build, perché ciò che fa al resto del template è sconosciuto alla build.

Anche due componenti che dichiarano una stessa coppia di trasformazioni in ordini opposti arrestano la build, nominando entrambi gli ordini ed entrambi i componenti, poiché lo stack le esegue in un unico ordine. Un componente che ha bisogno di una trasformazione che lo stack non può portare va collocato in un confine proprio.

Nomi nello stack assemblato

Un ID logico CloudFormation è univoco all’interno di un template e ammette solo lettere e cifre, e ogni componente che si assembla in quel template ne condivide i nomi — compresi i componenti di un secondo confine, quando entrambi si risolvono nella stessa directory di output. Quindi ogni nome con cui lo stack indirizza qualcosa deve essere distinto tra tutti i componenti che vi hanno contribuito, e l’insieme dei contributori non è sempre un unico confine.

Gli ID logici delle risorse vengono dalla Recipe. Il provider li emette esattamente come sono stati scritti e non ne riscrive nessuno, quindi il nome che leggi nel template assemblato è il nome che ha scritto la Recipe. Le Recipes CloudFormation della libreria standard lo derivano dal nome stesso dell’istanza del componente, leggendo i separatori di quel nome come confini di parola: l’istanza payments-db nomina la sua risorsa PaymentsDb. Due istanze dello stesso tipo descrivono quindi due risorse anziché contendersene una.

I nomi di output hanno l’ambito del componente che li ha pubblicati. Ogni voce di provides compare come un output che prende il nome dal componente che pubblica e dalla voce insieme — il componente payments-db che pubblica host compare come paymentsXzhdbXXhost — quindi due componenti che pubblicano la stessa voce arrivano a due output separati, e il significato di un output non cambia quando un altro componente si unisce allo stack. Un consumatore tra stack nello stesso account e nella stessa regione importa tramite il nome di export anziché tramite questo, quindi il nome di export non ne è toccato; una lettura tra account o tra regioni nomina questo output, così come il provider lo scrive per te (vedi Cablaggio tra stack).

Come viene costruito un nome di output

Un ID logico non ammette alcun carattere separatore, quindi un nome costruito a partire da qualcosa che hai scritto deve in qualche modo portare con sé i tuoi separatori. Eliminarli comporterebbe una perdita: payments-db e payments_db sono due componenti, e un nome che eliminasse la punteggiatura non identificherebbe nessuno dei due. Quindi il provider codifica invece ciò che l’alfabeto rifiuta, scrivendo per esteso ogni carattere rifiutato con caratteri che l’alfabeto ammette.

Lo schema riserva un carattere con cui aprire una sequenza di escape — una X maiuscola — e scrive tutto il resto così come lo hai digitato, maiuscole comprese. È riservata solo la maiuscola, quindi la x minuscola di un nome come nginx-proxy viene portata così come l’hai scritta:

ciò che hai scrittociò che diventaperché
una lettera o una cifra, eccetto Xil carattere stessol’alfabeto lo ammette
-Xzhl’alfabeto rifiuta il trattino
_Xzul’alfabeto rifiuta il trattino basso
.Xzdl’alfabeto rifiuta il punto
/Xzsl’alfabeto rifiuta la barra, che un’identità di componente annidata porta con sé
XXzx000058riservato per aprire una sequenza di escape, quindi viene scritto per esteso tramite il suo punto di codice
qualsiasi altra cosaXzx e il punto di codice del carattereun’unica regola copre ogni carattere restante
le due metà che si incontranoXXdue caratteri di apertura di fila, che nessuna delle due metà può contenere

La rilettura è univoca, e questo è il punto anziché un vezzo. Una X viene mantenuta come sé stessa solo quando il carattere che la segue è uno che l’alfabeto ammette, quindi una metà codificata non termina mai con una e non ne porta mai due di fila — il che lascia XX libero di indicare la giunzione, e soltanto la giunzione.

Così tre nomi che differiscono solo per la posizione della loro punteggiatura restano distinti:

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

I nomi sono più lunghi e meno immediatamente leggibili del nome di componente che hai scritto, e questo è il compromesso. Un nome che identifica esattamente una voce vale più di uno più breve che non identifica nessuna di due — e fai riferimento a un output tramite il nome di export anziché digitando questo, quindi ciò che costa è una seconda occhiata quando leggi un template emesso.

Gli ID logici delle risorse seguono una regola diversa, perché il provider non li costruisce: emette ciò che ha scritto la Recipe. Le Recipes CloudFormation della libreria standard ne derivano uno leggendo i separatori del nome dell’istanza come confini di parola — l’istanza payments-db nomina la sua risorsa PaymentsDb — e quella derivazione elimina i separatori, quindi due nomi di istanza che differiscono solo per la punteggiatura, o solo per le maiuscole e minuscole di una lettera, derivano comunque un unico nome di risorsa. La build si arresta, nominando ogni istanza arrivata a quel nome insieme al nome su cui sono finite, anziché emettere una sola risorsa dove sono stati dichiarati due componenti. Vengono nominate tutte anziché alcune, perché nulla in una collisione rende la derivazione di un’istanza quella intesa. Rinominarle tutte tranne una risolve l’arresto.

Un ID logico di risorsa fuori dall’alfabeto arresta la build

L’unicità e l’alfabeto sono due requisiti separati, e un insieme di nomi può soddisfare il primo e non il secondo. Poiché il provider emette un ID logico di risorsa esattamente come l’ha scritto la Recipe, l’ID che una Recipe scrive deve essere uno che un template CloudFormation può contenere da solo: lettere e cifre, e nient’altro.

È qui che un nome derivato e uno passato così com’è prendono strade diverse. Un nome di output viene costruito dal provider, che codifica il componente che pubblica e la voce, quindi un nome di output rientra nell’alfabeto comunque tu scriva l’una o l’altra metà. Un ID logico di risorsa viene passato così com’è, quindi qualunque cosa abbia scritto la Recipe è ciò che riceve il template.

Questo lo rende un vincolo anche sui nomi dei componenti, ogni volta che una Recipe scrive il nome di un’istanza di componente direttamente nell’ID logico. Il nome di un componente può contenere un trattino o un trattino basso; un ID logico no. Un componente che destini a questo provider tramite una Recipe di quel tipo va quindi nominato con sole lettere e cifre — paymentsdb anziché payments-db — e qualsiasi altra cosa arresta la build.

L’arresto nomina il contributore la cui Recipe ha scritto l’ID, l’ID stesso e ogni suo carattere che non può trovarsi lì, e dice che cosa puoi scrivere al suo posto. Due cose lo risolvono, e la prima è quella sempre disponibile per te:

  • Fai in modo che la Recipe scriva un ID logico proprio anziché passare un nome così com’è. Le Recipes CloudFormation della libreria standard seguono questa strada — leggono i separatori del nome dell’istanza come confini di parola, quindi l’istanza payments-db nomina la sua risorsa PaymentsDb e mantieni il nome di componente che hai scelto. Derivare un ID in questo modo scambia questo arresto con la regola di collisione vista sopra: due nomi di istanza che differiscono solo per la punteggiatura derivano un unico nome di risorsa.
  • Dove una Recipe passa invece un nome così com’è, rinomina ciò che passa usando sole lettere e cifre. Per la Recipe propria di un componente si tratta del nome del componente. Una Feature associata a un componente nomina le sue risorse dalla propria FeatureRecipe, quindi rinominare il componente ospitante non le raggiunge — è l’ID che scrive quella Recipe che deve cambiare.

Il provider rifiuta; non ripara di nascosto. Riscrivere l’ID al posto tuo sembrerebbe la cosa utile da fare, e non lo è. Un ID logico è il modo in cui CloudFormation identifica una risorsa attraverso gli aggiornamenti, quindi cambiarne uno non è una ridenominazione — indirizza una risorsa diversa. Un ID sostituito dal provider punterebbe altrove rispetto alla risorsa già distribuita con l’ID che hai scritto, e la sostituzione è una che non hai mai chiesto e che dovresti scoprire dal template emesso. Una build che si arresta nomina il problema finché sta ancora a te risolverlo.

Un nome di sezione portato fuori dall’alfabeto arresta la build

Gli ID logici delle risorse non sono gli unici nomi che il provider porta esattamente come li hai scritti. Anche Parameters, Mappings, Conditions e Rules nominano le loro voci con un ID logico, e ciascuna delle quattro raggiunge lo stack assemblato con il nome scelto dal suo autore. Il requisito è quindi lo stesso, su altre quattro superfici: il nome deve essere uno che un template CloudFormation può contenere da solo — lettere e cifre, e nient’altro — e qualsiasi altra cosa arresta la build.

C’è una conseguenza che va oltre la sezione che porta il nome, ed è il motivo per cui questo arresta la build anziché emettere un avviso. Questi nomi sono ciò rispetto a cui si risolvono il Condition: di una risorsa, un Fn::FindInMap o un Ref a un parametro. Un nome che l’alfabeto non ammette porta quindi fuori dal template distribuibile, insieme alla dichiarazione stessa, anche il riferimento che punta a esso, così un unico nome scritto rende irraggiungibili entrambi in una volta — e senza l’arresto lo si scopre al momento della distribuzione, da parte di chi sta distribuendo anziché di chi ha scritto il nome.

L’arresto nomina il contributore la cui Recipe ha scritto il nome, la sezione in cui è stato scritto, il nome stesso e ogni suo carattere che non può trovarsi lì. La sezione è il termine da cercare nelle tue Recipes: questi nomi vengono portati esattamente sotto la sezione in cui li hai scritti, quindi è l’unica parola che compare sia nel messaggio sia nei tuoi file. Rinominare la voce con sole lettere e cifre lo risolve, e questo è tutto il rimedio — un ID logico di risorsa offre l’alternativa di far derivare un ID alla Recipe anziché passare un nome così com’è, e qui non c’è nulla da derivare, perché il nome nella sezione è ciò che hai scritto.

Solo i nomi propri di una sezione sono vincolati all’alfabeto, mai le chiavi all’interno di una voce. Le chiavi di secondo livello di una mappatura sono tue da scegliere liberamente — us-east-1 sotto una mappa RegionCidr è il caso ordinario, e raggiunge il template emesso senza modifiche. Le chiavi all’interno del corpo di un parametro, di una condizione o di una regola nominano attributi, asserzioni e funzioni intrinseche anziché qualcosa che lo stack indirizza: gli Assertions di una regola, e un Fn::Contains scritto al suo interno, sono chiavi di questo tipo. Nessuna di esse è un ID logico, e nessuna viene controllata.

Due nomi di voce che hai scritto distinti restano distinti

Tre tipi di nome di voce sono abbastanza vicini da incontrarsi in un unico nome di output, e nessuno di essi è insolito. Poiché le due metà vengono codificate anziché compattate, e si incontrano in una sequenza che nessuna delle due metà può contenere, tutti e tre arrivano a nomi propri:

  • Voci che differiscono solo per la punteggiatura. Un componente che pubblica sia db-host sia db_host arriva a dbXzhhost e dbXzuhost.
  • Voci che differiscono solo per le maiuscole e minuscole di una lettera. host e Host arrivano a host e Host, perché una lettera viene portata maiuscola o minuscola così come l’hai scritta.
  • Voci che si incontrano attraverso la giunzione. Il Component payments-db che pubblica host arriva a paymentsXzhdbXXhost; il componente payments che pubblica db-host arriva a paymentsXXdbXzhhost.

Due voci si incontrano comunque dove nominano davvero una stessa cosa. Il nome di output è costruito a partire dal componente che pubblica e dalla voce, quindi tutto ciò che li condivide entrambi arriva a un unico nome, comunque venga codificato. Il caso che è più probabile incontrare è una stessa Feature associata due volte a un singolo componente: un’associazione pubblica sotto il suo ospitante, quindi due associazioni di una Feature su un componente pubblicano entrambe alarm-id da payments-db, e nella coppia non c’è nulla che permetta di distinguerle. La build si arresta anziché emettere un unico output dove ne sono stati scritti due, nominando il componente e la chiave di associazione che ciascun lato portava, così entrambe le estremità sono ricercabili nei tuoi file. Associa la Feature una sola volta, oppure usa una Feature i cui nomi di voce pubblicati si leggano come propri di quell’associazione.

Questo vale indipendentemente dal fatto che le due voci portino lo stesso valore. Due voci con lo stesso valore descrivono comunque due output richiesti da un autore, quindi fonderle in uno solo lascerebbe uno dei due output scritti assente dallo stack.

Un nome che una Recipe compone in un template non è coperto da questo

La codifica descritta sopra è del provider, e si applica ai nomi di output che costruisce il provider. Non è disponibile per te all’interno di un template di Recipe, e un nome che il tuo template compone non porta quindi nessuna delle sue garanzie. Dirlo chiaramente conta perché il rischio è invisibile dall’interno del template: la compattazione disponibile lì legge il suo argomento come parole ed elimina tutto ciò che sta tra di esse, quindi unire due valori prima di compattarli perde la giunzione insieme alla punteggiatura.

Una FeatureRecipe che nomina una risorsa a partire da un’istanza e da una chiave di associazione, unite da uno spazio e poi compattate, è la forma a cui prestare attenzione — app con cache e app-cache senza nulla vengono compattati entrambi in AppCache, e i due collidono prima che si applichi qualsiasi proprietà della compattazione. Due cose mantengono distinto un nome del genere, ed entrambe spettano a te anziché al provider:

  • Mantieni le parti composte in lettere e cifre, così nulla viene eliminato e nulla deve essere distinto.
  • Non unire due valori che possono contenere ciascuno il separatore dell’altro. Dove un nome deve portare due parti, rendi una di esse un letterale fisso che l’altra non può contenere.

Dove un nome composto collide davvero, collide come ID logico di risorsa anziché come nome di output, quindi l’arresto che incontri è quello sui nomi delle risorse descritto sopra.

Una chiave scritta due volte in una mappatura arresta la build

Un frammento CloudFormation viene letto come una mappatura, e una mappatura contiene un valore per chiave, quindi una chiave scritta due volte manterrebbe il corpo arrivato per ultimo e scarterebbe l’altro. Dove la mappatura è un blocco Resources o Outputs, il corpo scartato è una risorsa o un output che è stato scritto e che semplicemente non sarebbe nello stack.

La build invece si arresta, nominando la chiave ripetuta ed entrambe le righe in cui è stata scritta. È una regola sull’intero frammento anziché una regola sui nomi dello stack: si applica a qualsiasi mappatura del frammento, comprese le Properties di una risorsa. Il modo più comune di incorrervi è una Recipe che deriva un ID logico da un valore scritto da un autore, dove due valori scritti differiscono solo per la punteggiatura — app-cache e app_cache derivano entrambi AppCache, quindi il frammento scrive AppCache due volte.

Un nome di chiave che ricorre in punti diversi del documento è ordinario e non viene toccato: Type compare una volta per risorsa, e Value una volta per output, per quante risorse e output porti il frammento. Solo una ripetizione all’interno di una stessa mappatura perde un corpo.

Un singolo componente può rivendicare due volte uno stesso nome. Una Recipe contribuisce con diversi frammenti — diverse voci artifacts:, o una directory di origine che contiene diversi template — e ognuno di essi si assembla nello stesso stack, quindi i frammenti propri di un componente condividono tra loro i nomi dello stack esattamente come li condividono tra componenti diversi. Due frammenti che danno a uno stesso nome due corpi diversi arrestano la build, e l’arresto nomina lo spazio delle chiavi in cui si trova il nome — ID logici delle risorse o nomi di output — insieme al componente e al nome stesso. Entrambi gli spazi sono raggiungibili in questo modo: due frammenti possono scrivere uno stesso ID logico di risorsa su risorse diverse, e un componente raggiunge i propri nomi di output per due vie, un blocco Outputs: esplicito e le sue voci provides:, quindi anche una voce di ciascuna che porta uno stesso nome si incontra lì.

Ripetere un nome non è di per sé un conflitto. Un nome scritto più di una volta con contenuto identico indirizza comunque una sola cosa, quindi le ripetizioni si fondono in un’unica voce e la build prosegue — una ripetizione ordinaria non costa nulla. Ciò che arresta la build è il caso che perde contenuto: uno dei due corpi dovrebbe essere scartato, e la risorsa o l’output dichiarato dalla Recipe mancherebbe allora dallo stack. Rinominare l’uno o l’altro lo risolve.

Validazione strutturale dell’input

Un template CloudFormation di origine viene validato strutturalmente prima di essere renderizzato: il provider analizza il template e normalizza le sue funzioni intrinseche, arrestando la build con un messaggio chiaro che nomina il nodo responsabile quando un template è malformato. L’analisi controlla la forma, non la semantica — non contatta AWS, non risolve i riferimenti e non valuta le funzioni intrinseche.

Un template che supera l’analisi non viene per questo portato per intero. L’analisi dice che il documento è ben formato; ciò che raggiunge lo stack assemblato viene deciso separatamente e sezione per sezione, in Sezioni di primo livello nello stack assemblato — un template di origine passa per lo stesso rendiconto di un frammento.

Né l’analisi si chiede se i riferimenti del template si risolvono. Se un Ref nomina un parametro, o un Fn::FindInMap una mappa, è una domanda sullo stack assemblato anziché su un singolo documento di input, e spetta a CloudFormation rispondere al momento della distribuzione. La build dichiara ciò che non ha portato anziché giudicare a che cosa fa riferimento il risultato. I riferimenti che giudica sono quelli che la build stessa ha lasciato pendenti: uno a un parametro valorizzato dal binding di un template di origine, di cui tratta la sezione successiva, e uno a una risorsa che una voce omits: ha lasciato fuori dal template, di cui tratta la sezione dopo ancora.

Valori per i parametri di un template di origine

Un template di origine riceve valori nel modo in cui CloudFormation stesso dà valori a un template: attraverso i Parameters che dichiara. Il valuesMapping di ciò che lo usa come sorgente — la Recipe di un componente, o la FeatureRecipe di una Feature associata — scrive una chiave per ogni parametro che valorizza, e il provider lega ciascuna in ogni template della sorgente — ogni Ref al parametro in Resources, Outputs, Conditions, Rules e nei Globals di SAM diventa il valore, ogni Fn::Sub che nomina il parametro come variabile riceve il valore attraverso la sua mappa di variabili, e il parametro esce dai Parameters di ogni template che lo dichiara. Un parametro che nessuna chiave nomina viene lasciato esattamente come l’ha scritto il template, per un valore passato quando lo stack viene distribuito o per il suo Default.

La sorgente è l’unità che dichiara un parametro. I template di una sorgente di tipo directory si assemblano in un unico stack, quindi un template può fare riferimento a un parametro dichiarato da un altro template della stessa sorgente. Valorizzare il parametro lo valorizza anche lì: un template che si limita a farvi riferimento riceve il valore così come lo ha convertito il primo template della sorgente che lo dichiara, e nulla nella sorgente continua a fare riferimento a un parametro la cui dichiarazione è stata rimossa dal binding.

Nient’altro nello stack può fare riferimento a un parametro valorizzato. Il contenuto esterno alla sorgente — il frammento o il template di origine di un altro componente nello stesso stack — che nomina un parametro valorizzato dal binding della sorgente, tramite Ref, una variabile di Fn::Sub o il Fn::ValueOf di una regola, nominerebbe qualcosa che lo stack assemblato non dichiara più, cosa che CloudFormation rifiuta quando lo stack viene distribuito. Quindi la build si arresta, nominando ogni componente, il suo template e il parametro, e il componente il cui valuesMapping lo ha valorizzato — quello di una Recipe, o della FeatureRecipe di una Feature associata; una Feature associata a un componente viene nominata da quel componente, e una associata a un confine dall’identità che le sue risorse portano come aggrega.ai/component-id, composta dal percorso del confine e dal nome dell’associazione (bfr--stack--aux per un’associazione aux sul confine stack). Arresta la build anche il frammento del componente a cui è associata una Feature, o di un componente nel confine a cui è associata, che fa riferimento a un parametro valorizzato dal binding dell’associazione. Un nome che lo stack dichiara ancora non è interessato: dove un altro componente dichiara esso stesso un parametro con quel nome, o una risorsa lo porta come proprio ID logico, i suoi riferimenti si risolvono in quella dichiarazione e vengono lasciati come sono scritti. Per trasmettere il valore, fai in modo che il componente che lo valorizza lo pubblichi, dichiara il parametro nel template che vi fa riferimento, oppure rimuovi la chiave dal 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 }}"

Solo un valuesMapping valorizza i parametri. Le chiavi che scrive sono i nomi di parametro che intendevi per il template, quindi ciascuna deve nominare un parametro che qualche template della sorgente dichiara: una chiave che non ne nomina nessuno arresta la build, nominando la chiave e i parametri che ciascun template dichiara effettivamente — l’errore che CloudFormation segnalerebbe per un parametro sconosciuto, segnalato mentre sta ancora a te risolverlo. Una Recipe o una FeatureRecipe che non dichiara alcun valuesMapping non valorizza nulla: i valori propri del componente o dell’associazione raggiungono il provider con i loro nomi, scritti per i suoi altri input, e restano non letti.

Ciò che un valore è decide ciò che raggiunge il template.

  • Un letterale — una stringa, un numero, un booleano, o una lista di questi — viene scritto nel template, convertito nel modo in cui CloudFormation converte lo stesso valore passato per il Type del parametro quando lo stack viene distribuito: un Number diventa la stringa che restituisce un Ref a esso, quindi 7 arriva come "7"; un tipo CommaDelimitedList o List<…> diventa una lista di stringhe, accettando o una lista o una stringa separata da virgole i cui membri vengono privati degli spazi; ogni altro tipo accetta una sola stringa. Un letterale viene controllato rispetto ai AllowedValues, AllowedPattern, MinLength, MaxLength, MinValue e MaxValue del parametro stesso, e uno che questi rifiutano arresta la build, nominando il parametro e il vincolo, così valorizzare un parametro non rimuove alcun controllo che il template ha dichiarato. Un pattern scritto in una sintassi di espressioni regolari che la build non sa leggere viene lasciato al controllo di CloudFormation quando lo stack viene distribuito.
  • Un valore che è interamente una funzione intrinseca di CloudFormation raggiunge il punto del riferimento come quella funzione intrinseca, perché CloudFormation la valuti quando lo stack viene distribuito: una mappatura in forma lunga come {"Fn::GetAtt": [Queue, Arn]}, oppure una stringa che è esattamente una forma breve — !GetAtt Queue.Arn, !Ref Bucket, !Sub … e le altre forme che CloudFormation definisce. È così che il riferimento pubblicato da un altro componente raggiunge un parametro: le Recipes CloudFormation del catalogo pubblicano un riferimento del genere come testo in forma breve, e un valuesMapping che lo legge dal contesto di iniezione lo trasmette. Un riferimento inserito si legge allo stesso modo tra virgolette o senza. Tra virgolette — "{{ .context.inject.env.BUCKET_NAME }}" — la mappatura trasmette la stringa !GetAtt Queue.Arn; senza virgolette, lo YAML stesso della mappatura legge !GetAtt Queue.Arn come un tag, e il tag viene mantenuto con il suo argomento anziché essere scartato. In entrambi i casi raggiunge il parametro come funzione intrinseca. Un valore che si limita a iniziare con un punto esclamativo, o che non nomina alcuna forma breve di CloudFormation, resta testo.
  • Un riferimento dinamico — {{resolve:ssm:…}}, {{resolve:ssm-secure:…}} o {{resolve:secretsmanager:…}} — raggiunge il punto del riferimento così come è scritto, perché CloudFormation lo risolva quando lo stack viene distribuito, quindi il valore che nomina non è mai nel template.
  • Un valore che un altro componente pubblica da uno stack diverso raggiunge il template come riferimento tra stack, lo stesso Fn::ImportValue o Fn::GetStackOutput che riceve un frammento (vedi Cablaggio tra stack), in ogni punto in cui il template faceva riferimento al parametro.

Un parametro il cui tipo CloudFormation legge da Parameter Store — AWS::SSM::Parameter::Value<…> — non ha alcun letterale che riproduca ciò che CloudFormation ne farebbe, quindi un letterale legato a uno di questi arresta la build; lega un riferimento {{resolve:ssm:…}} o una funzione intrinseca, oppure lascialo non legato. Arresta la build anche una lista legata a un parametro che il template nomina come variabile di Fn::Sub, perché una variabile sostituisce una sola stringa. Arresta la build allo stesso modo una chiave che il valuesMapping imposta a null, nominando il parametro, perché un parametro accetta un valore e null non lo è; per lasciare un parametro a un valore passato quando lo stack viene distribuito o al suo Default, lascia la sua chiave fuori dalla mappatura.

Una regola che legge un parametro per nome lo mantiene non legato. Fn::ValueOf nelle Rules di un template nomina un parametro dichiarato tramite il suo ID logico anziché tramite Ref, e valorizzare il parametro rimuove la sua dichiarazione, quindi legare un parametro che una regola legge in quel modo arresta la build, nominando la regola e il parametro.

Un letterale che può portare un segreto viene rifiutato; una funzione intrinseca viene scritta così come è data. Un valore scritto nel template è leggibile da chiunque possa leggere il template dello stack:

  • Un parametro che il template dichiara NoEcho accetta un riferimento dinamico o una funzione intrinseca, e un letterale legato a esso arresta la build.
  • Dove il valuesMapping legge un valore che un autore ha dichiarato sensibile, nessuna parte del suo output può essere ricondotta al valore da cui proviene, quindi ogni letterale che lega arresta la build. Un riferimento dinamico e una funzione intrinseca che lega vengono scritti così come sono dati — compreso il testo all’interno di una funzione intrinseca. Un segreto che la mappatura inserisce nel testo di un Fn::Sub, per esempio, raggiunge quindi il template come quel testo: solo un riferimento dinamico tiene il segreto stesso fuori dal template. Dove una build del genere prosegue, stampa anche un avviso per ogni foglia dichiarata, per la mappatura di una Recipe come per quella della FeatureRecipe di una Feature associata a un componente, nominando la foglia e l’entità a cui appartiene la mappatura — vedi A declared-sensitive value reaches the target through a values mapping (Un valore dichiarato sensibile raggiunge la destinazione attraverso una mappatura di values).
  • Un riferimento dinamico arresta la build dove il suo parametro è referenziato nella proprietà UserData di una risorsa, nei metadati AWS::CloudFormation::Init o in Outputs: CloudFormation non risolve un riferimento dinamico nei dati utente EC2 né in quei metadati, e mostra Outputs a chiunque legga lo stack.

Ogni rifiuto di questo tipo nomina i parametri, e non cita alcun valore.

Lasciare risorse fuori da un template di origine

Le risorse di un template di origine sono sue: i valori lo raggiungono solo attraverso i parametri che dichiara, quindi un template recuperato da un repository git che dichiara una risorsa che la Release non deve creare — un bucket che l’operatore fornisce già, una chiave che la piattaforma gestisce altrove — non può essere modificato da un valore. È a questo che servono le voci omits: di una Recipe o di una FeatureRecipe. Questo provider le rispetta su un template di origine e su nient’altro: i frammenti che una voce artifacts: scrive vengono renderizzati senza di esse.

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

Una voce nomina una risorsa tramite il suo Type e il suo ID logico. Il kind della voce è il Type della risorsa, come AWS::S3::Bucket, e il suo name è l’ID logico della risorsa, la sua chiave sotto Resources; entrambi vengono confrontati esattamente come sono scritti, ed entrambi devono corrispondere, quindi una voce il cui Type è giusto e il cui ID logico non lo è non lascia fuori nulla. Un template non ha namespace, quindi una voce che porta un namespace arresta la build quando il componente viene renderizzato, nominando la voce; ogni voce viene verificata prima che qualsiasi cosa venga lasciata fuori.

Ogni template della sorgente viene confrontato. Una sorgente a file singolo ha un template. Una sorgente di tipo directory — e una sorgente recuperata da un repository git lo è sempre — ha ogni file che termina con .yaml, .yml, .json o .template, e una voce lascia fuori ogni risorsa che nomina in uno qualsiasi di essi; un file portato insieme ai template non viene mai letto. Il provider riporta quante risorse ciascuna voce ha lasciato fuori in tutti quanti, e una voce che non ne ha lasciata fuori nessuna arresta la build; vedi An omits entry left out nothing the source rendered (Una voce omits non ha lasciato fuori nulla di ciò che la sorgente ha renderizzato).

Una risorsa lasciata fuori sparisce prima che qualsiasi altra cosa legga il template. Non viene marcata con la provenienza, non viene contata tra i nomi che lo stack porta — quindi un altro componente può contribuire una risorsa con lo stesso ID logico senza che le due si incontrino — e non raggiunge mai lo stack assemblato. Tutto il resto del template viene scritto esattamente come sarebbe stato se il template fosse stato scritto senza la risorsa, e un template di cui ogni risorsa viene lasciata fuori mantiene una sezione Resources vuota.

Una risorsa lasciata fuori non deve restare nominata da ciò che rimane, perché CloudFormation rifiuta un template che nomina una risorsa che non dichiara. Una volta rimosse le risorse, ogni riferimento che i template rimanenti fanno ancora a una di esse arresta la build, e il messaggio nomina il template, la risorsa, il modo in cui il riferimento la nomina e il punto in cui il riferimento si trova, come percorso dalla radice del template — /Resources/Store/Properties/LoggingConfiguration/DestinationBucketName, ad esempio. Un riferimento è ciò che la guida di riferimento dei template di CloudFormation definisce come nominare una risorsa tramite il suo ID logico, letto nel corpo di ogni risorsa — comprese le sue proprietà, i suoi metadati e le sue policy — e in ogni output:

  • Ref, con l’ID logico come argomento;
  • Fn::GetAtt, come lista il cui primo elemento è l’ID logico, oppure come un’unica stringa — !GetAtt StoreLogs.Arn — il cui testo prima del primo punto lo è;
  • il DependsOn di una risorsa, come un singolo ID logico o una lista di essi;
  • ogni variabile di Fn::Sub, nella sua forma stringa e nella sua forma lista: ${StoreLogs} e ${StoreLogs.Arn} nominano entrambe StoreLogs.

Alcuni valori sembrano soltanto riferimenti e non vengono letti come tali. ${!StoreLogs} è testo letterale, e una variabile nominata dalla mappa della forma lista è il valore di quella mappa. Il Condition di una risorsa e il primo argomento di Fn::If nominano una condizione, Fn::FindInMap nomina una mappatura, Fn::ImportValue un export di un altro stack e Fn::GetAZs una regione. Le sezioni Conditions, Mappings, Parameters e Rules non possono nominare una risorsa, e la sezione Metadata di primo livello propria del template è un’informazione che CloudFormation conserva anziché leggere, quindi nessuna di esse viene verificata. Un Ref o un Fn::GetAtt il cui ID logico è a sua volta scritto come funzione intrinseca è valido solo con la trasformazione AWS::LanguageExtensions, che lo risolve quando lo stack viene distribuito (vedi Sezioni di primo livello nello stack assemblato), quindi non nomina alcuna risorsa che la verifica possa leggere e viene lasciato com’è; lo stesso vale per un riferimento a una risorsa che la sorgente non ha mai dichiarato.

La verifica legge insieme i template propri della Recipe o della FeatureRecipe dichiarante. Si assemblano in un unico stack, quindi un riferimento a un ID logico che un altro di quei template dichiara ancora non viene fermato. Nient’altro viene letto: un riferimento a una risorsa lasciata fuori arresta la build anche dove un altro componente dichiara una risorsa con quell’ID logico, e un riferimento fatto da qualsiasi altra cosa che si assembla nello stack — un altro componente, una Feature associata o le voci artifacts: della Recipe stessa — non è uno che questa verifica vede, quindi CloudFormation rifiuta lo stack quando viene distribuito. Per mantenere un riferimento, mantieni la risorsa. Un valore associato a un parametro sostituisce solo un riferimento a quel parametro, quindi un riferimento a una risorsa è proprio del template e non può essere modificato da un valore: lascia fuori anche la risorsa che lo fa, oppure rimuovi la voce. Un output non è una risorsa e nessuna voce ne nomina uno, quindi una risorsa che gli Outputs del template nominano non può esserne lasciata fuori: lasciarla fuori arresta la build.

Annotazioni di destinazione cloud

Tre annotazioni di confine indicano al provider dove viene distribuito uno stack, così che possa cablare correttamente i riferimenti tra stack:

  • aggrega.ai/aws-account — l’account AWS in cui viene distribuito lo stack.
  • aggrega.ai/aws-region — la regione AWS in cui viene distribuito lo stack.
  • aggrega.ai/aws-assume-role-arn — l’ARN del ruolo IAM che una lettura di stack tra account diversi assume per raggiungere i valori esportati di uno stack omologo.

Queste annotazioni sono opache per il compilatore — ne convoglia i valori fino al provider senza interpretarli (vedi well-known-annotations.md). Vengono scritte sul confine del produttore — lo stack che possiede il valore esportato. Una lettura tra account diversi assume un ruolo nell’account del produttore, quindi l’account, la regione e il ruolo che descrivono la lettura provengono tutti dalle annotazioni del confine del produttore, non da quelle del consumatore.

Riferimenti all’interno dello stack

Quando un arco uses collega due componenti che finiscono nello stesso confine — lo stesso stack — il valore consumato viene cablato come un Fn::GetAtt sull’ID logico della risorsa del produttore all’interno dell’unico template. Il valore provides del produttore confluisce nell’input renderizzato del consumatore come riferimento nativo all’interno dello stack; non serve alcun export né import. Il frammento del consumatore può scrivere un tale valore senza virgolette — Value: {{ .context.inject.env.DB_HOST }} — oppure tra virgolette — Value: "{{ .context.inject.env.DB_HOST }}": in entrambi i casi il template legge !GetAtt Db.Endpoint.Address come funzione intrinseca, perché una stringa che è esattamente una forma breve raggiunge lo stack come quella funzione intrinseca in un frammento così come in un valuesMapping. L’esempio aws-rds-and-ecs-service lo mostra in una task definition di Amazon ECS che legge l’indirizzo di un’istanza RDS in un unico stack.

Cablaggio tra stack

Quando un arco uses passa da un confine a un altro — i due componenti si assemblano in stack diversi — il riferimento non può essere un valore semplice, perché il valore prodotto non esiste finché lo stack del produttore non viene distribuito. Il provider lo cabla come riferimento tra stack di CloudFormation. Lo stack produttore pubblica il valore come Output dello stack con un Export sotto un nome di export deterministico (derivato dalla release, dal confine, dal componente e dalla chiave fornita). Lo stack consumatore lo legge con una di due funzioni intrinseche, scelta confrontando la collocazione dichiarata dei due confini:

  • Fn::ImportValue — il caso con lo stesso account e la stessa regione. CloudFormation risolve l’import rispetto al nome di export corrispondente all’interno dell’account e della regione.
  • Fn::GetStackOutput — una vera lettura tra account o tra regioni diversi. Il consumatore legge direttamente l’output dello stack produttore, assumendo il ruolo aws-assume-role-arn del confine del produttore nell’account e nella regione del produttore.

Semantica del rilevamento. Il provider instrada verso Fn::GetStackOutput solo quando entrambi gli endpoint dichiarano una collocazione (account/regione) e quelle collocazioni differiscono. In ogni altro caso — nessuno dei due la dichiara, solo uno la dichiara, oppure entrambi dichiarano la stessa collocazione — usa Fn::ImportValue. È una regola conservativa: una lettura tra stack nello stesso account resta un semplice import, e la funzione intrinseca di lettura diretta è riservata a un vero passaggio tra account o tra regioni diversi.

Lo stack produttore pubblica sempre l’Export, anche quando un determinato consumatore lo legge tra account diversi tramite Fn::GetStackOutput. Un export inutilizzato è inerte, e pubblicarlo incondizionatamente mantiene il template del produttore indipendente dal modo in cui ciascun consumatore sceglie di leggere il valore.

Più consumatori di un valore leggono un unico export. Quando più di un componente legge lo stesso valore fornito attraverso un confine — due consumatori in uno stack, o consumatori in più stack — lo stack produttore pubblica l’Export di quel valore una sola volta, e ogni consumatore legge l’unico nome: ogni Fn::ImportValue importa lo stesso export, e un consumatore collocato in un altro account o in un’altra regione legge lo stesso output tramite Fn::GetStackOutput. Un consumatore che legge anche un valore che nessun altro consumatore legge aggiunge soltanto l’export di quel valore.

L’esempio aws-rds-and-ecs-service costruisce il caso con lo stesso account: lo stack di un’istanza RDS esporta ogni voce che l’arco di un server consuma, e lo stack del server rilegge ciascuna con Fn::ImportValue.

Nota sulla versione. Fn::GetStackOutput è una funzione intrinseca nativa di CloudFormation. Un riferimento tra account diversi renderizzato con essa richiede strumenti CloudFormation che riconoscano la funzione intrinseca. Il percorso con lo stesso account usa Fn::ImportValue, che è disponibile ovunque.

Un valore letto dalla connessione anziché iniettato

La Recipe di un consumatore può leggere i valori di un produttore direttamente dalla connessione, tramite .context.uses.<alias>.provides, anziché riceverli attraverso il blocco inject della connessione. Attraverso il bordo di uno stack, una lettura di questo tipo viene cablata nello stesso modo di un valore iniettato:

  • Un valore che è una funzione intrinseca di CloudFormation — un tag in forma breve come !GetAtt Db.Endpoint.Address, oppure un Ref o una mappatura Fn:: in forma lunga — nomina qualcosa che solo lo stack del produttore dichiara, quindi il consumatore riceve lo stesso riferimento tra stack che riceve un valore iniettato: lo stack produttore pubblica un Export per quella chiave, e il consumatore lo legge con Fn::ImportValue, oppure con Fn::GetStackOutput dove i due confini dichiarano collocazioni che differiscono.
  • Un valore che è testo semplice — una porta, un protocollo, il nome di un database — significa la stessa cosa in entrambi gli stack, quindi il consumatore riceve il valore stesso e per esso non viene pubblicato alcun export. Arriva nella forma in cui CloudFormation lo legge: un valore scritto per intero viene renderizzato come sarebbe stato senza il confine, e un valore dall’aspetto numerico scritto tra virgolette arriva come numero.

Se un valore sia una funzione intrinseca lo decide questo provider, leggendo il valore nel modo in cui legge il blocco provides proprio del produttore. Il compilatore consegna il valore così come l’ha scritto la Recipe del produttore e non lo interpreta.

Un template può soltanto copiare un valore di questo tipo. Può scrivere il valore per intero, o all’interno di una stringa più lunga, oppure passarlo attraverso una funzione che lo lascia com’è, come quote. Un confronto, una diramazione, una lunghezza o una funzione che cambia il valore — eq, if, len, upper — verrebbero decisi rispetto a qualcosa di diverso dal valore, perché su una connessione di questo tipo il template riceve un segnaposto che il provider sostituisce una volta assemblati entrambi gli stack. La build invece si arresta, nominando il template e ogni valore che ha letto, con la connessione da cui l’ha letto e il componente a ciascun capo; basa la diramazione su un valore proprio del componente consumatore. Lo stesso vale per l’injectMapping di una FeatureRecipe associata e per una FeatureRecipe con ambito di confine che legge le connessioni del confine. Un valore scritto all’interno di una stringa più lunga incontra anche il limite proprio del provider: un riferimento tra stack può comparire solo come valore intero, quindi una funzione intrinseca scritta all’interno di una stringa più lunga arresta la build, come accade per un valore iniettato.

Come viene costruito un nome di export

Le quattro parti sono unite da un doppio trattino, e ciascuna parte viene scritta con le lettere, le cifre e i trattini di cui è fatto un nome di export. Una lettera o una cifra viene portata così come è scritta, e lo stesso vale per un trattino all’interno di una parte — payments-db resta payments-db. Qualsiasi altro carattere viene scritto come una breve sequenza di escape che si apre con -z: una barra come -zs, un trattino basso come -zu, un punto come -zd. Una parte senza alcun valore viene scritta -ze. Un nome di stack viene costruito nello stesso modo a partire dalla release e dal confine.

Così l’export che pubblica host dal componente db, nel confine la cui directory di output sotto dist/ è stack-a/cloudformation, della release orders, è:

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

La rilettura è univoca, e questo è il punto anziché un vezzo: poiché una parte non contiene mai due trattini di fila e non termina mai con uno, i doppi trattini sono sempre le giunzioni. Due insiemi di parti diversi producono quindi sempre due nomi diversi. payments-db e payments_db raggiungono due export separati anziché convergere su uno, e un trattino all’estremità di una parte non può essere letto come appartenente alla parte vicina.

Rispetto a che cosa un nome di export è univoco, e dove questo si ferma

All’interno di una build, un nome di export identifica esattamente una release, un confine, un componente e una chiave fornita — due di essi non convergono mai su un unico nome, quindi una build non può perdere un valore esportato dietro un altro.

CloudFormation richiede inoltre che un nome di export sia univoco rispetto a tutto ciò che è già distribuito nell’account e nella regione in cui finisce lo stack. Questa è una proprietà della distribuzione anziché della build, e si trova oltre ciò che qualsiasi derivazione al momento della build può raggiungere: il compilatore non si autentica presso AWS, non lo interroga e non può leggere l’output di un’altra build, quindi nulla di calcolato in anticipo può osservare ciò che vi è già distribuito.

Ciò che porta la distinzione oltre quella linea è l’identità della release che apre ogni nome di export e di stack. Due distribuzioni che condividono un account e una regione tengono separati i loro export essendo rilasciate con nomi diversi — che è la leva che hai in mano, e il motivo per cui l’identità della release apre il nome anziché chiuderlo.

Una voce di Outputs può dichiarare il proprio nome di export

Il blocco Outputs: di una Recipe è CloudFormation scritto dall’autore, e una voce al suo interno può portare un proprio Export: con un Name:. Quel nome raggiunge lo stack assemblato esattamente come è scritto — il provider non lo riscrive, non gli aggiunge un prefisso e non richiede che somigli a uno derivato.

Di solito non c’è altro da dire. Un nome di export scritto dall’autore che non corrisponde a nessun nome derivato dal provider viene pubblicato accanto a quelli derivati e non viene mai segnalato. Scriverlo è supportato; solo una coincidenza non lo è.

La build si arresta quando un nome di export scritto dall’autore è uguale a uno che il provider deriva per un collegamento tra confini nella stessa build. Entrambe le dichiarazioni raggiungerebbero il template assemblato, lasciando un nome di export dichiarato due volte in uno stesso stack — e un nome di export deve essere univoco, quindi le due non possono coesistere. L’arresto riporta il nome di export derivato e le quattro parti da cui è stato costruito, così puoi vedere quale collegamento lo ha prodotto, e nomina l’output dello stack sotto cui si trova la dichiarazione scritta dall’autore, contrassegnato come un nome che il provider assembla anziché uno scritto da una Recipe. Il nome di export è il termine da cercare nelle tue Recipes. La voce scritta dall’autore lo scrive esattamente come l’arresto — è proprio questa identità a rendere le due una collisione — quindi è l’unica stringa che compare sia nel messaggio sia nei tuoi file. Rinominare il nome di export che quella voce dichiara elimina l’arresto, e lo stesso fa rimuovere il blocco Export: di quella voce lasciando che il cablaggio tra stack pubblichi l’export da sé.

Il controllo ha ambito di build, e il suo ambito è uno stack. Confronta i nomi di export che uno stack assemblato dichiara con i nomi che il provider deriva per i collegamenti tra confini che pubblicano in quello stesso stack — il confronto che la build può fare a partire da ciò che ha assemblato. Due stack non vengono confrontati tra loro. E ciò che un nome scritto dall’autore incontra tra gli export già distribuiti in un account e in una regione è una proprietà della distribuzione, che si trova oltre ciò che qualsiasi derivazione al momento della build può raggiungere, per il motivo esposto in Rispetto a che cosa un nome di export è univoco, e dove questo si ferma: il compilatore non si autentica presso AWS, non lo interroga e non può leggere l’output di un’altra build. Un nome di export scritto come funzione intrinseca anziché come stringa semplice si trova dall’altra parte della stessa linea — si risolve al momento della distribuzione, e nulla qui valuta una funzione intrinseca, quindi non c’è alcun nome che la build possa confrontare.

La build si arresta anche quando l’output su cui un collegamento tra confini pubblica porta già un Export che il collegamento non ha scritto. Quell’output è quello che il provider assembla per la chiave fornita che un consumatore legge, quindi una Recipe il cui blocco Outputs: scrive una voce sotto quella stessa chiave, con un proprio Export:, mette il suo export esattamente dove va quello del collegamento. A meno che il nome di quell’export sia esattamente quello che il provider deriva — nel qual caso è l’export del collegamento stesso e ogni consumatore lo importa — i due non possono coesistere lì: scrivere l’export del collegamento sovrascriverebbe il tuo, e mantenere il tuo lascerebbe ogni consumatore a importare un nome che il collegamento non ha pubblicato. L’arresto riporta il nome di export derivato e le quattro parti da cui è stato costruito, e dice che cosa ha trovato in quell’output: il nome di export che la voce dichiara, un nome scritto come funzione intrinseca, un blocco Export: che non nomina nulla, oppure un Export: scritto come valore semplice anziché come blocco. Rimuovere il blocco Export: di quella voce lo elimina, e il cablaggio tra stack pubblica allora l’export che ogni consumatore importa.

Ordine di distribuzione

Il valore syncWave: del confine di una Release ordina il provisioning dello stack in cui quel confine si assembla. Ogni componente del confine eredita l’ondata del confine, e dove più confini si risolvono nella stessa directory di output — così che i loro frammenti si assemblano in un unico template — lo stack contiene più di un’ondata e il provider esprime l’ordinamento tra di esse come DependsOn.

Ogni risorsa nomina ogni risorsa dell’ondata immediatamente precedente che abbia delle risorse, e nessuna ondata anteriore a quella. CloudFormation concatena il resto: una risorsa nell’ondata 2 dipende dall’ondata 1, che dipende dall’ondata 0, così l’intera sequenza è ordinata mentre la lista propria di ciascuna risorsa resta della dimensione di una sola ondata anziché dell’intero stack. Le ondate non devono essere contigue, e i valori negativi sono normali — -1 è una scelta comune per un bucket o un ruolo che il resto dello stack legge. L’ondata più bassa non nomina nulla, perché nulla la precede.

Che cos’è l’ordinamento: ordine di creazione e, al contrario, ordine di eliminazione. CloudFormation opera sulle risorse in parallelo nella misura in cui può, e DependsOn scavalca quel parallelismo per operare sulle risorse nominate in un ordine stabilito. L’attributo governa entrambe le direzioni, quindi un’ondata che crea una risorsa prima la elimina anche dopo — la corretta sequenza di smantellamento viene con l’ordinamento anziché richiedere altro.

Non è un ordinamento di prontezza. Un template di stack non esprime alcuna nozione di una risorsa utilizzabile, quindi nulla qui attende che una diventi pronta — solo che CloudFormation finisca di crearla. Questa è una differenza reale rispetto alla stessa ondata su compose, dove un servizio che dichiara un healthcheck viene atteso finché non risulta integro: compose ha una primitiva di prontezza su cui basare l’attesa e un template di stack non ne ha. L’ordine di creazione è ciò che questa destinazione offre, e dichiararlo apertamente è più utile di un’avvertenza attaccata a una promessa che non può mantenere.

Un DependsOn scritto dall’autore viene esteso, mai sostituito. Un frammento che dichiara un proprio vincolo di ordinamento lo mantiene: le voci che ha scritto restano per prime, nell’ordine in cui le ha scritte, e seguono le voci dell’ondata. Entrambi i requisiti valgono e nessuno nasconde l’altro. Vengono letti sia un singolo ID logico sia una lista, e il valore unito viene emesso come lista, che è l’unica forma che regge per quante che siano le voci prodotte dall’unione.

Uno stack le cui risorse portano tutte una sola ondata non ne ricava nulla. Lo stesso vale per una Release che non dichiara affatto syncWave: ogni contributore porta il valore predefinito del campo, 0, il template assemblato contiene una sola ondata, e l’output è esattamente quello che sarebbe se il provider non esprimesse alcun ordinamento per ondate.

L’ordinamento tra due stack non è esprimibile, e non viene approssimato. DependsOn nomina una risorsa all’interno dello stesso template, e i componenti che si assemblano in un altro stack ne sono fuori. Quindi un’ondata ordina ogni risorsa dello stack in cui si assembla e nulla oltre. Mettere in sequenza due stack è compito dell’operatore, nello stesso modo in cui un riferimento tra stack è una risoluzione al momento della distribuzione anziché al momento della build.

L’ordinamento che le ondate non esprimono resta una questione di CloudFormation stesso, e i riferimenti tra le risorse ne portano già gran parte: un Fn::GetAtt su una risorsa del produttore dice a CloudFormation di creare prima quella risorsa. Un frammento che ha bisogno di un vincolo che né i riferimenti né le ondate implicano scrive DependsOn da sé, che è il caso che l’unione descritta sopra preserva.

Determinismo

A parità di input il provider emette un template di stack identico byte per byte a ogni esecuzione: ID logici, chiavi di output, nomi di export e ordinamento delle risorse sono tutti deterministici, quindi un template di stack CloudFormation produce diff puliti nella revisione GitOps.