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 d'ensembles de modifications pour les CloudFormation piles

Cette section fournit des exemples d'ensembles de modifications qui CloudFormation pourraient être créés pour les modifications de pile courantes. 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 ou l' AWS CLI opération CloudFormation DescribeChangeSetAPI pour afficher les détails de l'ensemble 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. Cette structure décrit des informations telles que le type de ressource qui CloudFormation va changer, l'action CloudFormation à entreprendre, l'ID de la ressource, l'étendue de la modification et si la modification nécessite un remplacement ( CloudFormation création d'une nouvelle ressource puis suppression de l'ancienne). Dans l'exemple, l'ensemble de modifications indique que cela CloudFormation modifiera l'Tagsattribut de l'i-1abc23d4 EC2 instance et ne nécessite pas le remplacement de l'instance.

Dans la Details structure, CloudFormation qualifie cette modification de modification directe qui ne nécessitera jamais de recréer (remplacer) l'instance. Vous pouvez exécuter cette modification en toute confiance, en sachant que cela CloudFormation ne remplacera pas l'instance.

CloudFormation montre ce changement sous forme d'Staticévaluation. Une évaluation statique permet de déterminer la valeur de la balise avant d'exécuter l'ensemble de modifications. CloudFormation Dans certains cas, vous ne CloudFormation pouvez déterminer une valeur qu'après avoir exécuté un ensemble de modifications. CloudFormationqualifie ces modifications d'Dynamicévaluations. Par exemple, si vous faites référence à une ressource mise à jour qui est remplacée de manière conditionnelle, vous ne CloudFormation pouvez pas déterminer si la référence à la ressource mise à jour va changer.

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 la valeur de paramètre mise à jour. 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 Purpose paramètre spécifie une valeur de clé de balise pour l' EC2 instance. 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 ResourceChange structure ; elle décrit une modification de l'Tagsattribut de l'i-1abc23d4 EC2 instance.

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 Replacement champ d'une ResourceChange structure indique s'il est CloudFormation prévu de recréer 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, si plusieurs modifications sont apportées à une seule ressource et que chaque modification a une valeur différente pour le RequiresRecreation champ, CloudFormation met à jour la ressource en utilisant 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.

L'ensemble de modifications suivant a été généré en modifiant les valeurs de chaque paramètre (PurposeInstanceType,, etKeyPairName), qui sont tous utilisés par l' EC2 instance. Avec ces modifications, il CloudFormation sera nécessaire de remplacer l'instance car le Replacement champ est égal à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 différente pour le RequireRecreation champ, mais la modification apportée à la KeyName propriété présente le comportement de mise à jour le plus intrusif, nécessitant toujours une recréation. CloudFormation remplacera l'instance car le nom de la 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 l' CloudFormation instance est remplacée, consultez le comportement de mise à jour de la InstanceType propriété du type de AWS::EC2::Instanceressource.

Ajout et suppression de ressources

L'exemple suivant a été généré en soumettant un modèle modifié qui supprime l' EC2 instance, ajoute un groupe Amazon EC2 Auto Scaling et 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 Action champ indique si elle est CloudFormation ajoutée ou supprimée. Les champs Scope et Details sont vides, car ils s'appliquent uniquement aux ressources modifiées.

Pour les nouvelles ressources, CloudFormation vous ne pouvez pas déterminer la valeur de certains champs tant que vous n'avez pas exécuté l'ensemble de modifications. Par exemple, CloudFormation ne fournit pas le physique IDs du groupe Amazon EC2 Auto Scaling ni la configuration de lancement, car ils n'existent pas encore. CloudFormation crée les nouvelles ressources lorsque vous exécutez l'ensemble de modifications.

Affichage des modifications au niveau des propriétés

L'exemple suivant montre les modifications apportées au niveau de la propriété à la Tag propriété 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