Stack CloudFormation con associazioni
Un database gestito e l’applicazione che lo legge, scritti una sola volta come intento dello sviluppatore e assemblati in template di stack AWS CloudFormation. Due associazioni portano risorse proprie — un allarme sul database e un parametro di impostazioni condivise sul confine — quindi questo esempio mostra dove finiscono le risorse di un’associazione nello stack assemblato e come vengono nominate accanto a quelle del componente.
Lo stesso intento dello sviluppatore viene costruito in tre modi: come un unico stack, come due stack con un riferimento che passa dall’uno all’altro, e — deliberatamente — come un build che si arresta.
I blocchi di output in questa pagina sono copiati da un’esecuzione reale, secondo Leggere l’output in queste pagine.
File
aggregate.yaml— intento dello sviluppatore: un databasepayments-dbdi tipocore/datastore/mariadbe unreporting-appdi tipoexample/compute/db-readerche dichiara di usare il database. Nulla qui riguarda AWS. Il bloccofeatures:del database portastorage-headroom, che associaexample/storage-alarm.release-one-stack.yaml— entrambi i componenti in un unico confine, così entrambi si assemblano in un unico stack. Associacore/shared-configall’intero confine.release-two-stacks.yaml— lo stesso intento suddiviso su due confini, così il riferimento dell’applicazione al database attraversa il bordo di uno stack.release-negative-name-collision.yamlconaggregate-name-collision.yaml— destinato a fallire. Associa l’allarme due volte a un unico componente.manifest.yaml— vincola ogni tipo di componente e ogni Feature associata alla Recipe che lo implementa su questa destinazione..aggrega-config.yaml— nomina il registry dell’hub da cui si risolvono le entità del catalogo.
Ogni release vincola lo slot root_password del database nella sua voce per payments-db, con core/generated-secret. Su questa destinazione è RDS a possedere la password dell’amministratore, e la Recipe del database scelta dal Manifest porta la direttiva che lo dice; questo rende il vincolo una decisione dell’operatore, scritta nella Release, e l’Aggregate non ne dice nulla.
Ogni release associa anche core/backup a payments-db, con infra.retention_days: 14, e il Manifest la vincola a cloudformation/backup-native. RDS conserva i backup automatici dell’istanza per 7 giorni quando nulla indica altrimenti; questa associazione conserva ciascuno per 14. La FeatureRecipe non renderizza nulla: il backup è un’impostazione dell’istanza, quindi la Recipe del database legge l’associazione e scrive "BackupRetentionPeriod": 14 nelle Properties proprie dell’istanza.
Le entità usate da questo esempio risiedono tutte nel catalogo pubblicato. Nulla viene copiato accanto ai file di release, quindi l’esempio si risolve rispetto al catalogo così com’è anziché rispetto a una sua istantanea privata.
Generare l’esempio
Puoi eseguire la build di questo esempio con i comandi qui sotto, oppure farla eseguire al tuo assistente IA.
Scrivi l’esempio in una nuova cartella che porta il suo nome:
aggrega scaffold --example cloudformation-rds-stackPoi stampa i prossimi comandi da eseguire. Il primo ti porta nella nuova cartella:
cd cloudformation-rds-stackBuild
Questo esempio include tre release, quindi nomina quella che vuoi. Per ogni esecuzione viene eseguito il build di una sola release. Il primo build di ciascuna release ha bisogno del suo lockfile, che il comando pull scrive:
aggrega pull --release release-one-stack.yamlaggrega build --release release-one-stack.yamlIl build stampa, con <workspace> al posto della cartella di questo esempio:
Total build time: 4.1sBuild completed: 1 file written to <workspace>/distLo stack assemblato finisce in dist/one-stack/cloudformation/cloudformation-stack.json. Ogni componente e ogni associazione che renderizza in quella directory contribuisce a quell’unico template — il provider emette un unico stack in puro JSON anziché un file per ogni contributore.
Con un assistente AI
Un assistente IA configurato con gli strumenti di Aggrega può fare lo stesso: incolla questo prompt nell’assistente.
Usa solo gli strumenti di Aggrega e non creare alcuna cartella da solo. Se la cartella del workspace non contiene ancora una cartella `cloudformation-rds-stack`, chiama una volta lo strumento `scaffold` con `example` impostato a `cloudformation-rds-stack` e senza `dir`: scrive l’esempio in una nuova cartella `cloudformation-rds-stack`. Poi chiama lo strumento `build` con `workspace_root` impostato a `cloudformation-rds-stack`, `release` impostato a `release-one-stack.yaml`, `auto_pull` impostato a true e `write` impostato a true. Dimmi quali file ha scritto la build; si trovano in `cloudformation-rds-stack/dist/`.Che cosa finisce nello stack, e chi l’ha fornito
Il build a stack singolo assembla quattro risorse da quattro contributori diversi:
| Risorsa | Fornito da |
|---|---|
PaymentsDb | la Recipe propria del componente di database |
PaymentsDbStorageHeadroom | l’associazione storage-headroom su quel componente |
AppSharedConfig | l’associazione shared-settings sul confine |
ReportingApp | la Recipe propria del componente applicativo |
L’associazione backup su payments-db non compare nella tabella perché non fornisce alcuna risorsa propria: ciò che imposta finisce all’interno di PaymentsDb.
Ogni risorsa porta un blocco di provenienza che nomina il contributore da cui proviene, così le due metà restano distinguibili all’interno di uno stack a cui entrambe hanno contribuito:
"PaymentsDbStorageHeadroom": { "Metadata": { "aggrega.ai/provenance": { "aggrega.ai/aggregate-name": "aggregate", "aggrega.ai/boundary-path": "app", [… omitted: a compiler-version entry, which moves with the build] "aggrega.ai/component-id": "cfr--payments-db--storage-headroom", "aggrega.ai/environment": "production", "aggrega.ai/provider": "cloudformation", [… omitted: a provider-version entry, which moves with the build] "aggrega.ai/recipe-uri": "storage-alarm:1.0.0" } }, [… omitted: the alarm's Properties, printed in full just below] "Type": "AWS::CloudWatch::Alarm" },Le due voci di versione sono le uniche righe di questo blocco che cambiano tra un build e l’altro, ed è per questo che sono omesse; la terza omissione sono solo le Properties dell’allarme, stampate a parte più sotto. Tutto ciò che è mostrato è ciò che scrive il tuo stesso build.
L’allarme è la risorsa dell’associazione, non del database. Rimuovere storage-headroom dall’Aggregate elimina esattamente quella risorsa e l’unico output che pubblica, e lascia PaymentsDb identico byte per byte a com’era.
Il nome della risorsa di un’associazione porta l’ambito che porta l’associazione
Una Feature viene scritta una volta e associata molte volte, quindi il nome che una FeatureRecipe deriva deve essere distinto per ogni associazione. Questa compone il componente host e il nome dell’associazione: l’host payments-db, portato sotto storage-headroom, dà PaymentsDbStorageHeadroom.
Comporre solo l’host basterebbe a tenere l’allarme distinto dalla risorsa che sorveglia, e non basterebbe a impedire che la stessa Feature associata due volte a un componente entri in collisione con sé stessa — ed è di questo che tratta la release che fallisce più sotto.
Le proprietà dell’allarme stesso indirizzano l’host tramite il nome derivato dell’host:
"Properties": { "AlarmDescription": "Free storage below 21474836480 bytes on payments-db", "ComparisonOperator": "LessThanThreshold", "Dimensions": [ { "Name": "DBInstanceIdentifier", "Value": { "Ref": "PaymentsDb" } } ], "EvaluationPeriods": 2, "MetricName": "FreeStorageSpace", "Namespace": "AWS/RDS", "Period": 300, "Statistic": "Minimum", "Threshold": 21474836480, "TreatMissingData": "breaching" },Ref sulla risorsa del database si risolve nell’identificatore di quell’istanza quando lo stack viene distribuito. Entrambe le metà derivano PaymentsDb dallo stesso nome di componente, ed è questo che le fa concordare — qui nulla viene cercato.
Chi decide che cosa, su un’unica associazione
L’associazione suddivide i suoi input come fa un componente. Quanto margine serve all’applicazione è intento dello sviluppatore, scritto sull’associazione in aggregate.yaml — è una proprietà dell’applicazione. Dove notifica l’allarme, e quanto a lungo deve persistere un calo prima che scatti, sono dimensionamento dell’operatore, fornito dalla Release:
payments-db: features: storage-headroom: infra: evaluation_periods: 3 notify_target: "arn:aws:sns:eu-west-1:123456789012:payments-oncall"Una Release fornisce infra per un’associazione dichiarata dall’Aggregate, e mai values. La release a due stack imposta entrambi; la release a stack singolo non ne imposta nessuno, e la differenza si legge nell’output. Impostati:
"Properties": { "AlarmActions": [ "arn:aws:sns:eu-west-1:123456789012:payments-oncall" ],Non impostato, il campo è assente anziché vuoto — l’allarme viene emesso senza alcuna azione di notifica, e EvaluationPeriods ricade sul 2 che porta la Recipe anziché su qualcosa dichiarato dalla Feature. Una Release che non ne fornisce nessuno ottiene comunque un allarme funzionante, e fornirne uno aggiunge esattamente un campo.
Gli output di un’associazione prendono il nome dal suo host, non da essa stessa
Le due metà dello stack vengono nominate secondo regole diverse, e questa è la metà che sorprende.
L’ID logico di una risorsa viene dalla Recipe propria dell’associazione — il nome visto sopra. Un output prende il nome dal componente che pubblica e dalla voce insieme, e per un’associazione il componente che pubblica è l’host. L’allarme pubblica una voce, alarm-id, che compare come:
"paymentsXzhdbXXalarmXzhid": { "Value": { "Ref": "PaymentsDbStorageHeadroom" } },Le due metà si leggono una volta nota la regola: un ID logico ammette solo lettere e cifre, quindi il provider scrive per esteso ciò che quell’alfabeto rifiuta anziché scartarlo — Xzh è il trattino che hai scritto, e XX è il punto in cui finisce il nome del componente e inizia il nome della voce. payments-db che pubblica alarm-id, e nient’altro, arriva a quel nome. Nomi nello stack assemblato espone lo schema per intero.
È lo stesso nome di output a cui si sarebbe arrivati se alarm-id l’avesse pubblicato il database stesso. Quindi un nome di voce pubblicato anche dall’host incontrerebbe quello dell’associazione in un unico nome di output — ed è per questo che nomi di voce che si leggono come propri dell’associazione li tengono distinti da quelli dell’host.
Un’associazione estesa a tutto il confine viene renderizzata una sola volta per il confine
core/shared-config viene associata nella Release, sul confine anziché su un componente, e viene renderizzata una volta per quel confine — non una volta per ogni componente che contiene. Il build a stack singolo contiene due componenti ed esattamente un AppSharedConfig:
"AppSharedConfig": { [… omitted: the provenance Metadata, whose shape is shown above] "Properties": { "Description": "Settings shared by every component in the app boundary", "Name": "/app/shared-config", "Type": "String", "Value": "tier=production" }, "Type": "AWS::SSM::Parameter" },Esegui il build della release a due stack e il punto diventa più netto: ogni confine riceve il proprio, che porta le impostazioni risolte proprie di quel confine. Le Properties di quello presente in ciascuno dei due template che quel build scrive:
"Properties": { "Description": "Settings shared by every component in the data boundary", "Name": "/data/shared-config", "Type": "String", "Value": "tier=production-data" }, "Properties": { "Description": "Settings shared by every component in the app boundary", "Name": "/app/shared-config", "Type": "String", "Value": "tier=production-app" },Viene associata nella Release perché ciò che porta è un’organizzazione propria dell’operatore anziché qualcosa che l’Aggregate dichiara. Un’associazione di confine imposta infra: e mai values: — l’Aggregate resta il luogo in cui si scrivono i valori dello sviluppatore.
Suddividere lo stesso intento su due stack
aggrega pull --release release-two-stacks.yamlaggrega build --release release-two-stacks.yamlNulla cambia in aggregate.yaml. L’applicazione dichiara ancora di usare il database; l’operatore decide nella Release che i due vengano forniti separatamente, e di conseguenza il riferimento tra di essi attraversa il bordo di uno stack.
Nel build a stack singolo l’applicazione riceve l’endpoint come riferimento all’interno dell’unico template:
"Properties": { "Name": "/reporting/db-host", "Tier": "Standard", "Type": "String", "Value": { "Fn::GetAtt": [ "PaymentsDb", "Endpoint.Address" ] } },Nel build a due stack lo stack produttore pubblica quel valore come export:
"paymentsXzhdbXXhost": { "Value": { "Fn::GetAtt": [ "PaymentsDb", "Endpoint.Address" ] }, "Export": { "Name": "aggrega--cloudformation-two-stacks--two-stacks-data-zscloudformation--payments-db--host" } },e lo stack consumatore lo rilegge con quello stesso nome:
"Properties": { "Name": "/reporting/db-host", "Tier": "Standard", "Type": "String", "Value": {"Fn::ImportValue":"aggrega--cloudformation-two-stacks--two-stacks-data-zscloudformation--payments-db--host"} },Solo host porta un Export, perché è la voce che un arco consuma davvero; le altre voci pubblicate dal database compaiono come semplici output. L’allarme con ambito di componente segue il suo host nello stack produttore, e ogni confine mantiene la propria associazione estesa a tutto il confine.
Nessuna delle due funzioni intrinseche viene valutata al momento del build. L’endpoint non esiste finché lo stack non viene distribuito, quindi il compilatore convoglia il riferimento così com’è e CloudFormation lo risolve — ed è per questo che l’applicazione non nomina mai un indirizzo.
Per come viene costruito il nome di export, e per quando il consumatore legge tramite Fn::ImportValue anziché con una lettura diretta tra account diversi, vedi Cablaggio tra stack.
Il build che si arresta
aggrega pull --release release-negative-name-collision.yamlaggrega build --release release-negative-name-collision.yamlaggregate-name-collision.yaml associa l’allarme due volte a un componente, sotto due nomi di associazione. Il nome di risorsa di ciascuna associazione compone il nome della sua associazione, quindi i due allarmi sono due risorse distinte e lì non entrano in collisione. I loro output sì: ciascuno pubblica alarm-id, un output prende il nome dal componente host e dalla voce, e l’host è lo stesso componente per entrambi.
[… omitted: the pull's lines, which report the same collision while writing the lockfile][TRANSLATION_ERROR E0038] dispatch groups whose contributors derive one name more than once in one key space caused by (2): [TRANSLATION_ERROR] release-negative-name-collision.yaml derived name collision: one name is derived more than once in one key space ("paymentsXzhdbXXalarmXzhid", key space "output-logical-ids", derived by component "payments-db", carrying attachment "storage-headroom", provider "cloudformation", dispatch path "name-collision/cloudformation") --- [TRANSLATION_ERROR] release-negative-name-collision.yaml derived name collision: one name is derived more than once in one key space ("paymentsXzhdbXXalarmXzhid", key space "output-logical-ids", derived by component "payments-db", carrying attachment "storage-headroom-strict", provider "cloudformation", dispatch path "name-collision/cloudformation")Quattro cose da leggervi, e ciascuna è voluta.
- Vengono nominati entrambi i capi. Ogni voce indica il componente e il nome dell’associazione che portava, quindi entrambi si possono cercare nei file che hai scritto. Nulla in una collisione rende il nome di un contributore quello inteso, quindi vengono riportati entrambi anziché il primo.
- Viene nominato lo spazio delle chiavi.
output-logical-idsti dice quale dei due spazi dei nomi dello stack è stato raggiunto e — poiché lo spazio dei nomi delle risorse è assente da questo arresto — che i nomi delle risorse andavano bene. - Non viene emesso nulla. Il build si ferma anziché scrivere uno stack in cui uno dei due allarmi resta silenziosamente senza output.
- Dare nomi distinti alle risorse non risolve questo caso. Il nome di output è costruito dal componente host e dalla voce, quindi è la voce che deve differire — o una sola associazione anziché due, oppure una Feature i cui nomi di voce pubblicati si leggono come propri di quell’associazione.
Input identico, output identico
Eseguire due volte il build da input invariati produce template identici byte per byte. Il compilatore non risolve alcun dato live — non chiama mai AWS, non cerca mai un identificatore di account e non esegue mai CloudFormation — quindi una ricompilazione non ha nulla da scoprire che possa spostare i byte. È la proprietà su cui si basa una revisione basata sui diff.
dist/ e i file *.lock sono generati e non vengono sottoposti a commit; si rigenerano dai file che lo sono.