Exemplos de conjuntos de alterações - AWS CloudFormation

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, no AWS CloudFormation API Reference.

Você pode usar o console, a AWS CLI ou a API do CloudFormation para exibir 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 campo ChangeSource. Neste exemplo, o campo ChangeSource será igual a ParameterReference, 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ção Dynamic.

  • Você pode encontrar a alteração da avaliação Dynamic correspondente comparando a estrutura Target de ambas as alterações, que conterão as mesmas informações. Neste exemplo, as estruturas Target das duas alterações contêm os mesmos valores para os campos Attribute e RequireRecreation.

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, pois 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.

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 criará os novos recursos quando você executar o conjunto de alterações.