Crea una definizione di macro CloudFormation - AWS CloudFormation
Mappatura degli eventiFormato della rispostaCrea una definizione di macro Ambito dei modelli delle macroOrdine di valutazione delle macro

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à.

Crea una definizione di macro CloudFormation

Quando crei una definizione di macro, questa rende la funzione Lambda sottostante disponibile nell’account specificato di modo che CloudFormation possa invocarla per elaborare i modelli.

Mappatura degli eventi

Quando CloudFormation invoca la funzione Lambda di una macro, invia una richiesta in formato JSON con la seguente struttura:

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

  • region

    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 di modello disponibile per l'elaborazione personalizzata, in formato JSON.

    • 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 Ambito dei modelli delle macro.

  • transformId

    Il nome della macro che richiama questa funzione.

  • params

    Per le chiamate della funzione Fn::Transform, 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 sezione Parameters del modello. CloudFormation valuta questi parametri prima di passarli alla funzione.

Formato della risposta

CloudFormation prevede che la funzione Lambda restituisca una risposta nel formato JSON seguente:

{
    "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 richiesta fornito da CloudFormation quando si richiama la funzione.

  • status

    Lo stato della richiesta (senza distinzione tra maiuscole e minuscole). Deve essere impostato su success. CloudFormation considera qualsiasi altra risposta come un errore.

  • fragment

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

    Il contenuto di modello elaborato deve essere in formato JSON valido e l'inclusione dello stesso nel modello elaborato deve generare un modello valido.

    Se la funzione non modifica effettivamente il contenuto di modello che CloudFormation passa alla stessa, ma è ancora necessario includere quel contenuto nel modello elaborato, la funzione deve restituire quel contenuto a CloudFormation nella relativa risposta.

  • errorMessage

    Il messaggio di errore che spiega perché la trasformazione non è riuscita. CloudFormation visualizza questo messaggio di errore nel riquadro Events (Eventi) della pagina Stack details (Dettagli stack) per lo stack.

    Ad esempio:

    Error creating change set: Transform
                            Account AWS account
                            number::macro name failed with:
                            error message string.

Crea una definizione di macro

Per creare una definizione di macro CloudFormation

  1. Crea una funzione Lambda che gestirà l’elaborazione dei contenuti del modello. La funzione può elaborare qualsiasi parte di un modello, anche l’intero modello.

  2. Crea un modello CloudFormation contenente un tipo di risorsa AWS::CloudFormation::Macro e specifica le proprietà Name e FunctionName. La proprietà FunctionName deve contenere l’ARN della funzione Lambda da invocare quando CloudFormation esegue la macro.

  3. (Opzionale) 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 log CloudWatch Logs al quale CloudFormation invia informazioni sulla registrazione degli errori quando viene invocata la funzione Lambda sottostante della macro, nonché il ruolo che CloudFormation deve assumere durante l’invio di voci di log a tali log.

  4. Crea uno stack utilizzando il modello con la macro nell’account in cui desideri utilizzarlo. In alternativa, crea un set di stack con autorizzazioni gestite dal cliente utilizzando il modello con la macro nell’account amministratore, quindi crea istanze stack negli account di destinazione.

  5. Dopo che CloudFormation ha creato lo stack contenente la definizione di macro, la macro è disponibile per l’uso in tali account. Puoi utilizzare una macro facendo riferimento alla stessa in un modello, nella posizione appropriata relativa al contenuto del modello che desideri elaborare.

Ambito dei modelli delle 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

Ordine di valutazione delle macro

Puoi fare riferimento a più macro in un determinato modello, incluse le trasformazioni ospitate da CloudFormation, ad esempio AWS::Include e 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, nel modello di esempio seguente, CloudFormation valuta dapprima la macro PolicyAdder poiché è la macro più nidificata nel modello. CloudFormation valuta quindi MyMacro prima di AWS::Serverless in quanto è elencata prima di AWS::Serverless nella sezione 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