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/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"
}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/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"
}A estrutura Changes funciona de maneira semelhante ao exemplo em 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/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"
}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/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"
}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.
