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 Afficher les modifications apportées 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 une description de chaque champ d'un ensemble de modifications, voir le type de données de modification dans la AWS CloudFormation APIréférence.

Vous pouvez utiliser la console AWS CLI, ou CloudFormation DescribeChangeSetAPIopération pour afficher les détails du set 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/SampleStack/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": "SampleStack",
    "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-1abc23d4EC2instance 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'EC2instance. 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/SampleStack/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": "SampleStack",
    "NotificationARNs": [],
    "ChangeSetId": "arn:aws:cloudformation:us-east-1:123456789012:changeSet/SampleChangeSet/1a2345b6-0000-00a0-a123-00abc0abc000"
}

La Changes structure fonctionne de la même manière que dans l'Modification directe d'un modèleexemple. Il n'existe qu'une seule ResourceChange structure ; elle décrit une modification de l'Tagsattribut de l'i-1abc23d4EC2instance.

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'EC2instance. 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/SampleStack/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": "SampleStack",
    "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é AWS::EC2::InstanceType de ressource .

Ajout et suppression de ressources

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


{
    "StackId": "arn:aws:cloudformation:us-east-1:123456789012:stack/SampleStack/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": "SampleStack",
    "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 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.

Afficher les modifications apportées 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 AmazonEC2. Le tag Value et Key va devenirTest.


"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 Details structure indique les valeurs pour Key et Value avant l'exécution de l'ensemble de modifications, ainsi que ce qu'elles seront après l'exécution de l'ensemble 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 ensemble de modifications

Modifier les ensembles pour les piles imbriquées