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

Mappatura degli eventi

Quando CloudFormation richiama 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 del modello di 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 sezione del modello. CloudFormation valuta questi parametri prima di passarli alla funzione.

Formato della risposta

CloudFormation si aspetta che la funzione Lambda restituisca una risposta nel seguente formato 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 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 Eventi della pagina dei Dettagli dello stack per lo stack.

  Per 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 CloudFormation macro

1. Crea una funzione Lambda che gestirà l'elaborazione dei contenuti del modello. Può elaborare qualsiasi parte di un modello, fino all'intero modello.

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

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

4. Crea uno stack utilizzando il modello con la macro nell'account in cui desideri utilizzarlo. Oppure, crea uno stack set con autorizzazioni autogestite utilizzando il modello con la macro nell'account amministratore, quindi crea istanze stack negli account di destinazione.

5. 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. Puoi utilizzare una macro facendo riferimento alla stessa in un modello, nella posizione appropriata relativa al contenuto del modello che desideri elaborare.

Ambito del modello di 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

È possibile fare riferimento a più macro in un determinato modello, incluse le trasformazioni ospitate da CloudFormation, ad esempio Trasformazione AWS::Include e. 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