Fazer o bootstrap de pilhas do CloudFormation baseadas em Windows

Este tópico descreve como fazer bootstrap de uma pilha do Windows e solucionar problemas na criação da pilha.

Dados do usuário em instâncias do EC2

Os dados do usuário são um recurso do Amazon EC2 que permite que você passe scripts ou informações de configuração para uma instância do EC2 quando ela é inicializada.

Para instâncias do EC2 para Windows:

• Você pode usar scripts em lote (usando tags <script>) ou scripts PowerShell (usando tags <powershell>).

• A execução de scripts é realizada por EC2Launch.

Importante

Se você estiver criando sua própria AMI do Windows para uso com o CloudFormation, verifique se o EC2Launch v2 está configurado corretamente. O EC2Launch v2 é necessário para que as ferramentas de bootstrap do CloudFormation inicializem e configurem adequadamente as instâncias Windows durante a criação da pilha. Para obter mais informações, consulte Usar o agente do EC2Launch v2 para realizar tarefas durante a inicialização da instância do EC2 do Windows no Guia do usuário do Amazon EC2.

Para obter informações sobre as AMIs da AWS para Windows disponíveis, consulte AWS Windows AMI Reference.

CloudFormation scripts auxiliares

Os scripts auxiliares são utilitários para configurar instâncias durante o processo de bootstrap. Usados com os dados do usuário do Amazon EC2, eles oferecem opções de configuração avançadas.

O CloudFormation fornece os seguintes scripts auxiliares do Python que podem ser usados para instalar software e iniciar serviços em uma instância do Amazon EC2 criada por você como parte da pilha:

• cfn-init: usado para recuperar e interpretar os metadados de recursos, instalar pacotes, criar arquivos e iniciar serviços.

• cfn-signal: usado para sinalizar com uma CreationPolicy para que você possa sincronizar outros recursos da pilha quando o recurso ou a aplicação exigidos estiverem prontos.

• cfn-get-metadata: usado para recuperar metadados de um recurso ou caminho para uma chave específica.

• cfn-hup: usado para verificar se há atualizações para os metadados e executar hooks personalizados quando alterações são detectadas.

Você chama os scripts diretamente do seu modelo. Os scripts funcionam em conjunto com os metadados de recurso que estão definidos no mesmo modelo. Os scripts são executados na instância do Amazon EC2 durante o processo de criação da pilha.

Para obter mais informações, consulte Referência de scripts auxiliares do CloudFormation no Guia de referência de modelos do AWS CloudFormation.

Exemplo de bootstrap de uma pilha do Windows

Vamos examinar exemplos de trechos de um modelo do Windows Server que executa as seguintes ações:

• Lança uma instância do EC2 denominada TestInstance em uma AMI do Windows Server 2022.

• Cria um arquivo de teste simples para verificar se cfn-init está funcionando.

• Configura cfn-hup para gerenciamento contínuo das configurações.

• Usa uma CreationPolicy para garantir que a instância sinalize conclusões bem-sucedidas.

O script auxiliar cfn-init é usado para realizar cada uma dessas ações com base em informações do recurso AWS::CloudFormation::Init no modelo.

A seção AWS::CloudFormation::Init é denominada TestInstance e começa com a declaração a seguir.

TestInstance:
  Type: AWS::EC2::Instance
  Metadata:
    AWS::CloudFormation::Init:
      configSets:
        default:
          - create_files
          - start_services

A seguir, a seção files de AWS::CloudFormation::Init é declarada.

      create_files:
        files:
          c:\cfn\test.txt:
            content: !Sub |
              Hello from ${AWS::StackName}
          c:\cfn\cfn-hup.conf:
            content: !Sub |
              [main]
              stack=${AWS::StackName}
              region=${AWS::Region}
              interval=2
          c:\cfn\hooks.d\cfn-auto-reloader.conf:
            content: !Sub |
              [cfn-auto-reloader-hook]
              triggers=post.update
              path=Resources.TestInstance.Metadata.AWS::CloudFormation::Init
              action=cfn-init.exe -v -s ${AWS::StackName} -r TestInstance -c default --region ${AWS::Region}

Três arquivos são criados aqui e colocados no diretório C:\cfn da instância do servidor:

• test.txt, um arquivo de teste simples que verifica se cfn-init está funcionando corretamente e pode criar arquivos com conteúdo dinâmico.

• cfn-hup.conf, o arquivo de configuração de cfn-hup com um intervalo de verificação de 2 minutos.

• cfn-auto-reloader.conf, o arquivo de configuração do hook usado por cfn-hup para iniciar uma atualização (chamando cfn-init) quando os metadados em AWS::CloudFormation::Init são alteados.

A próxima seção start_services configura serviços do Windows.

      start_services:
        services:
          windows:
            cfn-hup:
              enabled: true
              ensureRunning: true
              files:
                - c:\cfn\cfn-hup.conf
                - c:\cfn\hooks.d\cfn-auto-reloader.conf

Esta seção garante que o serviço cfn-hup seja iniciado e que será reiniciado automaticamente se os arquivos de configuração forem modificados. O serviço monitora alterações nos metadados do CloudFormation e executa cfn-init novamente quando atualizações são detectadas.

A próxima seção é Properties.

TestInstance:
  Type: AWS::EC2::Instance
  CreationPolicy:
    ResourceSignal:
      Timeout: PT20M
  Metadata:
    AWS::CloudFormation::Init:
      # ... metadata configuration ...
  Properties:
    InstanceType: t2.large
    ImageId: '{{resolve:ssm:/aws/service/ami-windows-latest/Windows_Server-2022-English-Full-Base}}'
    SecurityGroupIds:
      - !Ref InstanceSecurityGroup
    KeyName: !Ref KeyPairName
    UserData:
      Fn::Base64: !Sub |
        <powershell>
        cfn-init.exe -v -s ${AWS::StackName} -r TestInstance -c default --region ${AWS::Region}
        cfn-signal.exe -e $lastexitcode --stack ${AWS::StackName} --resource TestInstance --region ${AWS::Region}
        </powershell>

Nesta seção, a propriedade UserData contém um script PowerShell que será executado por EC2Launch, entre tags <powershell>. O script executa cfn-init com o configSet default e depois usa cfn-signal para retornar o código de saída ao CloudFormation. A CreationPolicy é usada para garantir que a instância esteja configurada corretamente antes que a criação da pilha seja considerada concluída.

A propriedade ImageId usa um parâmetro público do Systems Manager Parameter Store para recuperar automaticamente o ID da AMI mais recente do Windows Server 2022 . Essa abordagem elimina a necessidade de mapeamentos de AMIs específicas da região e garante que você sempre obtenha a AMI mais recente. O uso de parâmetros do Systems Manager para IDs de AMIs é uma prática recomendada para manter as referências de AMIs atualizadas. Se você planejar se conectar à instância, certifique-se de a propriedade SecurityGroupIds referencie um grupo de segurança que permita acesso por RDP.

A CreationPolicy é declarada como parte das propriedades do recurso e especifica um tempo limite. O comando cfn-signal nos dados do usuário sinaliza quando a configuração da instância foi concluída:

TestInstance:
  Type: AWS::EC2::Instance
  CreationPolicy:
    ResourceSignal:
      Timeout: PT20M
  Properties:
    # ... other properties ...

Como o processo de inicialização é mínimo e apenas cria arquivos e inicia serviços, a CreationPolicy aguarda 20 minutos (PT20M) antes de atingir o tempo limite. O tempo limite é especificado usando o formato de duração ISO 8601. Observe que as instâncias do Windows geralmente demoram mais para serem iniciadas que as instâncias do Linux, por isso, teste cuidadosamente para determinar os melhores valores de tempo limite para as suas necessidades.

Se tudo correr bem, a CreationPolicy será concluída com êxito e você poderá acessar a instância do Windows Server usando seu endereço IP público. Depois que a criação da pilha é concluída, o ID e endereço IP da instância são exibidos na guia Saídas do console do CloudFormation.

Outputs:
  InstanceId:
    Value: !Ref TestInstance
    Description: Instance ID of the Windows Server
  PublicIP:
    Value: !GetAtt TestInstance.PublicIp
    Description: Public IP address of the Windows Server

Você também pode verificar manualmente se a inicialização funcionou corretamente conectando-se à instância por RDP e verificando se o arquivo C:\cfn\test.txt existe e contém o conteúdo esperado. Para obter informações sobre conexão a instâncias do Windows, consulte Conexão com a instância do Windows usando um cliente RDP no Manual do usuário do Amazon EC2.

Escapar barras invertidas nos caminhos dos arquivos do Windows

Ao referenciar os caminhos do Windows nos modelos do CloudFormation, lembre-se sempre de escapar adequadamente as barras invertidas (\) de acordo com o formato do modelo sendo usado.

• Para modelos JSON, você deve usar barras invertidas duplas nos caminhos dos arquivos do Windows porque o JSON trata a barra invertida como um caractere de escape. A primeira barra invertida escapa da segunda, resultando na interpretação de uma única barra invertida literal.

  "commands" : {
    "1-extract" : {
      "command" : "C:\\SharePoint\\SharePointFoundation2010.exe /extract:C:\\SharePoint\\SPF2010 /quiet /log:C:\\SharePoint\\SharePointFoundation2010-extract.log"
    }
  }

• Para modelos YAML, barras invertidas simples normalmente são suficientes.

  commands:
    1-extract:
      command: C:\SharePoint\SharePointFoundation2010.exe /extract:C:\SharePoint\SPF2010 /quiet /log:C:\SharePoint\SharePointFoundation2010-extract.log

Gerenciar serviços da Windows

Os serviços do Windows são gerenciados da mesma forma que os serviços do Linux, exceto pelo uso de uma chave windows em vez de sysvinit. O exemplo a seguir iniciará o serviço cfn-hup, definirá o serviço como automático e o reiniciará se cfn-init modificar os arquivos de configuração c:\cfn\cfn-hup.conf ou c:\cfn\hooks.d\cfn-auto-reloader.conf.

        services:
          windows:
            cfn-hup:
              enabled: true
              ensureRunning: true
              files:
                - c:\cfn\cfn-hup.conf
                - c:\cfn\hooks.d\cfn-auto-reloader.conf

É possível gerenciar outros serviços do Windows da mesma maneira, usando o nome, não o nome de exibição, para referenciar o serviço.

Como solucionar problemas de criação de pilhas

Em caso de falha na pilha durante a criação, o comportamento padrão é de reversão em caso de falha. Embora normalmente seja um bom padrão, pois evita cobranças desnecessários, isso dificulta a depuração por causa da falha na criação da pilha.

Para desativar esse comportamento ao criar ou atualizar sua pilha com o console do CloudFormation, escolha a opção Preservar recursos provisionados com sucesso em Opções de falha de pilha. Para obter mais informações, consulte Escolha como lidar com falhas ao provisionar recursos. Isso permite a você fazer login na instância e visualizar os arquivos de log para identificar os problemas encontrados na execução dos scripts de startup.

Os logs importantes a serem observados são:

• O log de configuração do EC2 em %ProgramData%\Amazon\EC2Launch\log\agent.log

• O log de cfn-init em C:\cfn\log\cfn-init.log (verifique os códigos de saída e as mensagens de erro para pontos de falha específicos)

Para obter mais logs, consulte os seguintes tópicos no Guia do usuário do Amazon EC2:

• Estrutura de diretórios do EC2Launch

• Estrutura de diretório do EC2Launch v2

Para obter mais informações sobre como solucionar problemas de inicialização, consulte How do I troubleshoot helper scripts that won't bootstrap in a CloudFormation stack with Windows instances?.