Esegui elaborazioni personalizzate su CloudFormation modelli con macro di modelli - AWS CloudFormation

Le traduzioni sono generate tramite traduzione automatica. In caso di conflitto tra il contenuto di una traduzione e la versione originale in Inglese, quest'ultima prevarrà.

Esegui elaborazioni personalizzate su CloudFormation modelli con macro di modelli

Con le macro, puoi eseguire elaborazioni personalizzate sui modelli, da azioni semplici come find-and-replace operazioni a trasformazioni estese di interi modelli.

Per avere un'idea della gamma di possibilità, prendete in considerazione le AWS::Serverless trasformazioni AWS::Include and, che sono macro ospitate da: CloudFormation

Come funzionano le macro CloudFormation

L'elaborazione di modelli mediante macro comporta due fasi principali: la creazione della macro stessa e quindi l'utilizzo della macro per eseguire l'elaborazione sui modelli.

Per creare una definizione di macro, devi creare quanto segue:

  • Una AWS Lambda funzione per eseguire l'elaborazione del modello. Questa funzione Lambda accetta un frammento di modello o un intero modello e qualsiasi parametro supplementare che definisci. Restituisce quindi l'intero modello o il frammento di modello elaborato come risposta.

  • Una risorsa di tipo AWS::CloudFormation::Macro, che consente agli utenti di chiamare la funzione Lambda dall'interno CloudFormation dei modelli. Questa risorsa specifica la ARN funzione Lambda da richiamare per questa macro e proprietà opzionali aggiuntive per facilitare il debug. Per creare questa risorsa all'interno di un account, crea un modello che includa la AWS::CloudFormation::Macro risorsa, quindi crea uno stack o un set di stack con le autorizzazioni gestite automaticamente dal modello. AWS CloudFormation StackSets attualmente non supporta la creazione o l'aggiornamento di set di stack con autorizzazioni gestite dai servizi da modelli che fanno riferimento alle macro.

Per utilizzare una macro, fai riferimento alla macro nel modello:

  • Per elaborare una sezione, o frammento, di un modello, fate riferimento alla macro in un funzione situata rispetto al contenuto del modello che desideri trasformare. Quando utilizzi Fn::Transform, puoi anche passare qualsiasi parametro specificato di cui necessita.

  • Per elaborare un intero modello, fai riferimento alla macro nella sezione Transform sezione per CloudFormation modelli del modello.

Quindi, crea in genere un set di modifiche ed eseguilo. (L'elaborazione delle macro può aggiungere più risorse di cui potresti non essere a conoscenza. Per assicurarti di conoscere tutte le modifiche introdotte dalle macro, ti consigliamo vivamente di utilizzare i set di modifiche.) CloudFormationpassa il contenuto del modello specificato, insieme a eventuali parametri aggiuntivi specificati, alla funzione Lambda specificata nella risorsa macro. La funzione Lambda restituisce il contenuto di modello elaborato, che si tratti di un frammento o di un intero modello.

Dopo aver chiamato tutte le macro del modello, CloudFormation genera un set di modifiche che include il contenuto del modello elaborato. Dopo aver esaminato il set di modifiche, eseguilo per applicare le modifiche.

Importante

Se il modello di set di stack contiene riferimenti a una o più macro, devi creare il set di stack direttamente dal modello elaborato, senza prima esaminare le modifiche risultanti in un set di modifiche. Per creare o aggiornare direttamente il set di stack, è necessario utilizzare l'UpdateStackSetazione CreateStackSeto e specificare la CAPABILITY_AUTO_EXPAND funzionalità. Prima di creare o aggiornare un set di stack da un modello che fa riferimento direttamente alle macro, assicurarsi di sapere che elaborazione eseguono le macro.

Utilizzate la funzione Fn::Transform intrinseca o la Transform sezione del modello per passare il contenuto del modello e i parametri associati alla Lambda funzione sottostante della macro, che restituisce il contenuto del modello elaborato.
Nota

Se si è in grado di creare o aggiornare uno stack direttamente da un modello elaborato, senza prima rivedere le modifiche proposte in un set di modifiche, puoi farlo specificando la funzionalità CAPABILITY_AUTO_EXPAND durante una richiesta CreateStack o UpdateStack. Devi creare stack unicamente direttamente da un modello che fa riferimento alle macro se si conosce l'elaborazione eseguita dalle macro.

Per ulteriori informazioni, vedere CreateStacko UpdateStacknel Reference.AWS CloudFormation API

Creazione di una definizione di CloudFormation macro

Quando si crea una definizione di macro, la definizione della macro rende disponibile la funzione Lambda sottostante nell'account specificato in modo che la CloudFormation richiami per elaborare i modelli.

CloudFormation interfaccia con funzione macro

Per le macro, CloudFormation richiama le funzioni Lambda sottostanti con la seguente mappatura degli eventi. CloudFormation invia la richiesta in JSON formato e si aspetta che anche la risposta della funzione venga formattata. JSON

{ "region" : "us-east-1", "accountId" : "$ACCOUNT_ID", "fragment" : { ... }, "transformId" : "$TRANSFORM_ID", "params" : { ... }, "requestId" : "$REQUEST_ID", "templateParameterValues" : { ... } }
  • Regione

    La Regione in cui si trova la macro.

  • accountId

    L'ID account dell'account da cui la macro richiama la funzione Lambda.

  • fragment

    Il contenuto del modello disponibile per l'elaborazione personalizzata, in JSON formato.

    • Per le macro incluse nella sezione Transform del modello, si tratta dell'intero modello tranne la sezione Transform.

    • Per le macro incluse nella chiamata della funzione intrinseca Fn::Transform, include tutti i nodi di pari livello (e i relativi figli) in base alla posizione della funzione intrinseca nel modello ad eccezione della funzione Fn::Transform. Per ulteriori informazioni, consulta CloudFormation ambito macro.

  • transformId

    Il nome della macro che richiama questa funzione.

  • params

    Per le chiamate di Fn::Transform funzione, qualsiasi parametro specificato per la funzione. CloudFormation non valuta questi parametri prima di passarli alla funzione.

    Per le macro incluse nella sezione Transform del modello, questa sezione è vuota.

  • requestId

    L'ID della richiesta che richiama questa funzione.

  • templateParameterValues

    Qualsiasi parametro specificato nella Parameters riferimento alla sintassi della sezione per i modelli CloudFormation sezione del modello. CloudFormation valuta questi parametri prima di passarli alla funzione.

CloudFormation si aspetta che la funzione sottostante restituisca una risposta nel formato seguente: JSON

{ "requestId" : "$REQUEST_ID", "status" : "$STATUS", "fragment" : { ... } "errorMessage": "optional error message for failures" }
  • requestId

    L'ID della richiesta che richiama questa funzione. Deve corrispondere all'ID della richiesta fornito da CloudFormation quando si richiama la funzione.

  • status

    Lo stato della richiesta (senza distinzione tra maiuscole e minuscole). Dovrebbe essere impostato su. success CloudFormation considera ogni altra risposta come un fallimento.

  • fragment

    Il contenuto del modello elaborato CloudFormation da includere nel modello elaborato, inclusi i fratelli. CloudFormation sostituisce il contenuto del modello passato alla funzione Lambda con il frammento di modello che riceve nella risposta Lambda.

    Il contenuto del modello elaborato deve essere valido JSON e la sua inclusione nel modello elaborato deve dare come risultato un modello valido.

    Se la funzione non modifica effettivamente il contenuto del modello CloudFormation che le viene trasmesso, ma è comunque necessario includere tale contenuto nel modello elaborato, la funzione deve restituire quel contenuto del modello CloudFormation nella sua risposta.

  • errorMessage

    Il messaggio di errore che spiega perché la trasformazione non è riuscita. CloudFormationvisualizza questo messaggio di errore nel riquadro Eventi della pagina dei dettagli dello stack relativa allo stack.

    Ad esempio, «Errore durante la creazione del set di modifiche: Transform Account AWS account number::macro name fallito con: error message string".

Per informazioni su ulteriori considerazioni relative alla creazione di macro, consulta Considerazioni sulla creazione di definizioni di macro CloudFormation .

CloudFormation ambito e autorizzazioni dell'account macro

Puoi utilizzare le macro solo nell'account in cui sono state create come risorsa. Il nome della macro deve essere univoco in un determinato account. Tuttavia, puoi rendere disponibile la stessa funzionalità in vari account abilitando l'accesso tra più account sulla funzione Lambda sottostante e quindi creando definizioni di macro che fanno riferimento a quella funzione in molteplici account. Nell'esempio seguente, tre account contengono definizioni di macro che puntano alla stessa funzione Lambda.

Consentendo l'accesso a più account alla Lambda funzione, AWS consente di creare macro in più account che fanno riferimento a tale funzione.

Per ulteriori informazioni, consulta Panoramica della gestione delle autorizzazioni di accesso alle risorse AWS Lambda nella Guida per AWS Lambda gli sviluppatori.

Per creare una definizione di macro, l'utente deve disporre delle autorizzazioni per creare uno stack o set di stack nell'account specificato.

CloudFormation Per eseguire correttamente una macro inclusa in un modello, l'utente deve disporre delle Invoke autorizzazioni per la funzione Lambda sottostante. Per evitare un potenziale aumento delle autorizzazioni, CloudFormation impersona l'utente durante l'esecuzione della macro. Per ulteriori informazioni, consulta il modello di autorizzazioni Lambda nella AWS Lambda Developer Guide e Actions and condition context keys AWS Lambda nella Guida per l'IAMutente.

Le Trasformazione AWS::Include trasformazioni Trasformazione AWS::Serverless e sono macro ospitate da. CloudFormation Non sono necessarie autorizzazioni speciali per utilizzarle e sono disponibili da qualsiasi account in. CloudFormation

Macro di debug CloudFormation

Per facilitare il debug, puoi anche specificare le proprietà LogGroupName e LogRoleArn quando crei il tipo di risorsa AWS::CloudFormation::Macro per la macro. Queste proprietà consentono di specificare il gruppo di CloudWatch log a cui CloudFormation inviare le informazioni di registrazione degli errori quando si richiama la AWS Lambda funzione sottostante della macro e il ruolo da CloudFormation assumere quando si inviano le voci di registro a tali registri.

Fatturazione

Quando una macro viene eseguita, al proprietario della funzione Lambda vengono addebitati i costi relativi all'esecuzione di quella funzione.

Le Trasformazione AWS::Include trasformazioni Trasformazione AWS::Serverless e sono macro ospitate da. CloudFormation Il loro utilizzo non comporta alcun costo.

Considerazioni sulla creazione di definizioni di macro CloudFormation

Quando crei definizioni di macro, considera quanto segue:

  • Le macro sono supportate solo Regioni AWS dove AWS Lambda sono disponibili. Per l'elenco delle Regioni in cui Lambda è disponibile, consulta l'argomento relativo a endpoint e quote di AWS Lambda.

  • Tutti i frammenti di modello elaborati devono essere validi. JSON

  • Qualsiasi frammento di modello elaborato deve superare controlli di convalida per un'operazione di creazione o aggiornamento di stack e creazione o aggiornamento di set di stack.

  • CloudFormation risolve prima le macro e poi elabora il modello. Il modello risultante deve essere valido JSON e non deve superare il limite di dimensione del modello.

  • A causa dell'ordine in cui CloudFormation elabora gli elementi in un modello, una macro non può includere moduli nel contenuto del modello elaborato a cui ritorna CloudFormation. Per ulteriori informazioni sui moduli, consulta Developing modules nella CloudFormation CLIUser Guide.

  • Quando si utilizza la funzione di ripristino dell'aggiornamento, CloudFormation utilizza una copia del modello originale. Il rollback del modello originale viene eseguito anche se il frammento incluso è stato modificato.

  • L'inclusione di macro all'interno delle macro non funziona perché non elaboriamo le macro in modo ricorsivo.

  • La funzione intrinseca Fn::ImportValue non è attualmente supportata nelle macro.

  • Le funzioni intrinseche incluse nel modello sono valutate dopo le macro. Pertanto, il contenuto di modello elaborato restituito dalla macro può includere chiamate alle funzioni intrinseche, che vengono valutate normalmente.

  • StackSets attualmente non supporta la creazione o l'aggiornamento di set di stack con autorizzazioni gestite dai servizi da modelli che fanno riferimento alle macro. CloudFormation

  • Se il modello di set di stack contiene riferimenti a una o più macro, devi creare o aggiornare il set di stack direttamente dal modello elaborato, senza prima esaminare le modifiche risultanti in un set di modifiche. Per creare o aggiornare direttamente lo stack set, utilizzate l'azione CreateStackSeto UpdateStackSete specificate la funzionalità. CAPABILITY_AUTO_EXPAND L'elaborazione di macro può aggiungere molteplici risorse di cui potresti non essere a conoscenza. Prima di creare o aggiornare un set di stack da un modello che fa riferimento direttamente alle macro, assicurarsi di sapere che elaborazione eseguono le macro.

  • I set di modifiche non supportano attualmente stack nidificati. Se desideri creare o aggiornare uno stack utilizzando un modello che fa riferimento a delle macro e contiene stack nidificati, devi creare o aggiornare lo stack direttamente. Per eseguire questa operazione, utilizzate l'UpdateStackazione CreateStacko e specificate la CAPABILITY_AUTO_EXPAND funzionalità.

Per creare una definizione di CloudFormation macro:
  1. Crea una AWS Lambda funzione che elabori i CloudFormation modelli.

    La funzione Lambda creata esegue l'elaborazione del contenuto di modello. La funzione può elaborare qualsiasi parte di un modello, fino all'intero modello. Per informazioni sulla mappatura di eventi alla quale la funzione deve aderire, consulta CloudFormation interfaccia con funzione macro. Per informazioni su ulteriori considerazioni relative alla creazione di macro, consulta Considerazioni sulla creazione di definizioni di macro CloudFormation .

  2. Crea un modello contenente un tipo di AWS::CloudFormation::Macro risorsa.

    • È necessario specificare le proprietà Name e FunctionName. La FunctionName proprietà specifica la ARN funzione Lambda da richiamare CloudFormation quando viene eseguita la macro.

    • Per facilitare il debug, è anche possibile specificare le proprietà LogGroupName e LogRoleArn.

  3. Creare uno stack a partire dal modello contenente la macro nell'account desiderato oppure creare un set di stack con autorizzazioni autogestite a partire dal modello che fa riferimento alla macro nell'account amministratore, quindi creare istanze stack negli account di destinazione desiderati .

    Dopo aver CloudFormation creato con successo gli stack che contengono la definizione della macro, la macro è disponibile per l'uso all'interno di tali account.

Utilizzo delle CloudFormation macro nei modelli

Dopo CloudFormation aver creato con successo gli stack che contengono la definizione della macro, la macro è disponibile per l'uso all'interno di tali account. Puoi utilizzare una macro facendo riferimento alla stessa in un modello, nella posizione appropriata relativa al contenuto del modello che desideri elaborare.

CloudFormation ordine di valutazione delle macro

È possibile fare riferimento a più macro in un determinato modello, incluse le trasformazioni ospitate da CloudFormation, ad esempio Trasformazione AWS::Include and. Trasformazione AWS::Serverless

Le macro vengono valutate nell'ordine, secondo la relativa posizione nel modello, da quella più nidificata a quella più generale. Le macro nella stessa posizione nel modello vengono valutate in serie in base all'ordine in cui sono elencate.

Le trasformazioni come AWS::Include e AWS::Transform vengono gestite come qualsiasi altra macro in termini di ordine e ambito dell'operazione.

Ad esempio, nell'esempio di modello riportato di seguito, CloudFormation valuta per prima cosa la PolicyAdder macro, perché è la macro con il nido più profondo del modello. CloudFormation quindi valuta MyMacro prima della valutazione AWS::Serverless perché è elencata in precedenza nella sezione. AWS::Serverless Transform

AWSTemplateFormatVersion: 2010-09-09 Transform: [MyMacro, AWS::Serverless] Resources: WaitCondition: Type: AWS::CloudFormation::WaitCondition MyBucket: Type: 'AWS::S3::Bucket' Properties: BucketName: amzn-s3-demo-bucket Tags: [{"key":"value"}] 'Fn::Transform': - Name: PolicyAdder CorsConfiguration: [] MyEc2Instance: Type: 'AWS::EC2::Instance' Properties: ImageID: ami-1234567890abcdef0

CloudFormation ambito macro

Le macro a cui si fa riferimento nella sezione Transform di un modello possono elaborare l'intero contenuto di quel modello.

Le macro a cui si fa riferimento in una funzione Fn::Transform possono elaborare il contenuto di qualsiasi elemento di pari livello (inclusi i figli) di quella funzione Fn::Transform nel modello.

Ad esempio, nell'esempio di modello seguente, AWS::Include può elaborare tutte le proprietà MyBucket in base alla posizione della funzione Fn::Transform che la contiene. MyMacro può elaborare il contenuto dell'intero modello per via della relativa inclusione nella sezione Transform.

# Start of processable content for MyMacro AWSTemplateFormatVersion: 2010-09-09 Transform: [MyMacro] Resources: WaitCondition: Type: AWS::CloudFormation::WaitCondition MyBucket: Type: 'AWS::S3::Bucket' # Start of processable content for AWS::Include Properties: BucketName: amzn-s3-demo-bucket1 Tags: [{"key":"value"}] 'Fn::Transform': - Name: 'AWS::Include' Parameters: Location: s3://amzn-s3-demo-bucket2/MyFileName.yaml CorsConfiguration: [] # End of processable content for AWS::Include MyEc2Instance: Type: 'AWS::EC2::Instance' Properties: ImageID: ami-1234567890abcdef0 # End of processable content for MyMacro

Set di modifiche e macro CloudFormation

Per creare o aggiornare uno stack utilizzando un modello che fa riferimento a macro, crea un set di modifiche e quindi eseguilo. Un set di modifiche descrive le azioni CloudFormation che verranno intraprese in base al modello elaborato. L'elaborazione di macro può aggiungere molteplici risorse di cui potresti non essere a conoscenza. Per assicurarti di essere a conoscenza di tutte le modifiche introdotte dalle macro, ti consigliamo di utilizzare set di modifiche. Dopo aver esaminato il set di modifiche, puoi eseguirlo per applicare le modifiche.

Una macro può aggiungere IAM risorse al modello. Per queste risorse, è CloudFormation necessario riconoscerne le capacità. Poiché non è CloudFormation possibile sapere quali risorse vengono aggiunte prima di elaborare il modello, potrebbe essere necessario riconoscere IAM le funzionalità al momento della creazione del set di modifiche, a seconda che le macro a cui si fa riferimento contengano IAM risorse. In questo modo, quando si esegue il set di modifiche, CloudFormation dispone delle funzionalità necessarie per creare IAM risorse.

Importante

Se il modello di set di stack contiene riferimenti a una o più macro, devi creare il set di stack direttamente dal modello elaborato, senza prima esaminare le modifiche risultanti in un set di modifiche. Per creare o aggiornare direttamente lo stack set, è necessario utilizzare l'UpdateStackSetazione CreateStackSeto e specificare la CAPABILITY_AUTO_EXPAND funzionalità. Prima di creare o aggiornare un set di stack da un modello che fa riferimento direttamente alle macro, assicurarsi di sapere che elaborazione eseguono le macro.

Nota

Se si è in grado di creare o aggiornare uno stack direttamente da un modello elaborato, senza prima rivedere le modifiche proposte in un set di modifiche, puoi farlo specificando la funzionalità CAPABILITY_AUTO_EXPAND durante una richiesta CreateStack o UpdateStack. È sufficiente creare stack direttamente da un modello di stack che contiene macro se si conosce l'elaborazione della macro. Non puoi utilizzare set di modifiche con macro di set di stack; è necessario aggiornare il set di stack direttamente.

Per ulteriori informazioni, vedere CreateStacko UpdateStacknella sezione AWS CloudFormation APIReference.

Se si utilizza il AWS CLI, è possibile utilizzare i deploy comandi package and per ridurre il numero di passaggi necessari per avviare pile di modelli che fanno riferimento alle macro. Per ulteriori informazioni, consulta la pagina relativa all'implementazione di applicazioni basate su Lambda nella Guida per gli sviluppatori di AWS Lambda .

Fase del modello e macro CloudFormation

La fase di un modello indica se il modello è il modello originale inviato dall'utente o quello in cui sono CloudFormation state elaborate le macro.

  • Original: il modello che l'utente ha originariamente inviato per creare o aggiornare lo stack o set di stack.

  • Processed: Il modello CloudFormation utilizzato per creare o aggiornare lo stack o il set di pile dopo l'elaborazione di tutte le macro a cui si fa riferimento. Il modello elaborato è formattato comeJSON, anche se il modello originale era formattato come. YAML

Utilizza il modello elaborato per la risoluzione dei problemi relativi allo stack. Se un modello non fa riferimento a macro, il modello originale e quello elaborato sono identici.

Puoi usare la CloudFormation console o AWS CLIvisualizzare la fase di un modello di pila.

Nota

La dimensione massima per un modello di stack elaborato è di 51.200 byte se passato direttamente in una ValidateTemplate richiestaCreateStack, oUpdateStack, o 1 MB se passato come oggetto S3 utilizzando un modello Amazon S3. URL Tuttavia, durante l'elaborazione CloudFormation aggiorna lo stato temporaneo del modello mentre elabora in serie le macro contenute nel modello. Per questo motivo, le dimensioni del modello durante l'elaborazione possono temporaneamente superare le dimensioni consentite di un modello completamente elaborato. CloudFormation consente un certo buffer per questi modelli in corso di elaborazione. Tuttavia, è opportuno progettare i modelli e le macro tenendo presenti le dimensioni massime consentite per un modello di stack elaborato.

Se CloudFormation restituisce un Transformation data limit exceeded errore durante l'elaborazione del modello, significa che il modello ha superato la dimensione massima CloudFormation consentita durante l'elaborazione.

Per risolvere questo problema, valutare se eseguire le seguenti operazioni:

Per utilizzare una CloudFormation macro nel modello
Nota

CloudFormation Per eseguire correttamente una macro a cui si fa riferimento in un modello, l'utente deve disporre delle Invoke autorizzazioni per la funzione Lambda sottostante. Per ulteriori informazioni, consulta Panoramica della gestione delle autorizzazioni di accesso alle risorse AWS Lambda nella Guida per AWS Lambda gli sviluppatori.

  1. Includere un riferimento alla macro nel modello.

    • Per elaborare un frammento di modello, fare riferimento alla macro in una funzione Fn::Transform posizionata in relazione al contenuto del modello che si intende elaborare.

    • Per elaborare l'intero modello, fare riferimento alla macro nella sezione Transform sezione per CloudFormation modelli del modello.

  2. Creare un set di modifiche utilizzando il modello.

    Importante

    Se il modello di set di stack contiene riferimenti a una o più macro, devi creare il set di stack direttamente dal modello elaborato, senza prima esaminare le modifiche risultanti in un set di modifiche. Per creare o aggiornare direttamente lo stack set, è necessario utilizzare l'UpdateStackSetazione CreateStackSeto e specificare la funzionalità. CAPABILITY_AUTO_EXPAND Prima di creare o aggiornare un set di stack da un modello che fa riferimento direttamente alle macro, assicurarsi di sapere che elaborazione eseguono le macro.

  3. Esaminare ed eseguire il set di modifiche.

    Importante

    Se il modello di set di stack contiene riferimenti a una o più macro, devi creare il set di stack direttamente dal modello elaborato, senza prima esaminare le modifiche risultanti in un set di modifiche. Per creare o aggiornare direttamente il set di stack, è necessario utilizzare l'UpdateStackSetazione CreateStackSeto e specificare la CAPABILITY_AUTO_EXPAND funzionalità. Prima di creare o aggiornare un set di stack da un modello che fa riferimento direttamente alle macro, assicurarsi di sapere che elaborazione eseguono le macro.

Esempi di macro

Oltre alla Esempio di macro: creazione e utilizzo di una macro procedura dettagliata di questa guida, nel nostro repository puoi trovare macro di esempio, tra cui codice sorgente e modelli. GitHub Questi esempi vengono forniti "così come sono" per scopi didattici.

Consulta anche

AWS:: :Macro CloudFormation

Transform sezione per CloudFormation modelli

Fn::Transform

Trasformazione AWS::Serverless

Trasformazione AWS::Include