Atualizar uma pilha do CloudFormation

Este tópico demonstra uma progressão simples de atualizações para uma pilha em execução. Demonstraremos as seguintes etapas:

Etapa 1: criar a pilha inicial

Vamos começar com a criação de uma pilha que possamos usar em todo o restante desta seção. Fornecemos um modelo simples que executa uma única aplicação web de instância PHP hospedada no Apache Web Server e em execução em uma AMI do Amazon Linux 2.

O Apache Web Server, o PHP e a aplicação PHP simples são instalados pelos scripts auxiliares do CloudFormation instalados por padrão na AMI do Amazon Linux 2. O trecho do modelo a seguir mostra os metadados que descrevem os pacotes e os arquivos a instalar, neste caso o Apache Web Server e a infraestrutura PHP do repositório Yum da AMI do Amazon Linux 2. O trecho também mostra a seção Services, que garante que o Apache Web Server esteja em execução.

WebServerInstance:
  Type: AWS::EC2::Instance
  Metadata:
    AWS::CloudFormation::Init:
      config:
        packages:
          yum:
            httpd: []
            php: []
        files:
          /var/www/html/index.php:
            content: |
              <?php
              echo '<h1>Hello World!</h1>';
              ?>
            mode: '000644'
            owner: apache
            group: apache
        services:
          systemd:
            httpd:
              enabled: true
              ensureRunning: true

A aplicação em si é um exemplo de “Hello World” totalmente definida dentro do modelo. Para um aplicativo do mundo real, os arquivos podem ser armazenados no Amazon S3, no GitHub ou em outro repositório e referenciados a partir do modelo. O CloudFormation pode baixar pacotes (como RPMs ou RubyGems) nem referenciar arquivos individuais e expandir arquivos .zip e .tar para criar os artefatos da aplicação na instância do Amazon EC2.

O modelo habilita e configura o daemon cfn-hup para receber alterações na configuração definida nos metadados da instância do Amazon EC2. Usando o daemon cfn-hup, você pode atualizar o software de aplicação, como a versão do Apache ou do PHP, ou o próprio arquivo da aplicação PHP no CloudFormation. O trecho a seguir do mesmo recurso do Amazon EC2 no modelo mostra os itens necessários para configurar o cfn-hup para chamar o cfn-init a cada dois minutos para observar e aplicar atualizações nos metadados. Caso contrário, o cfn-init só é executado uma vez na inicialização.

files:
  /etc/cfn/cfn-hup.conf:
    content: !Sub |
      [main]
      stack=${AWS::StackId}
      region=${AWS::Region}
      # The interval used to check for changes to the resource metadata in minutes. Default is 15
      interval=2
    mode: '000400'
    owner: root
    group: root
  /etc/cfn/hooks.d/cfn-auto-reloader.conf:
    content: !Sub |
      [cfn-auto-reloader-hook]
      triggers=post.update
      path=Resources.WebServerInstance.Metadata.AWS::CloudFormation::Init
      action=/opt/aws/bin/cfn-init -s ${AWS::StackId} -r WebServerInstance --region ${AWS::Region}
      runas=root
services:
  systemd:
    cfn-hup:
      enabled: true
      ensureRunning: true
      files:
        - /etc/cfn/cfn-hup.conf
        - /etc/cfn/hooks.d/cfn-auto-reloader.conf

Para concluir a pilha, na seção Properties da definição da instância do Amazon EC2, a propriedade UserData contém o script cloud-init que chama o cfn-init a fim de instalar os pacotes e arquivos. Para obter mais informações, consulte Referência de scripts auxiliares do CloudFormation no Guia de referência de modelos do CloudFormation. O modelo também cria um grupo de segurança do Amazon EC2.

AWSTemplateFormatVersion: 2010-09-09

Parameters:
  LatestAmiId:
    Description: The latest Amazon Linux 2 AMI from the Parameter Store
    Type: AWS::SSM::Parameter::Value<AWS::EC2::Image::Id>
    Default: '/aws/service/ami-amazon-linux-latest/amzn2-ami-hvm-x86_64-gp2'

  InstanceType:
    Description: WebServer EC2 instance type
    Type: String
    Default: t3.micro
    AllowedValues:
      - t3.nano
      - t3.micro
      - t3.small
      - t3.medium
      - t3a.nano
      - t3a.micro
      - t3a.small
      - t3a.medium
      - m5.large
      - m5.xlarge
      - m5.2xlarge
      - m5a.large
      - m5a.xlarge
      - m5a.2xlarge
      - c5.large
      - c5.xlarge
      - c5.2xlarge
      - r5.large
      - r5.xlarge
      - r5.2xlarge
      - r5a.large
      - r5a.xlarge
      - r5a.2xlarge
    ConstraintDescription: must be a valid EC2 instance type.
    
Resources:
  WebServerInstance:
    Type: AWS::EC2::Instance
    Properties:
      ImageId: !Ref LatestAmiId
      InstanceType: !Ref InstanceType
      SecurityGroupIds:
        - !Ref WebServerSecurityGroup
      UserData:
        Fn::Base64: !Sub |
          #!/bin/bash -xe
          # Get the latest CloudFormation package
          yum update -y aws-cfn-bootstrap
          # Run cfn-init
          /opt/aws/bin/cfn-init -v --stack ${AWS::StackName} --resource WebServerInstance --region ${AWS::Region} || error_exit 'Failed to run cfn-init'        
          # Start up the cfn-hup daemon to listen for changes to the EC2 instance metadata
          /opt/aws/bin/cfn-hup || error_exit 'Failed to start cfn-hup'
          # Signal success or failure
          /opt/aws/bin/cfn-signal -e $? --stack ${AWS::StackName} --resource WebServerInstance --region ${AWS::Region}
    Metadata:
      AWS::CloudFormation::Init:
        config:
          packages:
            yum:
              httpd: []
              php: []
          files:
            /var/www/html/index.php:
              content: |
                <?php
                echo "<h1>Hello World!</h1>";
                ?>
              mode: '000644'
              owner: apache
              group: apache
            /etc/cfn/cfn-hup.conf:
              content: !Sub |
                [main]
                stack=${AWS::StackId}
                region=${AWS::Region}
                # The interval used to check for changes to the resource metadata in minutes. Default is 15
                interval=2
              mode: '000400'
              owner: root
              group: root
            /etc/cfn/hooks.d/cfn-auto-reloader.conf:
              content: !Sub |
                [cfn-auto-reloader-hook]
                triggers=post.update
                path=Resources.WebServerInstance.Metadata.AWS::CloudFormation::Init
                action=/opt/aws/bin/cfn-init -s ${AWS::StackId} -r WebServerInstance --region ${AWS::Region}
                runas=root
          services:
            systemd:
              httpd:
                enabled: true
                ensureRunning: true
              cfn-hup:
                enabled: true
                ensureRunning: true
                files:
                  - /etc/cfn/cfn-hup.conf
                  - /etc/cfn/hooks.d/cfn-auto-reloader.conf
    CreationPolicy:
      ResourceSignal:
        Timeout: PT5M

  WebServerSecurityGroup:
    Type: AWS::EC2::SecurityGroup
    Properties:
      GroupDescription: Enable HTTP access via port 80
      SecurityGroupIngress:
        - IpProtocol: tcp
          FromPort: 80
          ToPort: 80
          CidrIp: 0.0.0.0/0

Outputs:
  WebsiteURL:
    Value: !Sub 'http://${WebServerInstance.PublicDnsName}'
    Description: URL of the web application

Depois que o status da pilha for CREATE_COMPLETE, a guia Saída exibirá o URL de seu site. Se você clicar no valor da saída WebsiteURL, verá sua nova aplicação PHP funcionando.

Etapa 2: atualizar a aplicação

Agora que implantamos a pilha, vamos atualizar o aplicativo. Vamos fazer uma alteração simples no texto impresso pela aplicação. Para fazer isso, vamos adicionar um comando echo ao arquivo index.php como mostrado neste trecho de modelo:

files:
  /var/www/html/index.php:
    content: |
      <?php
      echo "<h1>Hello World!</h1>";
      echo "<p>This is an updated version of our application.</p>";
      ?>
    mode: '000644'
    owner: apache
    group: apache

Use um editor de texto para editar manualmente o arquivo de modelo que você salvou localmente.

Agora, atualize a pilha.

Quando a pilha estiver no estado UPDATE_COMPLETE, será possível escolher o valor da saída WebsiteURL novamente para verificar se as alterações da aplicação tiveram efeito. Por padrão, o daemon cfn-hup é executado a cada dois minutos, portanto, pode levar até dois minutos para que a aplicação seja alterada após a atualização da pilha.

Para ver o conjunto de recursos que foram atualizados, vá para o console do CloudFormation. Na guia Eventos, examine os eventos da pilha. Neste caso específico, os metadados de WebServerInstance da instância do Amazon EC2 foram atualizados, o que fez o CloudFormation reavaliar também os outros recursos (WebServerSecurityGroup) para garantir que não havia outras alterações. Nenhum outro recurso da pilha foi modificado. O CloudFormation só atualiza os recursos da pilha que são afetados por alterações feitas na pilha. Tais alterações podem ser diretas, como alterações de propriedades ou metadados, ou podem ser devido a dependências ou fluxos de dados por meio de Ref, GetAtt ou outras funções intrínsecas do modelo. Para obter mais informações, consulte Referência de funções intrínsecas.

Essa atualização simples ilustra o processo. No entanto, você pode fazer alterações muito mais complexas nos arquivos e pacotes implantados nas instâncias do Amazon EC2. Por exemplo, você pode decidir que precisa adicionar o MySQL à instância, junto com suporte PHP para MySQL. Para fazer isso, basta adicionar outros pacotes e arquivos juntamente com todos os serviços adicionais à configuração e, em seguida, atualizar a pilha para implantar as alterações.

packages:
  yum:
    httpd: []
    php: []
    mysql: []
    php-mysql: []
    mysql-server: []
    mysql-libs: []

  ...

services:
  systemd:
    httpd:
      enabled: true
      ensureRunning: true
    cfn-hup:
      enabled: true
      ensureRunning: true
      files:
        - /etc/cfn/cfn-hup.conf
        - /etc/cfn/hooks.d/cfn-auto-reloader.conf
    mysqld:
      enabled: true
      ensureRunning: true

Você pode atualizar os metadados do CloudFormation a fim de atualizar para novas versões dos pacotes usados pela aplicação. Nos exemplos anteriores, a propriedade de versão de cada pacote está vazia, indicando que o cfn-init deve instalar a versão mais recente do pacote.

packages:
  yum:
    httpd: []
    php: []

Opcionalmente, você pode especificar uma string de versão para um pacote. Se você alterar a string de versão em chamadas de pilha de atualização subsequentes, a nova versão do pacote será implantada. Veja um exemplo de como usar os números de versão para pacotes do RubyGems. Qualquer pacote compatível com o versionamento pode ter versões específicas.

packages:
  rubygems:
    mysql: []
    rubygems-update:
      - "1.6.2"
    rake:
      - "0.8.7"
    rails:
      - "2.3.11"

Etapa 3: adicionar o acesso por SSH com um par de chaves

Também é possível atualizar um recurso no modelo para adicionar propriedades que não foram originalmente especificadas no modelo. Para ilustrar, vamos adicionar um par de chaves do Amazon EC2 a uma instância existente do EC2 e, em seguida, abrir a porta 22 no grupo de segurança do Amazon EC2 para que você possa usar o Secure Shell (SSH) para acessar a instância.

Etapa 4: atualizar o tipo de instância

Agora, vamos demonstrar como atualizar a infraestrutura subjacente alterando o tipo de instância.

A pilha criada até o momento usa uma instância t3.micro do Amazon EC2. Vamos supor que o site recém-criado esteja recebendo cada vez mais tráfego do que uma instância t3.micro pode processar, e agora você deseja mudar para um tipo de instância m5.large do Amazon EC2. Se a arquitetura do tipo de instância for alterada, a instância será criada com uma AMI diferente. No entanto, tanto a t3.micro quanto a m5.large usam as mesmas arquiteturas de CPU e executam AMIs do Amazon Linux 2 (x86_64). Para obter mais informações, consulte Compatibilidade para alterar o tipo de instância no Guia do usuário do Amazon EC2.

Vamos usar o modelo que modificamos na etapa anterior para alterar o tipo de instância. Como InstanceType era um parâmetro de entrada para o modelo, não é necessário modificá-lo. É possível alterar o valor do parâmetro na página Especificar detalhes da pilha.

Você pode alterar dinamicamente o tipo de instância de uma instância do Amazon EC2 baseada no EBS iniciando e parando a instância. O CloudFormation tenta otimizar a alteração atualizando o tipo de instância e reiniciando a instância, de modo que o ID de instância não seja alterado. Quando a instância é reiniciada, no entanto, o endereço IP público da instância é alterado. Para garantir que o endereço IP elástico esteja vinculado corretamente depois da alteração, o CloudFormation também o atualiza. Você pode ver as alterações no console do CloudFormation na guia Eventos.

Para verificar o tipo de instância a partir do Console de gerenciamento da AWS, abra o console do Amazon EC2 e localize sua instância.

Etapa 5: atualizar a AMI

Agora, vamos atualizar nossa pilha para usar o Amazon Linux 2023, que é a próxima geração do Amazon Linux.

A atualização da AMI é uma grande mudança que exige a substituição da instância. Não é possível simplesmente iniciar e interromper a instância para modificar a AMI. O CloudFormation considera isso uma alteração em uma propriedade imutável do recurso. Para alterar uma propriedade imutável, o CloudFormation precisa iniciar um recurso substituto, neste caso, uma nova instância do Amazon EC2 executando a nova AMI.

Vamos conferir como podemos atualizar nosso modelo de pilha para usar o Amazon Linux 2023. As principais mudanças incluem a atualização do parâmetro da AMI e a mudança do yum para o gerenciador de pacotes dnf.

AWSTemplateFormatVersion: 2010-09-09

Parameters:
  LatestAmiId:
    Description: The latest Amazon Linux 2023 AMI from the Parameter Store
    Type: AWS::SSM::Parameter::Value<AWS::EC2::Image::Id>
    Default: '/aws/service/ami-amazon-linux-latest/al2023-ami-kernel-6.1-x86_64'

  InstanceType:
    Description: WebServer EC2 instance type
    Type: String
    Default: t3.micro
    AllowedValues:
      - t3.nano
      - t3.micro
      - t3.small
      - t3.medium
      - t3a.nano
      - t3a.micro
      - t3a.small
      - t3a.medium
      - m5.large
      - m5.xlarge
      - m5.2xlarge
      - m5a.large
      - m5a.xlarge
      - m5a.2xlarge
      - c5.large
      - c5.xlarge
      - c5.2xlarge
      - r5.large
      - r5.xlarge
      - r5.2xlarge
      - r5a.large
      - r5a.xlarge
      - r5a.2xlarge
    ConstraintDescription: must be a valid EC2 instance type.

  KeyName:
    Description: Name of an existing EC2 KeyPair to enable SSH access to the instance
    Type: AWS::EC2::KeyPair::KeyName
    ConstraintDescription: must be the name of an existing EC2 KeyPair.

  SSHLocation:
    Description: The IP address that can be used to SSH to the EC2 instances in CIDR format (e.g. 203.0.113.1/32)
    Type: String
    MinLength: 9
    MaxLength: 18
    Default: 0.0.0.0/0
    AllowedPattern: '^(\d{1,3}\.){3}\d{1,3}\/\d{1,2}$'
    ConstraintDescription: must be a valid IP CIDR range of the form x.x.x.x/x.
    
Resources:
  WebServerInstance:
    Type: AWS::EC2::Instance
    Properties:
      ImageId: !Ref LatestAmiId
      InstanceType: !Ref InstanceType
      KeyName: !Ref KeyName
      SecurityGroupIds:
        - !Ref WebServerSecurityGroup
      UserData:
        Fn::Base64: !Sub |
          #!/bin/bash -xe
          # Get the latest CloudFormation package
          dnf update -y aws-cfn-bootstrap
          # Run cfn-init
          /opt/aws/bin/cfn-init -v --stack ${AWS::StackName} --resource WebServerInstance --region ${AWS::Region} || error_exit 'Failed to run cfn-init'        
          # Start up the cfn-hup daemon to listen for changes to the EC2 instance metadata
          /opt/aws/bin/cfn-hup || error_exit 'Failed to start cfn-hup'
          # Signal success or failure
          /opt/aws/bin/cfn-signal -e $? --stack ${AWS::StackName} --resource WebServerInstance --region ${AWS::Region}
    Metadata:
      AWS::CloudFormation::Init:
        config:
          packages:
            dnf:
              httpd: []
              php: []
          files:
            /var/www/html/index.php:
              content: |
                <?php
                echo "<h1>Hello World!</h1>";
                echo "<p>This is an updated version of our application.</p>";
                echo "<p>Running on Amazon Linux 2023!</p>";
                ?>
              mode: '000644'
              owner: apache
              group: apache
            /etc/cfn/cfn-hup.conf:
              content: !Sub |
                [main]
                stack=${AWS::StackId}
                region=${AWS::Region}
                # The interval used to check for changes to the resource metadata in minutes. Default is 15
                interval=2
              mode: '000400'
              owner: root
              group: root
            /etc/cfn/hooks.d/cfn-auto-reloader.conf:
              content: !Sub |
                [cfn-auto-reloader-hook]
                triggers=post.update
                path=Resources.WebServerInstance.Metadata.AWS::CloudFormation::Init
                action=/opt/aws/bin/cfn-init -s ${AWS::StackId} -r WebServerInstance --region ${AWS::Region}
                runas=root
          services:
            systemd:
              httpd:
                enabled: true
                ensureRunning: true
              cfn-hup:
                enabled: true
                ensureRunning: true
                files:
                  - /etc/cfn/cfn-hup.conf
                  - /etc/cfn/hooks.d/cfn-auto-reloader.conf
    CreationPolicy:
      ResourceSignal:
        Timeout: PT5M

  WebServerSecurityGroup:
    Type: AWS::EC2::SecurityGroup
    Properties:
      GroupDescription: Enable HTTP access via port 80 and SSH access via port 22
      SecurityGroupIngress:
        - IpProtocol: tcp
          FromPort: 80
          ToPort: 80
          CidrIp: 0.0.0.0/0
        - IpProtocol: tcp
          FromPort: 22
          ToPort: 22
          CidrIp: !Ref SSHLocation

Outputs:
  WebsiteURL:
    Value: !Sub 'http://${WebServerInstance.PublicDnsName}'
    Description: URL of the web application

Atualize a pilha usando as mesmas etapas explicadas em Etapa 2: atualizar a aplicação.

Depois que a nova instância está em execução, o CloudFormation atualiza os outros recursos da pilha para que apontem para o novo recurso. Quando todos os novos recursos são criados, o recurso antigo é excluído. Esse processo é conhecido como UPDATE_CLEANUP. Desta vez, você notará que o ID da instância e o URL do aplicativo da instância na pilha foram alterados como resultado da atualização. Os eventos na tabela Evento contêm uma descrição “A atualização solicitada tem uma alteração em uma propriedade imutável e, portanto, está criando um novo recurso físico” para indicar que um recurso foi substituído.

Como alternativa: se você tem um código de aplicação escrito na AMI que deseja atualizar, pode usar o mesmo mecanismo de atualização de pilha para atualizar a AMI para que ela carregue a nova aplicação.

Ao atualizar a pilha, o CloudFormation detecta que o ID da AMI foi alterado e, em seguida, aciona uma atualização da pilha da mesma maneira que iniciamos a atualização demonstrada acima.

Considerações sobre disponibilidade e impacto

Diferentes propriedades têm diferentes impactos nos recursos na pilha. Você pode usar o CloudFormation para atualizar qualquer propriedade. No entanto, antes de fazer qualquer alteração, você deve considerar estas perguntas:

Recursos relacionados

Para obter mais informações sobre como usar o CloudFormation para iniciar aplicações e sobre a integração com outros serviços de configuração e implantação, como o Puppet e o Opscode Chef, consulte os seguintes whitepapers: