Créer une définition de macro CloudFormation - 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éer une définition de macro CloudFormation

Lorsque vous créez une définition de macro, celle-ci rend la fonction Lambda sous-jacente disponible dans le compte spécifié afin que CloudFormation puisse l’invoquer pour traiter les modèles.

Mappage d’événements

Lorsque CloudFormation invoque la fonction Lambda d’une macro, il 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, consultez Portée du modèle de macro.

  • transformId

    Nom de la macro qui appelle cette fonction.

  • params

    Pour les appels de fonction Fn::Transform, 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 section Parameters 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. Ceci doit correspondre à l’ID de demande fourni par CloudFormation lorsqu’il invoque la fonction.

  • status

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

  • fragment

    Le contenu du modèle traité que CloudFormation doit inclure dans le modèle traité, y compris les éléments frères. CloudFormation remplace le contenu du modèle transmis à la fonction Lambda par le fragment de modèle qu’il 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 modifie pas réellement le contenu du modèle que CloudFormation lui transmet, mais que vous devez tout de même inclure ce contenu dans le modèle traité, votre fonction doit renvoyer ce contenu du modèle à CloudFormation dans sa réponse.

  • errorMessage

    Message d'erreur qui explique pourquoi la transformation a échoué. CloudFormation affiche ce message d'erreur dans le volet Événements de la page Détails 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 macro CloudFormation

  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 modèle CloudFormation contenant un type de ressource AWS::CloudFormation::Macro et spécifiez les propriétés Name et FunctionName. La propriété FunctionName doit contenir l’ARN de la fonction Lambda à invoquer lorsque CloudFormation exécute 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 journaux CloudWatch Logs auquel CloudFormation envoie les informations de journalisation des erreurs lors de l’invoquer de la fonction Lambda sous-jacente de la macro, ainsi que le rôle que CloudFormation 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 fois que CloudFormation a créé avec succès les piles contenant la définition de la macro, celle-ci est disponible pour ê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 les transformeurs hébergés par CloudFormation, tels que AWS::Include et 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 macro PolicyAdder, car c’est la macro la plus profondément imbriquée dans le modèle. CloudFormation évalue ensuite MyMacro avant d’évaluer AWS::Serverless, car elle est répertoriée avant AWS::Serverless dans la section 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