Exemplos de conjuntos de alterações
Esta seção fornece exemplos de conjuntos de alterações que o CloudFormation poderia criar para alterações de pilha comuns. Eles mostram como editar um modelo diretamente; modificar um único parâmetro de entrada; planejar a recriação de recursos (substituições) (o que evita a perda de dados que não foram colocados em backup ou a interrupção de aplicativos que estão em execução em sua pilha) e adicionar e remover recursos. Para ilustrar como os conjuntos de alterações funcionam, vamos acompanhar as alterações que foram enviadas e discutir o conjunto de alterações resultante. Como cada exemplo tem como fundamento o pressuposto de que você entendeu o exemplo anterior, recomendamos que você leia-os em sequência. Para obter uma descrição de cada campo em um conjunto de alterações, consulte o tipo de dados Change, na Referência de APIs do AWS CloudFormation.
Você pode usar o console, a AWS CLI ou a operação da API DescribeChangeSet do CloudFormation para visualizar detalhes de conjuntos de alterações.
Geramos cada um dos seguintes conjuntos de alterações de uma pilha com o seguinte modelo de exemplo
{ "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" } } ] } } } }
Editar um modelo diretamente
Quando você modifica diretamente os recursos no modelo de pilha para gerar um conjunto de alterações, o CloudFormation classifica a alteração como uma modificação direta, em oposição a alterações iniciadas por um valor de parâmetro atualizado. O conjunto de alterações a seguir, que adicionou uma nova tag à instância i-1abc23d4, é um exemplo de uma modificação direta. Todos os outros valores de entrada, como os valores de parâmetro e as capacidades, permanecem inalterados, assim podemos nos concentrar na estrutura de 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" }
Na estrutura de Changes, há apenas uma estrutura ResourceChange. Essa estrutura descreve informações como o tipo de recurso que o CloudFormation alterará, a ação que o CloudFormation realizará, o ID do recurso, o escopo da alteração e se ela requer uma substituição (em que o CloudFormation criará um novo recurso e, em seguida, excluirá o antigo). No exemplo, o conjunto de alterações indica que o CloudFormation modificará o atributo Tags da instância do EC2 i-1abc23d4 e não exigirá que a instância seja substituída.
Na estrutura Details, o CloudFormation rotula essa mudança como uma modificação direta que nunca exigirá que a instância seja recriada (substituída). Você pode executar essa mudança com confiança, sabendo que o CloudFormation não substituirá a instância.
O CloudFormation mostra essa mudança como uma avaliação Static. Uma avaliação estática significa que o CloudFormation pode determinar o valor da tag antes de executar o conjunto de alterações. Em alguns casos, o CloudFormation pode determinar um valor somente depois que você executar um conjunto de alterações. O CloudFormation rotula essas alterações como avaliações Dynamic. Por exemplo, se você fizer referência a um recurso atualizado que é substituído condicionalmente, o CloudFormation não poderá determinar se ela será alterada.
Modificar o valor de um parâmetro de entrada
Ao modificar o valor de um parâmetro de entrada, o CloudFormation gera duas alterações para cada recurso que usa o valor de parâmetro atualizado. Neste exemplo, queremos destacar como são essas alterações e em quais informações você deve se concentrar. O exemplo a seguir foi gerado alterando-se apenas o valor do parâmetro de entrada Purpose.
O parâmetro Purpose especifica um valor de chave de tag para a instância EC2. No exemplo, o valor do parâmetro foi alterado de testing para production. O novo valor é mostrado na estrutura 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" }
A estrutura Changes funciona de maneira semelhante ao exemplo em Como editar um modelo diretamente. Existe apenas uma estrutura ResourceChange. Ela descreve uma alteração no atributo Tags da instância EC2 i-1abc23d4.
No entanto, na estrutura Details, o conjunto de alterações mostra duas alterações para o atributo Tags, mesmo que apenas um único valor do parâmetro tenha sido alterado. Os recursos que fazem referência a um valor de parâmetro alterado (usando a função intrínseca Ref) sempre resultam em duas alterações: uma com uma avaliação Dynamic e outra com uma avaliação Static. Você pode ver esses tipos de alterações visualizando os seguintes campos:
-
Para alterar a avaliação
Static, visualize o campoChangeSource. Neste exemplo, o campoChangeSourceserá igual aParameterReference, o que significa que essa alteração é resultado de um valor de referência de parâmetro atualizado. O conjunto de alterações deve conter uma alteração similar na avaliaçãoDynamic. -
Você pode encontrar a alteração da avaliação
Dynamiccorrespondente comparando a estruturaTargetde ambas as alterações, que conterão as mesmas informações. Neste exemplo, as estruturasTargetdas duas alterações contêm os mesmos valores para os camposAttributeeRequireRecreation.
Para esses tipos de alterações, o foco na avaliação estático, que oferece mais informações detalhadas sobre a alteração. Neste exemplo, a avaliação estática mostra que a alteração é o resultado de uma modificação no valor de referência de um parâmetro (ParameterReference). O parâmetro exato que foi alterado é indicado pelo campo CauseEntity (o parâmetro Purpose).
Determinar o valor do campo Replacement
O campo Replacement em uma estrutura ResourceChange indica se o CloudFormation recriará o recurso. O planejamento da recriação de recursos (substituições) impede a perda de dados que não foram colocados em backup ou a interrupção de aplicativos que estão em execução em sua pilha.
O valor no campo Replacement depende de uma alteração exigir uma substituição ou não, o que é indicado pelo campo RequiresRecreation em uma estrutura Target da alteração. Por exemplo, se o campo RequiresRecreation for Never, o campo Replacement será False. No entanto, se houver várias alterações em um único recurso e cada uma tiver um valor diferente para o campo RequiresRecreation, o CloudFormation atualizará o recurso usando o comportamento mais intrusivo. Em outras palavras, se apenas uma das muitas alterações exigir uma substituição, o CloudFormation terá que substituir o recurso e, portanto, definir o campo Replacement como True.
O conjunto de alterações a seguir foi gerado pela alteração dos valores de cada parâmetro (Purpose, InstanceType, e KeyPairName), que são usados pela instância EC2. Com essas alterações, o CloudFormation terá que substituir a instância porque o campo Replacement é igual a 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" }
Identifique a alteração que requer a substituição do recurso, visualizando cada alteração (as avaliações estáticas na estrutura Details). Neste exemplo, cada alteração tem um valor diferente para o campo RequireRecreation, mas a alteração na propriedade KeyName tem o comportamento de atualização mais intrusivo, sempre exigindo uma recriação. O CloudFormation substituirá a instância porque o nome da chave foi alterado.
Se o nome da chave permanecesse inalterado, a alteração na propriedade InstanceType teria o comportamento de atualização mais intrusivo (Conditionally), assim o campo Replacement seria Conditionally. Para encontrar as condições em que o CloudFormation substitui a instância, veja o comportamento de atualização da propriedade InstanceType do tipo de recurso AWS::EC2::Instance.
Adicionar e remover recursos
O exemplo a seguir foi gerado enviando um modelo modificado que remove a instância EC2 e adiciona um grupo Auto Scaling e uma configuração de execução.
{ "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" }
Na estrutura Changes, há três estruturas ResourceChange, uma para cada recurso. Para cada recurso, o campo Action indica se o CloudFormation adiciona ou remove o recurso. Os campos Scope e Details estão vazios porque se aplicam somente a recursos modificados.
Para novos recursos, o CloudFormation não pode determinar o valor de alguns campos até que você execute o conjunto de alterações. Por exemplo, o CloudFormation não fornece os IDs físicos do grupo do Auto Scaling e configuração de execução, pois eles não existem ainda. O CloudFormation cria os novos recursos quando você executa o conjunto de alterações.
Visualizar alterações no nível da propriedade
O exemplo a seguir mostra as alterações no nível da propriedade feitas na propriedade Tag de uma instância do Amazon EC2. A tag Value e Key mudará para 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\"}]}}" } } ]
A estrutura Details mostra os valores de Key e Value antes da execução do conjunto de alterações e quais serão os valores após a execução do conjunto de alterações.
