# Fazer o bootstrap de pilhas do CloudFormation baseadas em Windows
<a name="cfn-windows-stacks-bootstrapping"></a>

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

**Topics**
+ [Dados do usuário em instâncias do EC2](#cfn-windows-bootstrapping-user-data)
+ [CloudFormation scripts auxiliares](#cfn-windows-bootstrapping-helper-scripts)
+ [Exemplo de bootstrap de uma pilha do Windows](#cfn-windows-bootstrapping-example)
+ [Escapar barras invertidas nos caminhos dos arquivos do Windows](#cfn-windows-stacks-escape-backslashes)
+ [Gerenciar serviços da Windows](#cfn-windows-stacks-manage-windows-services)
+ [Como solucionar problemas de criação de pilhas](#cfn-windows-stacks-troubleshooting)

## Dados do usuário em instâncias do EC2
<a name="cfn-windows-bootstrapping-user-data"></a>

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](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/ec2launch-v2.html) 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](https://docs.aws.amazon.com/ec2/latest/windows-ami-reference/windows-amis.html).

## CloudFormation scripts auxiliares
<a name="cfn-windows-bootstrapping-helper-scripts"></a>

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](https://docs.aws.amazon.com/AWSCloudFormation/latest/TemplateReference/cfn-helper-scripts-reference.html) no *Guia de referência de modelos do CloudFormation*.

## Exemplo de bootstrap de uma pilha do Windows
<a name="cfn-windows-bootstrapping-example"></a>

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](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/connecting_to_windows_instance.html) no *Manual do usuário do Amazon EC2*.

## Escapar barras invertidas nos caminhos dos arquivos do Windows
<a name="cfn-windows-stacks-escape-backslashes"></a>

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
<a name="cfn-windows-stacks-manage-windows-services"></a>

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
<a name="cfn-windows-stacks-troubleshooting"></a>

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](stack-failure-options.md). 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*:
+ [EC2Launch Estrutura de diretórios do](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/ec2config-service.html#UsingConfigXML_WinAMI)
+ [EC2Launch Estrutura de diretório do v](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/ec2launch-v2.html#ec2launch-v2-directory)

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?](https://repost.aws/knowledge-center/cloudformation-helper-scripts-windows).