How do I troubleshoot issues when I include metadata on an EC2 instance in CloudFormation?

Resolution

Prerequisites: Set the Rollback on failure option for your CloudFormation stack to No.

If you set Rollback on failure to No and still can't include metadata on the EC2 instance, then take the following actions.

Note: The following resolution steps are for CloudFormation stacks that you created with a Linux instance.

Verify that the cfn-init helper script is installed

To confirm that you installed cfn-init on the instance that's configured to send signals to CloudFormation resources, complete the following steps:

1. Use SSH to connect to the instance.
2. Verify that cfn-init or the aws-cfn-bootstrap package is installed in your directory.
   To check for cfn-init, run the following command:

   sudo find / -name cfn-init/opt/aws/bin/cfn-init
   /opt/aws/apitools/cfn-init
   /opt/aws/apitools/cfn-init-1.4-34.24.amzn1/bin/cfn-init
   /var/lib/cfn-init

   To check for the aws-cfn-bootstrap package, run the following command:

   sudo rpm -q aws-cfn-bootstrapaws-cfn-bootstrap-1.4-34.24.amzn1.noarch

   Note: The preceding command works only on distributions that use the RPM Package Manager.

CloudFormation helper scripts are installed on the Amazon Linux Amazon Machine Image (AMI) by default.

Verify that the instance is connected to the internet

If the instance is in an Amazon Virtual Private Cloud (Amazon VPC), then the instance can connect to the internet through the following methods:

• A NAT device in a private subnet
• An internet gateway in a public subnet

To test the instance's internet connection, open a public webpage such as the AWS home page. Then, run a curl command on the instance. Example:

curl -I https://aws.amazon.com

If the instance is connected to the internet, then the command returns an HTTP 200 status code.

If you use an interface VPC endpoint, then the endpoint must be in the same AWS Region as the instance. Also, the security group that's attached to the interface endpoint must allow incoming connections on port 443 from the private subnet of the Amazon VPC.

Search for errors in the cloud-init or cfn-init logs

To search for syntax errors or incorrect values in the cloud-init logs or cfn-init logs, complete the following steps:

1. Use SSH to connect to your instance.
2. To find detailed error messages, search for the error or failure keywords in the following logs:
   /var/log/cloud-init-output.log
   /var/log/cloud-init.log
   /var/log/cfn-init.log
   /var/log/cfn-init-cmd.log
   To find all instances of the words error or failure in the /var/log/cfn or /var/log/cloud-init files, run the following command:

   grep -ni 'error\|failure' $(sudo find /var/log -name cfn-init\* -or -name cloud-init\*)

   Note: The preceding command returns the file name, line number, and error message.
3. Use the detailed error message to fix errors, and then update the stack.

If cfn-init.log doesn't exist, then the CloudFormation template didn't run cfn-init.

To confirm that you configured the UserData property to run cfn-init, complete the following steps:

1. In a code editor, open the CloudFormation template for your stack.
2. Under UserData, check for errors such as syntax errors, missing spaces, misspellings, and other typos.
3. Confirm that the values for the stack, resource, and Region properties are correct.
4. For the Fn::Join intrinsic function of the UserData property, use -v to run cfn-init in verbose mode. For example outputs, see Example.

Related information

Considerations for CloudFormation VPC endpoints

AWS::CloudFormation::Init

How do I resolve the error "Failed to receive X resource signal(s) within the specified duration" in AWS CloudFormation?