Création d'une définition de CloudFormation macro - AWS CloudFormation
Mappage d’événementsFormat de la réponseCréer une définition de macroPortée du modèle de macroOrdre d’évaluation des macros

Les traductions sont fournies par des outils de traduction automatique. En cas de conflit entre le contenu d'une traduction et celui de la version originale en anglais, la version anglaise prévaudra.

Création d'une définition de CloudFormation macro

Lorsque vous créez une définition de macro, la définition de macro rend la fonction Lambda sous-jacente disponible dans le compte spécifié afin qu'elle l' CloudFormation invoque pour traiter les modèles.

Mappage d’événements

Lorsqu'elle CloudFormation invoque la fonction Lambda d'une macro, elle envoie une demande au format JSON avec la structure suivante :

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

  • region

    Région dans laquelle la macro réside.

  • accountId

    ID de compte du compte à partir duquel la macro appelle la fonction Lambda.

  • fragment

    Contenu de modèle disponible pour un traitement personnalisé, au format JSON.

    • Pour les macros incluses dans la section Transform du modèle, il s'agit du modèle complet à l'exception de la section Transform.

    • Pour les macros incluses dans un appel de fonction intrinsèque Fn::Transform, cela inclut tous les nœuds frères (et leurs enfants) en fonction de l'emplacement de la fonction intrinsèque au sein du modèle à l'exception de la fonction Fn::Transform. Pour de plus amples informations, veuillez consulter Portée du modèle de macro.

  • transformId

    Nom de la macro qui appelle cette fonction.

  • params

    Pour les appels de Fn::Transform fonction, tous les paramètres spécifiés pour la fonction. CloudFormation n'évalue pas ces paramètres avant de les transmettre à la fonction.

    Pour les macros incluses dans la section Transform du modèle, cette section est vide.

  • requestId

    ID de la demande qui appelle cette fonction.

  • templateParameterValues

    Tous les paramètres spécifiés dans la Parameters section du modèle. CloudFormation évalue ces paramètres avant de les transmettre à la fonction.

Format de la réponse

CloudFormation attend de la fonction Lambda qu'elle renvoie une réponse au format JSON suivant :

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

  • requestId

    ID de la demande qui appelle cette fonction. Cela doit correspondre à l'ID de demande fourni CloudFormation lors de l'appel de la fonction.

  • status

    Statut de la demande (non sensible à la casse). Doit être réglé sursuccess. CloudFormation traite toute autre réponse comme un échec.

  • fragment

    Le contenu du modèle traité CloudFormation à inclure dans le modèle traité, y compris les frères et sœurs. CloudFormation remplace le contenu du modèle transmis à la fonction Lambda par le fragment de modèle qu'elle reçoit dans la réponse Lambda.

    Le contenu de modèle traité doit être dans un format JSON valide et son inclusion dans le modèle traité doit engendrer un modèle valide.

    Si votre fonction ne change pas réellement le contenu de modèle qu' CloudFormation lui transmet, mais que vous devez encore inclure ce contenu dans le modèle traité, votre fonction a besoin de renvoyer ce modèle de contenu à CloudFormation , dans sa réponse.

  • errorMessage

    Message d'erreur expliquant pourquoi la transformation a échoué. CloudFormation affiche ce message d'erreur dans le volet Événements de la page d’Informations de la pile pour votre pile.

    Par exemple :

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

Créer une définition de macro

Pour créer une définition de CloudFormation macro

  1. Créez une fonction Lambda qui gérera le traitement du contenu du modèle. Elle peut traiter n’importe quelle partie d’un modèle, jusqu’au modèle entier.

  2. Créez un CloudFormation modèle contenant un type de AWS::CloudFormation::Macro ressource et spécifiez les FunctionName propriétés Name et. La FunctionName propriété doit contenir l'ARN de la fonction Lambda à invoquer lors de l' CloudFormation exécution de la macro.

  3. (Facultatif) Pour faciliter le débogage, vous pouvez également spécifier les propriétés LogGroupName et LogRoleArn lors de la création du type de ressource AWS::CloudFormation::Macro pour votre macro. Ces propriétés vous permettent de spécifier le groupe de CloudWatch journaux auquel CloudFormation envoie les informations de journalisation des erreurs lors de l'appel de la fonction Lambda sous-jacente de la macro, et le CloudFormation rôle doit assumer lors de l'envoi d'entrées de journal à ces journaux.

  4. Créez une pile à l’aide du modèle contenant la macro dans le compte dans lequel vous voulez l’utiliser. Ou bien, créez un ensemble de piles avec des autorisations autogérées à l’aide du modèle avec la macro dans le compte administrateur, puis créez des instances de pile dans les comptes cibles.

  5. Une CloudFormation fois que les piles contenant la définition de la macro ont été créées avec succès, la macro peut être utilisée dans ces comptes. Vous utilisez une macro en la référençant dans le modèle, à l'emplacement approprié correspondant au contenu de modèle que vous souhaitez traiter.

Portée du modèle de macro

Les macros référencées dans la section Transform d'un modèle peuvent traiter l'ensemble du contenu de ce modèle.

Les macros référencées dans une fonction Fn::Transform peuvent traiter le contenu de tous les éléments frères (y compris de leurs enfants) de cette fonction Fn::Transform dans le modèle.

Par exemple, dans l'exemple de modèle ci-dessous, AWS::Include peut traiter toutes les propriétés MyBucket, en fonction de l'emplacement de la fonction Fn::Transform qui les contient. MyMacro peut traiter le contenu du modèle complet en raison de son inclusion dans la section 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

Ordre d’évaluation des macros

Vous pouvez référencer plusieurs macros dans un modèle donné, y compris des transformations hébergées par CloudFormation, telles que AWS::Includeet AWS::Serverless.

Les macros sont évaluées dans l'ordre, en fonction de leur emplacement dans le modèle, du plus profondément imbriqué jusqu'au plus général. Les macros figurant dans le même emplacement dans le modèle sont évaluées en série en fonction de l'ordre dans lequel elles sont répertoriées.

Les transformations telles que AWS::Include et AWS::Transform sont traitées de la même manière que toutes les autres macros en termes d'ordre et de portée d'action.

Par exemple, dans l'exemple de modèle ci-dessous, CloudFormation évalue d'abord la PolicyAdder macro, car il s'agit de la macro la plus profondément imbriquée du modèle. CloudFormation évalue ensuite MyMacro avant d'évaluer AWS::Serverless car il est répertorié précédemment AWS::Serverless dans la Transform section.

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