Modification directe d'un modèle Modification d'une valeur de paramètre d'entrée Détermination de la valeur du champ Replacement Ajout et suppression de ressources Affichage des modifications au niveau des propriétés

Exemples de jeux de modifications pour les piles CloudFormation

Cette section fournit des exemples de jeux de modifications qu'CloudFormation crée pour des modifications de pile habituelles. Ces exemples illustrent comment modifier un modèle directement, mettre à jour un paramètre d'entrée unique, planifier la recréation (ou le remplacement) des ressources (qui empêche de perdre les données qui n'étaient pas sauvegardées ou d'interrompre des applications en cours d'exécution dans votre pile) et comment ajouter ou supprimer des ressources. Pour décrire le fonctionnement des jeux de modifications, nous parcourrons les modifications qui ont été soumises et parlerons du jeu de modifications généré. Comme chaque exemple repose sur le précédent et présume que vous l'avez compris, nous vous recommandons de les lire dans l'ordre. Pour obtenir une description de chaque champ d'un jeu de modifications, veuillez consulter la rubrique Change dans la Référence d'API AWS CloudFormation.

Vous pouvez utiliser la console, AWS CLI ou l’opération API CloudFormation DescribeChangeSet pour afficher les détails des jeux de modifications.

Nous avons généré chacun des jeux de modifications suivants à partir d'une pile avec l’exemple de modèle :


{
  "AWSTemplateFormatVersion" : "2010-09-09",
  "Description" : "A sample EC2 instance template for testing change sets.",
  "Parameters" : {
    "Purpose" : {
      "Type" : "String",
      "Default" : "testing",
      "AllowedValues" : ["testing", "production"],
      "Description" : "The purpose of this instance."
    },
    "KeyPairName" : {
      "Type": "AWS::EC2::KeyPair::KeyName",
      "Description" : "Name of an existing EC2 KeyPair to enable SSH access to the instance"
    },
    "InstanceType" : {
      "Type" : "String",
      "Default" : "t2.micro",
      "AllowedValues" : ["t2.micro", "t2.small", "t2.medium"],
      "Description" : "The EC2 instance type."
    }
  },
  "Resources" : {
    "MyEC2Instance" : {
      "Type" : "AWS::EC2::Instance",
      "Properties" : {
        "KeyName" : { "Ref" : "KeyPairName" },
        "InstanceType" : { "Ref" : "InstanceType" },
        "ImageId" : "ami-8fcee4e5",
        "Tags" : [
          {
            "Key" : "Purpose",
            "Value" : { "Ref" : "Purpose" }
          }
        ]
      }
    }
  }
}

Modification directe d'un modèle

Lorsque vous modifiez directement des ressources dans le modèle de la pile afin de générer un jeu de modifications, CloudFormation considère qu'il s'agit d'une modification directe, par opposition aux modifications lancées par une valeur de paramètre mise à jour. Le jeu de modifications suivant, qui a ajouté une balise à l'instance i-1abc23d4, est un exemple de modification directe. Toutes les autres valeurs d'entrée, telles que les valeurs de paramètres et les capacités, restent les mêmes. Nous nous concentrerons donc sur la structure Changes.


{
    "StackId": "arn:aws:cloudformation:us-east-1:123456789012:stack/MyStack/1a2345b6-0000-00a0-a123-00abc0abc000",
    "Status": "CREATE_COMPLETE",
    "ChangeSetName": "SampleChangeSet-direct",
    "Parameters": [
        {
            "ParameterValue": "testing",
            "ParameterKey": "Purpose"
        },
        {
            "ParameterValue": "MyKeyName",
            "ParameterKey": "KeyPairName"
        },
        {
            "ParameterValue": "t2.micro",
            "ParameterKey": "InstanceType"
        }
    ],
    "Changes": [
        {
            "ResourceChange": {
                "ResourceType": "AWS::EC2::Instance",
                "PhysicalResourceId": "i-1abc23d4",
                "Details": [
                    {
                        "ChangeSource": "DirectModification",
                        "Evaluation": "Static",
                        "Target": {
                            "Attribute": "Tags",
                            "RequiresRecreation": "Never"
                        }
                    }
                ],
                "Action": "Modify",
                "Scope": [
                    "Tags"
                ],
                "LogicalResourceId": "MyEC2Instance",
                "Replacement": "False"
            },
            "Type": "Resource"
        }
    ],
    "CreationTime": "2020-11-18T23:35:25.813Z",
    "Capabilities": [],
    "StackName": "MyStack",
    "NotificationARNs": [],
    "ChangeSetId": "arn:aws:cloudformation:us-east-1:123456789012:changeSet/SampleChangeSet-direct/1a2345b6-0000-00a0-a123-00abc0abc000"
}

Dans Changes, il n'y a qu'une seule structure ResourceChange. Celle-ci décrit des informations, telles que le type de ressource qu'CloudFormation modifiera, l'action qu'CloudFormation effectuera, l'ID de la ressource et la portée de la modification, et elle détermine si la modification nécessite un remplacement (auquel cas CloudFormation crée une nouvelle ressource, puis supprime l'ancienne). Dans cet exemple, le jeu de modifications indique qu'CloudFormation modifiera l'attribut Tags de l'instance EC2 i-1abc23d4 et qu'il ne nécessite pas le remplacement de l'instance.

Dans la structure Details, CloudFormation marque cette modification comme une modification directe qui ne nécessite jamais la recréation (ni le remplacement) de l'instance. Vous pouvez exécuter cette modification en toute confiance, sachant qu'CloudFormation ne remplacera pas l'instance.

CloudFormation présente cette modification en tant qu'évaluation Static. Une évaluation statique signifie qu'CloudFormation peut déterminer la valeur de la balise avant l'exécution du jeu de modifications. Dans certains cas, CloudFormation ne peut déterminer une valeur qu'après l'exécution d'un jeu de modifications. CloudFormation marque ces modifications en tant qu'évaluations Dynamic. Par exemple, si vous référencez une ressource mise à jour qui est remplacée sous certaines conditions, CloudFormation ne peut pas déterminer si cette référence sera modifiée.

Modification d'une valeur de paramètre d'entrée

Lorsque vous modifiez une valeur de paramètre d'entrée, CloudFormation génère deux modifications pour chaque ressource qui utilise cette valeur. Dans cet exemple, nous souhaitons mettre en évidence ce à quoi ressemblent ces modifications, ainsi que les informations que vous devez cibler. L'exemple suivant a été généré en modifiant uniquement la valeur du paramètre d'entrée Purpose.

Le paramètre Purpose spécifie une valeur de clé de balise pour l'instance EC2. Dans cet exemple, la valeur de paramètre testing a été remplacée par production. La nouvelle valeur apparaît dans la structure Parameters.


{
    "StackId": "arn:aws:cloudformation:us-east-1:123456789012:stack/MyStack/1a2345b6-0000-00a0-a123-00abc0abc000",
    "Status": "CREATE_COMPLETE",
    "ChangeSetName": "SampleChangeSet",
    "Parameters": [
        {
            "ParameterValue": "production",
            "ParameterKey": "Purpose"
        },
        {
            "ParameterValue": "MyKeyName",
            "ParameterKey": "KeyPairName"
        },
        {
            "ParameterValue": "t2.micro",
            "ParameterKey": "InstanceType"
        }
    ],
    "Changes": [
        {
            "ResourceChange": {
                "ResourceType": "AWS::EC2::Instance",
                "PhysicalResourceId": "i-1abc23d4",
                "Details": [
                    {
                        "ChangeSource": "DirectModification",
                        "Evaluation": "Dynamic",
                        "Target": {
                            "Attribute": "Tags",
                            "RequiresRecreation": "Never"
                        }
                    },
                    {
                        "CausingEntity": "Purpose",
                        "ChangeSource": "ParameterReference",
                        "Evaluation": "Static",
                        "Target": {
                            "Attribute": "Tags",
                            "RequiresRecreation": "Never"
                        }
                    }
                ],
                "Action": "Modify",
                "Scope": [
                    "Tags"
                ],
                "LogicalResourceId": "MyEC2Instance",
                "Replacement": "False"
            },
            "Type": "Resource"
        }
    ],
    "CreationTime": "2020-11-18T23:59:18.447Z",
    "Capabilities": [],
    "StackName": "MyStack",
    "NotificationARNs": [],
    "ChangeSetId": "arn:aws:cloudformation:us-east-1:123456789012:changeSet/SampleChangeSet/1a2345b6-0000-00a0-a123-00abc0abc000"
}

La structure Changes fonctionne de manière similaire à l’exemple Modification directe d'un modèle. Il n'existe qu'une seule structureResourceChange. Elle décrit une modification apportée à l'attribut Tags de l'instance EC2 i-1abc23d4.

Toutefois, dans la structure Details, le jeu de modifications présente deux changements pour l'attribut Tags, même si une seule valeur de paramètre a été modifiée. Les ressources qui référencent une valeur de paramètre modifiée (à l'aide de la fonction intrinsèque Ref) entraînent toujours deux modifications : une avec une évaluation Dynamic et une autre avec une évaluation Static. Pour voir ces types de modification, consultez les champs suivants :

Pour la modification de l'évaluation Static, consultez le champ ChangeSource. Dans cet exemple, le champ ChangeSource équivaut à ParameterReference, ce qui signifie que cette modification est le résultat de la mise à jour de la valeur de référence du paramètre. Le jeu de modifications doit comporter une modification de l'évaluation Dynamic similaire.
Pour identifier la modification de l'évaluation Dynamic correspondante, comparez la structure Target des deux modifications, qui contient les mêmes informations. Dans cet exemple, la structure Target des deux modifications contient les mêmes valeurs pour les champs Attribute et RequireRecreation.

Pour ces types de modifications, concentrez-vous sur l'évaluation statique, qui fournit des informations plus détaillées sur la modification. Dans cet exemple, l'évaluation statique indique que le changement est le résultat de la modification de la valeur de référence du paramètre (ParameterReference). Le paramètre exact qui a été modifié est signalé par le champ CauseEntity (le paramètre Purpose).

Détermination de la valeur du champ Replacement

Le champ Replacement d'une structure ResourceChange indique si CloudFormation recréera la ressource. La planification de la recréation (ou du remplacement) de la ressource vous empêche de perdre les données qui n'étaient pas sauvegardées ou d'interrompre des applications en cours d'exécution dans votre pile.

La valeur du champ Replacement varie selon qu'une modification nécessite un remplacement, ce qui est indiqué par le champ RequiresRecreation dans la structure Target d'une modification. Par exemple, si le champ RequiresRecreation indique Never, le champ Replacement contient la valeur False. Toutefois, plusieurs modifications sont apportées à une seule ressource et si chacune d'elle a une valeur différente pour le champ RequiresRecreation, CloudFormation met à jour la ressource via le comportement le plus intrusif. En d'autres termes, si seulement l'une des nombreuses modifications nécessite un remplacement, CloudFormation doit remplacer la ressource et, par conséquent, définir le champ Replacement sur True.

Le jeu de modifications suivant a été généré en modifiant les valeurs pour tous les paramètres (Purpose, InstanceType et KeyPairName), qui sont toutes utilisées par l'instance EC2. Avec ces modifications, CloudFormation devra remplacer l'instance, car le champ Replacement équivaut à True.


{
    "StackId": "arn:aws:cloudformation:us-east-1:123456789012:stack/MyStack/1a2345b6-0000-00a0-a123-00abc0abc000",
    "Status": "CREATE_COMPLETE",
    "ChangeSetName": "SampleChangeSet-multiple",
    "Parameters": [
        {
            "ParameterValue": "production",
            "ParameterKey": "Purpose"
        },
        {
            "ParameterValue": "MyNewKeyName",
            "ParameterKey": "KeyPairName"
        },
        {
            "ParameterValue": "t2.small",
            "ParameterKey": "InstanceType"
        }
    ],
    "Changes": [
        {
            "ResourceChange": {
                "ResourceType": "AWS::EC2::Instance",
                "PhysicalResourceId": "i-7bef86f8",
                "Details": [
                    {
                        "ChangeSource": "DirectModification",
                        "Evaluation": "Dynamic",
                        "Target": {
                            "Attribute": "Properties",
                            "Name": "KeyName",
                            "RequiresRecreation": "Always"
                        }
                    },
                    {
                        "ChangeSource": "DirectModification",
                        "Evaluation": "Dynamic",
                        "Target": {
                            "Attribute": "Properties",
                            "Name": "InstanceType",
                            "RequiresRecreation": "Conditionally"
                        }
                    },
                    {
                        "ChangeSource": "DirectModification",
                        "Evaluation": "Dynamic",
                        "Target": {
                            "Attribute": "Tags",
                            "RequiresRecreation": "Never"
                        }
                    },
                    {
                        "CausingEntity": "KeyPairName",
                        "ChangeSource": "ParameterReference",
                        "Evaluation": "Static",
                        "Target": {
                            "Attribute": "Properties",
                            "Name": "KeyName",
                            "RequiresRecreation": "Always"
                        }
                    },
                    {
                        "CausingEntity": "InstanceType",
                        "ChangeSource": "ParameterReference",
                        "Evaluation": "Static",
                        "Target": {
                            "Attribute": "Properties",
                            "Name": "InstanceType",
                            "RequiresRecreation": "Conditionally"
                        }
                    },
                    {
                        "CausingEntity": "Purpose",
                        "ChangeSource": "ParameterReference",
                        "Evaluation": "Static",
                        "Target": {
                            "Attribute": "Tags",
                            "RequiresRecreation": "Never"
                        }
                    }
                ],
                "Action": "Modify",
                "Scope": [
                    "Tags",
                    "Properties"
                ],
                "LogicalResourceId": "MyEC2Instance",
                "Replacement": "True"
            },
            "Type": "Resource"
        }
    ],
    "CreationTime": "2020-11-18T00:39:35.974Z",
    "Capabilities": [],
    "StackName": "MyStack",
    "NotificationARNs": [],
    "ChangeSetId": "arn:aws:cloudformation:us-east-1:123456789012:changeSet/SampleChangeSet-multiple/1a2345b6-0000-00a0-a123-00abc0abc000"
}

Consultez chaque modification (évaluations statiques dans la structure Details) pour identifier celle qui nécessite le remplacement de la ressource. Dans cet exemple, chaque modification a une valeur distincte pour le champ RequireRecreation, mais la modification apportée à la propriété KeyName a le comportement de mise à jour le plus intrusif, ce qui implique toujours une recréation. CloudFormation remplacera l'instance car le nom de clé a été modifié.

Si le nom de clé n'avait pas changé, la modification de la propriété InstanceType aurait le comportement de mise à jour le plus intrusif (Conditionally). Le champ Replacement indiquerait Conditionally. Pour connaître les conditions dans lesquelles CloudFormation remplace l’instance, consultez le comportement de mise à jour de la propriété InstanceType du type de ressource AWS::EC2::Instance.

Ajout et suppression de ressources

L'exemple suivant a été généré en soumettant un modèle modifié qui supprime l'instance EC2 et ajoute un groupe Auto Scaling, ainsi qu'une configuration de lancement.


{
    "StackId": "arn:aws:cloudformation:us-east-1:123456789012:stack/MyStack/1a2345b6-0000-00a0-a123-00abc0abc000",
    "Status": "CREATE_COMPLETE",
    "ChangeSetName": "SampleChangeSet-addremove",
    "Parameters": [
        {
            "ParameterValue": "testing",
            "ParameterKey": "Purpose"
        },
        {
            "ParameterValue": "MyKeyName",
            "ParameterKey": "KeyPairName"
        },
        {
            "ParameterValue": "t2.micro",
            "ParameterKey": "InstanceType"
        }
    ],
    "Changes": [
        {
            "ResourceChange": {
                "Action": "Add",
                "ResourceType": "AWS::AutoScaling::AutoScalingGroup",
                "Scope": [],
                "Details": [],
                "LogicalResourceId": "AutoScalingGroup"
            },
            "Type": "Resource"
        },
        {
            "ResourceChange": {
                "Action": "Add",
                "ResourceType": "AWS::AutoScaling::LaunchConfiguration",
                "Scope": [],
                "Details": [],
                "LogicalResourceId": "LaunchConfig"
            },
            "Type": "Resource"
        },
        {
            "ResourceChange": {
                "ResourceType": "AWS::EC2::Instance",
                "PhysicalResourceId": "i-1abc23d4",
                "Details": [],
                "Action": "Remove",
                "Scope": [],
                "LogicalResourceId": "MyEC2Instance"
            },
            "Type": "Resource"
        }
    ],
    "CreationTime": "2020-11-18T01:44:08.444Z",
    "Capabilities": [],
    "StackName": "MyStack",
    "NotificationARNs": [],
    "ChangeSetId": "arn:aws:cloudformation:us-east-1:123456789012:changeSet/SampleChangeSet-addremove/1a2345b6-0000-00a0-a123-00abc0abc000"
}

Changes comporte trois structures ResourceChange, une pour chaque ressource. Pour chaque ressource, le champ Action indique si CloudFormation ajoute ou supprime la ressource. Les champs Scope et Details sont vides, car ils s'appliquent uniquement aux ressources modifiées.

Pour les nouvelles ressources, CloudFormation ne peut pas déterminer la valeur de certains champs tant que vous n'exécutez pas le jeu de modifications. Par exemple, CloudFormation ne fournit pas les ID physiques du groupe Auto Scaling et de la configuration de lancement, car ils n'existent pas encore. CloudFormation crée les ressources lorsque vous exécutez le jeu de modifications.

Affichage des modifications au niveau des propriétés

L’exemple suivant montre les modifications au niveau des propriétés de la propriété Tag d’une instance Amazon EC2. Les balises Value et Key seront remplacées par Test.


"ChangeSetName": "SampleChangeSet",
    "ChangeSetId": "arn:aws:cloudformation:us-east-1:123456789012:changeSet/SampleChangeSet/38d91d27-798d-4736-9bf1-fb7c46207807",
    "StackId": "arn:aws:cloudformation:us-east-1:123456789012:stack/SampleEc2Template/68edcdc0-f6b6-11ee-966c-126d572cdd11",
    "StackName": "SampleEc2Template",
    "Description": "A sample EC2 instance template for testing change sets.",
    "Parameters": [
        {
            "ParameterKey": "KeyPairName",
            "ParameterValue": "BatchTest"
        },
        {
            "ParameterKey": "Purpose",
            "ParameterValue": "testing"
        },
        {
            "ParameterKey": "InstanceType",
            "ParameterValue": "t2.micro"
        }
    ],
    "CreationTime": "2024-04-09T21:29:10.759000+00:00",
    "ExecutionStatus": "AVAILABLE",
    "Status": "CREATE_COMPLETE",
    "StatusReason": null,
    "NotificationARNs": [],
    "RollbackConfiguration": {
:...skipping...
{
    "Changes": [
        {
            "Type": "Resource",
            "ResourceChange": {
                "Action": "Modify",
                "LogicalResourceId": "MyEC2Instance",
                "PhysicalResourceId": "i-0cc7856a36315e62b",
                "ResourceType": "AWS::EC2::Instance",
                "Replacement": "False",
                "Scope": [
                    "Tags"
                ],
                "Details": [
                    {
                        "Target": {
                            "Attribute": "Tags",
                            "RequiresRecreation": "Never",
                            "Path": "/Properties/Tags/0/Value",
                            "BeforeValue": "testing",
                            "AfterValue": "Test",
                            "AttributeChangeType": "Modify"
                        },
                        "Evaluation": "Static",
                        "ChangeSource": "DirectModification"
                    },
                    {
                        "Target": {
                            "Attribute": "Tags",
                            "RequiresRecreation": "Never",
                            "Path": "/Properties/Tags/0/Key",
                            "BeforeValue": "Purpose",
                            "AfterValue": "Test",
                            "AttributeChangeType": "Modify"
                        },
                        "Evaluation": "Static",
                        "ChangeSource": "DirectModification"
                    }
                ],
                "BeforeContext": "{\"Properties\":{\"KeyName\":\"BatchTest\",\"ImageId\":\"ami-8fcee4e5\",\"InstanceType\":\"t2.micro\",\"Tags\":[{\"Value\":\"testing\",\"Key\":\"Purpose\"}]}}",
                "AfterContext": "{\"Properties\":{\"KeyName\":\"BatchTest\",\"ImageId\":\"ami-8fcee4e5\",\"InstanceType\":\"t2.micro\",\"Tags\":[{\"Value\":\"Test\",\"Key\":\"Test\"}]}}"
            }
        }
    ]

La structure Details affiche les valeurs de Key et Value avant l’exécution du jeu de modifications, ainsi que celles après l’exécution du jeu de modifications.

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

Supprimer un jeu de modifications

Modifier les ensembles pour les piles imbriquées