Comment créer des piles directement Considérations Portée et autorisations du compte de macro

Présentation des macros CloudFormation

Il existe deux étapes principales pour le traitement des modèles à l'aide de macros : la création de la macro elle-même, puis l'utilisation de la macro pour effectuer un traitement sur vos modèles.

Pour créer une définition de macro, vous devez créer les éléments suivants :

Une fonction Lambda pour effectuer le traitement du modèle. Cette fonction Lambda accepte un extrait ou un modèle complet, ainsi que tous les paramètres supplémentaires que vous définissez. Elle renvoie l'extrait de modèle traité ou l'ensemble du modèle comme réponse.
Une ressource de type AWS::CloudFormation::Macro, qui permet aux utilisateurs d’appeler la fonction Lambda à partir des modèles CloudFormation. Cette ressource spécifie l'ARN de la fonction Lambda à appeler pour cette macro, ainsi que d'autres propriétés facultatives pour faciliter le débogage. Pour créer cette ressource dans un compte, créez un modèle qui inclut la ressource AWS::CloudFormation::Macro, puis créez une pile ou un ensemble de piles avec des autorisations autogérées à partir du modèle. CloudFormation Actuellement, StackSets ne prend pas en charge la création ou la mise à jour d'ensembles de piles avec des autorisations gérées par le service à partir de modèles qui référencent des macros .

Pour utiliser une macro, référencez la macro dans votre modèle :

Pour traiter une section ou une partie d’un modèle, référencer la macro dans une fonction Fn::Transform située par rapport au contenu du modèle que vous voulez transformer. Lorsque vous utilisez Fn::Transform, vous pouvez également transmettre tous les paramètres spécifiés qu'elle requiert.
Pour traiter un modèle complet, référencez la macro dans la section Transform du modèle.

En règle générale, vous créez ensuite un jeu de modifications que vous exécutez. (Le traitement des macros peut ajouter plusieurs ressources dont vous n’avez peut-être pas connaissance. Pour vous assurer que vous êtes informé de toutes les modifications introduites par les macros, nous vous recommandons vivement d’utiliser un jeu de modifications.) CloudFormation transmet le contenu du modèle spécifié, ainsi que tous les paramètres supplémentaires spécifiés, à la fonction Lambda spécifiée dans la ressource macro. La fonction Lambda renvoie le contenu de modèle traité, qu'il s'agisse d'un extrait ou d'un modèle complet.

Une fois que toutes les macros dans le modèle ont été appelées, CloudFormation génère un jeu de modifications qui inclut le contenu du modèle traité. Après avoir passé en revue le jeu de modifications, exécutez-le pour appliquer les modifications.

Utilisez la fonction intrinsèque Fn::Transform ou la section Transform du modèle pour transmettre le contenu du modèle et les paramètres associés à la fonction Lambda sous-jacente de la macro, qui renvoie le contenu du modèle traité.

Comment créer des piles directement

Pour créer ou mettre à jour une pile à l'aide d'un modèle qui référence des macros, en règle générale vous créez un jeu de modifications que vous exécutez ensuite. Un jeu de modifications décrit les actions qu'CloudFormation va entreprendre en fonction du modèle traité. Le traitement des macros peut ajouter plusieurs ressources à votre insu. Pour garantir que vous ayez connaissance de toutes les modifications apportées par les macros, nous vous suggérons vivement d'utiliser des jeux de modifications. Après avoir passé en revue le jeu de modifications, vous pouvez l'exécuter pour en appliquer les modifications.

Une macro peut ajouter des ressources IAM à votre modèle. Pour ces ressources, CloudFormation vous demande de confirmer leurs capacités. Comme CloudFormation ne peut pas savoir quelles ressources sont ajoutées avant de traiter votre modèle, vous devrez peut-être confirmer les capacités IAM lorsque vous créez l’ensemble de modifications, selon que les macros référencées contiennent ou non des ressources IAM. De cette façon, lorsque vous exécutez le jeu de modifications, CloudFormation dispose des capacités nécessaires pour créer des ressources IAM.

Pour créer ou mettre à jour une pile directement à partir d’un modèle traité sans examiner au préalable les modifications proposées dans un jeu de modifications, veuillez spécifier la capacité CAPABILITY_AUTO_EXPAND lors d’une demande CreateStack ou UpdateStack. Ne créez directement de piles à partir d'un modèle de pile qui contient des macros qu'à la condition de connaître les transformations effectuées par la macro. Vous ne pouvez pas utiliser de jeux de modifications avec des macros d'ensemble de piles. Vous devez mettre à jour votre ensemble de piles directement.

Pour plus d’informations, consultez CreateStack ou UpdateStack dans la Référence d’API AWS CloudFormation.

Important

Si votre modèle d'ensemble de piles référence une ou plusieurs macros, vous devez créer une pile directement à partir du modèle traité, sans examiner au préalable les modifications qui en résultent dans un jeu de modifications. Le traitement des macros peut ajouter plusieurs ressources à votre insu. Avant de créer ou de mettre à jour un ensemble de piles à partir d'un modèle qui référence directement les macros, assurez-vous de connaître les transformations effectuées par la macro.

Afin de réduire le nombre d’étapes nécessaires au lancement de piles à partir de modèles qui font référence à des macros, vous pouvez utiliser les commandes package et deploy d’AWS CLI. Pour plus d'informations, consultez Charger des artefacts locaux dans un compartiment S3 à l’aide de l’ AWS CLI et Créer une pile qui inclut des transformations.

Considérations

Lorsque vous travaillez avec des macros, veuillez garder à l’esprit les remarques et limitations suivantes :

Les macros ne sont prises en charge que dans les Régions AWS où Lambda est disponible. Pour obtenir une liste de toutes les régions où Lambda est actuellement disponible, veuillez consulter la rubrique Points de terminaison et quotas AWS Lambda.
Tout les extraits de modèle traités doivent être dans un format JSON valide.
Tous les extraits de modèle traités doivent réussir les vérifications de validation pour une opération de création ou de mise à jour de pile ou d'ensemble de piles.
CloudFormation résout d’abord les macros, puis traite le modèle. Le modèle résultant doit être dans un format JSON valide et ne doit pas dépasser la limite de taille de modèle.
En raison de l'ordre dans lequel CloudFormation traite les éléments d'un modèle, une macro ne peut pas inclure de modules dans le contenu du modèle traité qu'elle renvoie à CloudFormation. Pour de plus amples informations, consultez Ordre d’évaluation des macros.
Lors de l’utilisation de la fonctionnalité de restauration de mise à jour, CloudFormation utilise une copie du modèle d’origine. Le modèle d'origine est restauré même si l'extrait inclus a été modifié.
L’inclusion de macros dans des macros ne fonctionne pas, car nous ne traitons pas les macros de manière récursive.
La fonction intrinsèque Fn::ImportValue n'est pas actuellement prise en charge dans les macros.
Les fonctions intrinsèques incluses dans le modèle sont évaluées après les macros éventuelles. Par conséquent, le contenu de modèle traité que votre macro renvoie peut inclure des appels à des fonctions intrinsèques, et ils sont évalués comme d'habitude.
StackSets ne prend actuellement pas en charge la création ou la mise à jour d’ensembles de piles avec des autorisations gérées par le service à partir de modèles qui font référence à des macros CloudFormation.

Portée et autorisations du compte de macro

Vous pouvez utiliser des macros uniquement dans le compte où elles ont été créées en tant que ressource. Le nom de la macro doit être unique au sein d'un compte donné. Toutefois, vous pouvez mettre à disposition les mêmes fonctionnalités dans plusieurs comptes en permettant l'accès entre comptes sur la fonction Lambda, puis en créant des définitions de macro référençant cette fonction dans plusieurs comptes. Dans l'exemple ci-dessous, trois comptes contiennent des définitions de macro qui pointent toutes vers la même fonction Lambda.

En autorisant l’accès intercompte à la fonction Lambda, AWS vous permet de créer des macros dans plusieurs comptes qui font référence à cette fonction.

Afin de créer la définition d'une macro, l'utilisateur doit disposer d'autorisations pour créer une pile ou un ensemble de piles dans le compte spécifié.

Pour que CloudFormation puisse exécuter correctement une macro incluse dans un modèle, l’utilisateur doit disposer des autorisations Invoke pour la fonction Lambda sous-jacente. Pour empêcher l’escalade éventuelle des autorisations, CloudFormation emprunte l’identité de l’utilisateur lors de l’exécution de la macro.

Pour plus d’informations, consultez Gestion des autorisations dans AWS Lambda du Guide du développeur AWS Lambda et la section Actions, ressources et clés de condition pour AWS Lambda de la Référence d’autorisation de service.

Avertissement JavaScript est désactivé ou n'est pas disponible dans votre navigateur.

Pour que vous puissiez utiliser la documentation AWS, Javascript doit être activé. Vous trouverez des instructions sur les pages d'aide de votre navigateur.

Conventions de rédaction

Macros de modèle

Créer une définition de macro