Troubleshooting 7 common errors in AWS CloudFormation

Use comments to provide context

Developers build CloudFormation templates in JSON or YAML format. These templates define the group of cloud resources to launch a CloudFormation stack. Comments are useful to add context or additional information relevant to a template and the resources being launched.

YAML tends to be a less verbose format than JSON for CloudFormation templates. YAML also supports comments in the template, while JSON does not. Without the context from comments, developers risk introducing errors through configuration changes and updates.

Avoid configuration errors

Developers and engineers need to build CloudFormation stacks that can launch resources in multiple environments. The configuration for development, for example, differs from the ones for QA, staging and production. Therefore, the template must be able to launch stacks with different configurations based on their deployment phase.

Use features such as parameters and mappings to support different configuration values for resources. For example, a parameter or a mapping feature can configure an EC2 instance size for the development stage versus for production. The instance size in the build changes in accordance with the stack being launched without requiring an updated or separate template.

Use the CloudFormation console

AWS renders a stack status when a CloudFormation stack launches or updates, either through the SDK, AWS Command Line Interface or the console. CREATE_COMPLETE, UPDATE_COMPLETE and UPDATE_COMPLETE_CLEANUP_IN_PROGRESS are typical stack statuses that indicate a successful operation.

When something goes wrong during the stack creation or update, CloudFormation returns statuses such as CREATE_FAILED, UPDATE_FAILED and UPDATE_ROLLBACK_COMPLETE. The CloudFormation console can shed some insights into these statuses.

When troubleshooting errors, the easiest way to view details is via the CloudFormation console, not working with the CLI or SDK. Click on the stack to troubleshoot and use the Events tab. This screen displays detailed information on each resource's status and the reason behind any errors.

Look for syntax errors

Syntax errors are common. After submitting the CloudFormation template, CloudFormation may display a message in the console detailing an error and its location in the template. If there is a JSON or YAML format issue, the console doesn't allow the template to be submitted. In this example, it shows the following message:

"Template format error: YAML not well-formed. (line <number>, column <number>".

For this type of generic error, there are online tools that are useful to identify JSON or YAML format issues, including the following:

• JSON Lint.
• YAML Lint.
• JSON Formatter.
• YAML Validator.

For AWS-specific errors, AWS documentation provides details on the expected CloudFormation syntax for each type of supported resource.

Check permissions

CloudFormation executes administrator-level actions, such as creating, updating or deleting AWS resources. It can manage Amazon EC2/Relational Database Service instances, S3 buckets, Virtual Private Clouds, security groups and more. Therefore, anyone who executes CloudFormation tasks must have elevated AWS Identity and Access Management (IAM) permissions that allow these actions. An IAM role or IAM user without proper permissions encounters errors that prevent build completion or stack updates within CloudFormation.

It is also important to control IAM permissions and set up IAM entities to execute only actions relevant to the AWS developer's or admin's role. AWS offers the option to pass an IAM role to CloudFormation during the stack creation or update process. Either way, configuring the required IAM permissions in an IAM role correctly enables CloudFormation to perform the required actions to manage the stack's AWS resources.

Ensure all dependencies are available

Building a stack of AWS components comes with several dependencies based on the type of resource and specific configuration. For example, if an EC2 instance is configured to deploy in a specific subnet, the subnet must be available before the instance can launch. The same is true for other parameters, such as security group IDs and network interface configurations. If these dependencies are not met, CloudFormation emits errors.

Use the DependsOn attribute to ensure that no resources launch until all dependencies are met. This parameter supports dependencies either in the current CloudFormation stack or in other stacks.

Avoid update issues

Another common error when updating CloudFormation stacks is denoted by the UPDATE_ROLLBACK_FAILED status. This happens when a stack update is not successful but CloudFormation cannot roll back all the relevant resources to their previous state. In this case, the AWS developer can continue with the update rollback but must indicate whether to skip the affected resources or try again to reset them. Skipping the affected resources could require manual updates after the stack update finishes, which creates opportunity for human error and missed changes.

Developers can trigger unwanted updates to a stack. This potentially disruptive error could cause data loss, resource deletion or replacement, and other events that could harm an application. To avoid this type of error, build a change set to preview updates introduced to a CloudFormation template, instead of applying the stack update directly. Developers can view affected resources before the update; determine the type of actions to apply, e.g., add, modify and remove; and approve or reject the update.

Ernesto Marquez is owner and project director at Concurrency Labs, where he helps startups launch and grow their applications on AWS. He particularly enjoys building serverless architectures, automating everything and helping customers cut their AWS costs.