How do I troubleshoot helper scripts that won't bootstrap in a CloudFormation stack with Windows instances?

Short description

Reboot the Windows instance. If your helper scripts don't run after you reboot the Windows instance, then complete the steps in the Troubleshoot bootstrapping issues section.

If you receive the following error, then you might have issues with cfn-signal: "Received 0 conditions when expecting X or Failed to receive X resource signal(s) within the specified duration." To resolve this issue, complete the steps in the Troubleshoot cfn-signal issues section.

For both issues, complete the steps in the Follow best practices for Windows operating systems with CloudFormation section.

Resolution

Troubleshoot bootstrapping issues

Check the commands section of your cfn-init configuration set to verify that waitAfterCompletion is set to forever. Example:

"commands": { "0-restart": {
 "command": "powershell.exe -Command Restart-Computer",
 "waitAfterCompletion": "forever"
 }
 }

Note: The forever value directs cfn-init to exit and resume only after the reboot is complete. For more information, see Commands.

After you verify your configuration, review the following logs for errors:

• The cfn-init log: C:\cfn\log\cfn-init.log
• The Windows event logs: C:\Windows\System32\winevt\logs
  Note: Amazon Elastic Cloud Compute (Amazon EC2) EC2Launch v2 agent publishes Windows event logs.
• (For Windows instances that use the EC2Config Service) the configuration log: C:\Program Files\Amazon\Ec2ConfigService\Logs\Ec2ConfigLog.txt
• (For Windows instances that use EC2Launch v1 agent) the launch log: C:\ProgramData\Amazon\EC2-Windows\Launch\Log

Troubleshoot cfn-signal issues

Complete the following steps:

1. Verify that you configured the cfn-signal correctly.
   Important: Use -e $lastexitcode in PowerShell scripts, and -e %ERRORLEVEL% in Windows cmd.exe scripts.
   For PowerShell scripts in UserData, use the following tags:

   <powershell></powershell>

   Example PowerShell script:

   UserData:        Fn::Base64:
             Fn::Sub : |
               <powershell>
               $LASTEXITCODE=0
               echo Current date and time >> C:\Temp\test.log
               echo %DATE% %TIME% >> C:\Temp\test.log
               cfn-init.exe -s ${AWS::StackId} -r SInstance --region ${AWS::Region}
               New-Item -Path "C:\" -Name userdata -ItemType directory
               cfn-signal.exe -e $LASTEXITCODE --stack ${AWS::StackId} --resource WindowsInstance --region ${AWS::Region}
               </powershell>

   For cmd.exe scripts in UserData, use the following tags:

   <script></script>

   Example cmd.exe script:

   UserData:  Fn::Base64: !Sub |
       <script>
       cfn-init.exe -v -s ${AWS::StackId} -r WindowsInstance --configsets ascending --region ${AWS::Region}
       cfn-signal.exe -e %ERRORLEVEL% --stack ${AWS::StackId} --resource WindowsInstance --region ${AWS::Region}
       </script>

2. Increase the Timeout of the AWS::CloudFormation::WaitCondition. For an example configuration, see Example of bootstrapping a Windows stack.
   Note: Windows instances typically take longer than Linux instances to complete their initial boot process.

3. If you're using a custom Amazon Machine Image (AMI), then you must use Sysprep to create the AMI. If you don't use Sysprep, then you might receive the following error in the user data log for metadata: "Failed to get metadata: The result from http://169.254.169.254/latest/user-data was empty. Unable to execute userdata: Userdata was not provided."

Follow best practices for Windows operating systems with CloudFormation

Use the following best practices to troubleshoot your setup:

• Include $ErrorActionPreference = "Stop" at the top of your PowerShell scripts to catch exceptions.

• When you refer to a Windows path in your CloudFormation template, add a forward slash (/) at the beginning of the path. Example:

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

• For Windows stacks, base64 encode the WaitCondition handle URL. Example:

  cfn-signal.exe -e %ERRORLEVEL% ", { "Fn::Base64" : { "Ref" : "SharePointFoundationWaitHandle" }}, "\n"