How do I use the AWSSupport-TroubleshootCfnCustomResource runbook to diagnose why my CloudFormation stack failed?

Short description

The AWSSupport-TroubleshootCFNCustomResource runbook diagnoses a CloudFormation stack that fails when you create, updated, or delete a custom resource. The runbook checks the service token used for the custom resource and the error message that was returned. After analyzing the details of the custom resource, the runbook output provides information on the stack behavior and how to troubleshoot the custom resource.

For AWS Lambda custom resources, the runbook checks if Lambda reaches the Amazon Simple Storage Service (Amazon S3) to send a response back to CloudFormation. The response back to CloudFormation is for checking Lambda network configuration and security groups.

Resolution

Before you begin, make sure your AWS Identity and Access Management (IAM) user or role has the required permissions to allow the following IAM actions:

• CloudFormation: DescribeStacks
• CloudFormation: DescribeStackEvents
• CloudFormation: ListStackResources
• Amazon Elastic Compute Cloud (Amazon EC2): DescribeRouteTables
• Amazon EC2: DescribeNatGateways
• Amazon EC2: DescribeSecurityGroups
• Amazon EC2: DescribeVpcs
• Amazon EC2: DescribeVpcEndpoints
• Amazon EC2: DescribeSubnets
• Amazon EC2: FilterLogEvents

Run the AWSSupport-TroubleshootCFNCustomResource runbook

1.    Log in to the AWS Systems Manager console.

2.    In the navigation pane, choose Documents.

3.    In the search bar, type the following: AWSSupport-TroubleshootCfnCustomResource.

4.    Select the AWSSupport-TroubleshootCfnCustomResource document.

5.    Select Execute automation.

6.    For the input parameters, enter the following:

• AutomationAssumeRole (optional): Enter the Amazon Resource Name (ARN) of the IAM role that allows Systems Manager Automation to perform the actions on your behalf. If no role is specified, Systems Manager Automation uses the permissions of the user that starts the runbook.
• StackName (Required): Enter the name of the CloudFormation stack where the custom resource failed.

7.    Select Execute. The automation is initiated.

8.    When the automation is complete, review the Outputs section for detailed results:

• validateCloudFormationStack - Verifies that the CloudFormation stack exists in the same AWS account and AWS Region.
• checkCustomResource - Analyzes the CloudFormation stack, checks the failed custom resource, and provides information on how to troubleshoot the failed custom resource.

Related information

Running a simple automation (console)

Setting up Automation

AWSSupport-TroubleshootCFNCustomResource

Systems Manager Automation runbook reference