Why I use YAML for AWS CloudFormation

I’m a JSON masochist no more!

AWS supports YAML for CloudFormation templates, and I’ve regained my sanity…at least some of it.

CloudFormation is AWS’s service for defining infrastructure as code, allowing you to provision AWS resources on demand. I use CloudFormation daily when automating my clients’ environments in AWS as part of continuous integration and delivery (CI/CD) pipelines.

Since the release of CloudFormation, I’ve been using JSON format for my templates, but recently switched to YAML.

In this article, I’ll discuss why I switched from JSON to YAML for my CloudFormation, and why you should too.

History

Until recently, CloudFormation templates could only be written in JSON. While YAML and JSON have similar semantic capabilities, YAML was designed to be human-readable while JSON was most definitely not.

Issues with JSON

JSON was designed as a serialization format. It is explicit and most suitable for data interchange between web APIs. JSON is also defined by a very simple spec. You can learn JSON very quickly, due to its anemic feature set.

Here’s an example CloudFormation template in JSON.

Can you tell what that security group does? How about the OS version specified by that AMI?

{
  "Parameters" : {
    "KeyName" : {
      "Description" : "The EC2 Key Pair to allow SSH access to the instance",
      "Type" : "AWS::EC2::KeyPair::KeyName"
    }
  },
  "Resources" : {
    "Ec2Instance" : {
      "Type" : "AWS::EC2::Instance",
      "Properties" : {
        "SecurityGroups" : [ "MyExistingSecurityGroup" ],
        "KeyName" : { "Ref" : "KeyName"},
        "ImageId" : "ami-6869aa05"
      }
    }
  }
}

You can imagine this getting entirely unmanageable for even the simplest templates. I’ve resorted to maintaining separate documentation to demystify templates like this. Then, of course, you have to remember to update the documentation when you make a template change. And that never happens.

Advantages of YAML

YAML is a superset of JSON, which means you can parse JSON with a YAML parser. Betcha didn’t know that!

It is far better suited for configuration than JSON, making it the de facto configuration file format for cloud-native infrastructure tooling.

If you use Ansible playbooks, Docker Compose, or Kubernetes, there’s no need to adopt a different syntax - they all use YAML too.

YAML has a couple of big advantages over JSON, including the ability to self reference, support for complex datatypes, embedded block literals, comments, and more.

A big win for YAML is that it supports comments. This is very useful especially when you use it for configuration.

YAML-based templates use less punctuation and should be substantially easier to write and to read. They also allow the use of comments. CloudFormation supports essentially all of YAML, with the exception of hash merges, aliases, and some tags (binary, imap, pairs, TIMESTAMP, and set).

In addition to being more readable, YAML takes fewer characters to express the same information as JSON, and there is a character limit on the size of the template you can upload to CloudFormation.

Let’s see that same template from above in YAML format:

Parameters:
  KeyName:
    Description: The EC2 Key Pair to allow SSH access to the instance
    Type: AWS::EC2::KeyPair::KeyName
Resources:
  Ec2Instance:
    Type: AWS::EC2::Instance
    Properties:
      SecurityGroups:
      - MyExistingSecurityGroup # allow only 22/tcp inbound for 0.0.0.0/0
      KeyName:
        Ref: KeyName
      ImageId: ami-6869aa05 # Amazon Linux AMI 2016.03 HVM SSD EBS

Well that certainly clears up any confusion about that security group and AMI!

Converting Between JSON and YAML

If you want to author your CloudFormation templates in YAML, but convert to JSON at deployment time for any reason, you certainly can. There are any number of CLI and web-based tools which can facilitate this.

Keep in mind that YAML comments are removed when the YAML is converted to JSON during deployment. Complex configurations and policies can be fully explained in a comment block, which greatly increases self-service for enhancements.

Intrinsic Functions

One of the features in YAML is the ability to use a new abbreviated syntax to refer to CloudFormation intrinsic functions. The former Fn::GetAtt can now be written as !GetAtt, for example. This coupled with some other YAML syntax rules allows us to shorten up the code while still maintaining readability.

Converting JSON to YAML

AWS CloudFormation Template Flip is a tool that converts AWS CloudFormation templates between JSON and YAML formats, making use of the YAML format’s short function syntax where possible.

If you need to maintain JSON versions for backward compatibility purposes, check this tool out!

Conclusion

AWS’s support for YAML dramatically improves the DevOps experience.

I encourage you to write your configuration files in YAML format where you have the opportunity; it is designed to be readable and editable by humans.

Learn more about my DevOps on AWS services.

Why I use YAML for AWS CloudFormation