How To Troubleshoot AWS CloudFormation Errors?

AWS CloudFormation (CFN) helps in automating deployments by delivering Infrastructure as a Code (IaaC). It offers several useful capabilities, like simple templates, support for a wide range of AWS services, dependency management, parallel deployments, and so on. To use CloudFormation, you create CFN templates either from scratch or from samples. You can also use tools like the CloudFormation Designer to author the CFN templates. However, similarly to coding, you will run into errors with CFN as well. In this post, we will cover the two prominent types of CFN errors and how to troubleshoot these.

Types of CloudFormation Errors

There are two types of CFN errors.

1. Syntax Errors: A CFN template is a text document in either JSON or YAML format. The syntax errors in the CFN template lead to this error. For example, a missing comma or brace in JSON, an incorrect indentation in YAML, and so on. Such a template is not even deployed as the CloudFormation Console or the CLI will fail upon detecting the error.
2. Semantic Errors: These occur at deployment time typically due to coding or an infrastructure issue. For example, an incorrectly specified resource property name, trying to create a duplicate resource, and so on.

How To Troubleshoot CloudFormation Syntax Errors?

Let’s take an example here. The following screenshot shows a CFN template snippet in JSON format.

As you can see, the curly brace for the PolicyDocument property is missing. When we try to deploy this CFN template, we will see an error like the one shown below.

Here the JSON parser has detected a missing comma or a curly brace. After you add the missing brace, the error will be resolved. Errors like these are quite common during development. Here are some tips on how to resolve or minimize the occurrence of such errors.

• Check if your text editor supports block matching capabilities, like the powerful VI editor. This can be used to find the matching brace, and if you find that it is not on the expected element you have found the problem area. Then you can keep drilling down till you find the problem. As a general practice, it is also a good idea to always specify the closing brace when opening a brace so that you do not miss it. This can really come in handy for large templates.
• You can also use a JSON validator or beautifier. There are several available online. While in most cases the validator may not reveal any more useful information than what the CFN CLI output shows, the beautifier may be a bit helpful to visually inspect the template for any anomalies.

How To Troubleshoot CloudFormation Semantic Errors?

The semantic errors can range from simple things like incorrect property names, missing resource names to infrastructure-related errors, such as duplicate infrastructure resource name. And, as we discussed earlier, these occur at the deployment time. So, it may increase your end-to-end resolution time. Let’s take the example wherein we are trying to deploy an S3 bucket using a CFN template but a bucket with the specified name already exists. The following screenshot shows the CFN CLI output.

As you can see, the CLI execution failed. However, unlike the syntax error, the details are not available in this output. So, to troubleshoot further, you can either go to the CloudFormation Console or run the command shown in the above output.

aws cloudformation describe-stack-events –stack-name c9apps-demo-bucket1

This will show the stack events in reverse chronological order (most recent event first). Scroll through the list till you find the error cause as shown below.

It shows that a bucket named c9apps-demo-bucket (which was the bucket name we specified when deploying the template) already exists in another stack. This approach can be particularly useful for DevOps pipelines to retrieve the error information.

The other option is to go to the CloudFormation Console and look into the stack events for the error cause as shown below.

As we can see, the console shows the same information.

While semantic errors is a broader category and it is difficult to have a silver bullet solution for every scenario, here are some general tips.

• Use the AWS Resource and Property Types Reference document to check the resources types and properties.
• Use unique resource identifier names in the CFN templates. In general, giving names based on purpose is a good idea. For example, instead of calling it EC2Instance1, a better name would be WebTierInstance1.
• CloudFormation offers several Intrinsic Functions for common computing needs. Leverage from these to make more meaningful and unique resource names. For example, the Fn::Join Intrinsic Function can be used to combine a list of strings.
• Leverage from the lifecycle for choosing the resource names. For example, resources that are global in nature (such as IAM role) may not have the stack name as part of their names. Whereas, resources that are meant for a specific stack only can use the stack name to make their names unique.

Troubleshooting CFN errors takes some practice. Also, at times the error messages may not be easy to understand. So, it is a good idea to familiarize yourself with these techniques so that you are better prepared when the issues occur.

Be a smart troubleshooter!
– Nitin

If you liked this post, you will find my AWS CloudFormation Deep Dive course helpful that focuses on many such best practices, techniques and hands-on examples to use CloudFormation in real-world deployments.

 

 

---

Also published on Medium.