gosphotodesign - Fotolia


Simplify CloudFormation templates with YAML instead of JSON

Developers can format AWS CloudFormation templates with JSON or YAML. Inexperienced dev teams should look at YAML first to deploy infrastructure as code.

One benefit of a public cloud like AWS is the ability for developers to automate tasks. AWS CloudFormation, which...

defines an application stack's resources in a declarative template, lets developers define and deploy infrastructure as code. Initially, developers needed to use JSON -- an expressive, human-readable data format that some find confusing -- to format CloudFormation templates. The difficulty attributed to using JSON was a drawback to the automation process.

JavaScript Object Notation (JSON) templates require a lot of punctuation with commas and quotation marks, along with square and curly brackets in different places. In response to customer requests, AWS now supports the use of YAML in an AWS CloudFormation template. YAML, which stands for YAML Ain't Markup Language, is a human readable open data format used by a variety of languages to exchange data, define configuration files and more. YAML generally is easier to read compared to other common structured data formats such as JSON and XML.

Comparing YAML and JSON formatted templates

Which template format to use is a matter of personal preference; teams that collaborate on templates likely want to standardize on a single format, but there is no right or wrong answer. Admins should choose the format that they're most comfortable with. However, developers who are new to both the JSON and YAML formats should compare the two to determine which would work best. Figure 1 shows a simple CloudFormation template, authored in JSON, to deploy a single Elastic Compute Cloud (EC2) instance.

AWS CloudFormation template created using JSON format.
Figure 1. Simple CloudFormation template in JSON.

The template defines a single resource, an EC2 instance called WebServer. A few of the required properties are set for the instance, which include the Amazon Machine Image (AMI), the instance type and the key name to use for remote access via secure socket shell protocol.

Figure 2 shows the same template formatted in YAML.

Using YAML to create CloudFormation template.
Figure 2. Simple CloudFormation template in YAML.

In Figure 2, the YAML-based template is more concise compared to its JSON counterpart, with nearly 100 fewer characters. This may not seem like a lot, but CloudFormation templates include several independent resources. CloudFormation templates that use the YAML format will reduce the amount of code.

Support for code comments

A big issue with building CloudFormation templates in JSON format is the lack of support for comments. Some CloudFormation templates are several thousand lines long and, in those cases, comments can be a lifesaver. YAML-based CloudFormation templates can include inline comments, as shown in Figure 3.

Include inline comments with YAML in CloudFormation.
Figure 3. Inline comments within a YAML template.

This code snippet defines a single EC2 instance in a YAML template. In this example, two comments were added. On the second line, an inline comment was added after declaring the server name of WebServer; this comment explains the intent of the item. The only requirement is to prefix comments with the hash (#) character.

Figure 3 also includes a comment that explains which AMI is used for the image ID -- ImageId property -- of the EC2 instance. Developers can use these techniques to add as many comments as needed throughout CloudFormation templates.

Make function calls with YAML

Another benefit for developers who use YAML to create CloudFormation templates is the use of abbreviated syntax to make calls to CloudFormation intrinsic functions, as shown in Figure 4.

Function calls with YAML in AWS CloudFormation template.
Figure 4. Calling the Ref function in YAML.

The template in Figure 4 has a section for input parameters. In this case, the template accepts one input parameter called KeyName, which defines the name of the EC2 key pair for the new instance. Within the properties of the WebServer resource, the CloudFormation Ref function references the KeyName parameter. This allows an operator to set the KeyName value at runtime, as opposed to hard-coding the value into the template.

When the template launches, the Ref function is called and the value input through the KeyName parameter is used in the KeyName property of the EC2 instance. A tag-based syntax is used to call the Ref function, which requires a developer to prefix the function name with an exclamation point (!). Without this shortcut, function calls are more verbose and require more code.

Next Steps

Study this infrastructure as code tools cheat sheet

Keys to use AWS CloudFormation with Jenkins

Get into a DevOps state of mind

Dig Deeper on AWS architecture and design