Did you know that CloudFormation templates come in two flavors? YAML and JSON. When CloudFormation launched, JSON was the only format supported. YAML was introduced to CloudFormation in 2016. Both JSON and YAML are text and can be edited in any text editor. But more importantly, they can be managed in your version control system just like you do your application code.

Why YAML?

JSON was designed for the serialization of data, not configuration. Comments aren't supported, which means you can't add important context to your infrastructure code.

YAML supports comments and it's human readable. Instead of curly braces and commas to represent hierarchy, it uses indentation. YAML takes less characters to represent the same configuration. All of this makes it easier to read and troubleshoot complex CloudFormation templates.

What if you don't have YAML?

Sometimes you have a JSON template you want to convert to YAML or vice versa, which is what I ran into today. I found this template (from the sample templates in the AWS docs) to provision a highly available, scalable Ruby on Rails stack with a multi-AZ MySQL Amazon RDS database. I had no desire to read through the full JSON but I did want to understand the various parts of the template that make this work for this use case.

Enter AWS CloudFormation Template Flip.

AWS CloudFormation Template Flip is a command-line tool (and also a python library), you can use to convert a JSON template to YAML.

From the command line:

$ cfn-flip s3.json

You can convert this JSON template:

{
    "AWSTemplateFormatVersion": "2010-09-09",
    "Description": "Example for creating an S3 Bucket",
    "Resources": {
        "MyBucket": {
            "Type": "AWS::S3::Bucket",
            "Properties": {
                "BucketName": "my-bucket"
            }
        }
    }
}

To YAML:

AWSTemplateFormatVersion: '2010-09-09'
Description: Example for creating an S3 Bucket
Resources:
  MyBucket:
    Type: AWS::S3::Bucket
    Properties:
      BucketName: my-bucket

Flip Back to JSON

You can also use cfn-flip to convert from YAML back to JSON. Just remember that you'll lose any comments from the original YAML template when you do.

For instance, when converting this YAML template:

AWSTemplateFormatVersion: 2010-09-09
Description: Example for creating an S3 Bucket

Resources:
  MyBucket:
    Type: AWS::S3::Bucket
    Properties:
      BucketName: my-bucket
      # Uncomment to enable bucket encryption
      # BucketEncryption:
      #   ServerSideEncryptionConfiguration:
      #     - ServerSideEncryptionByDefault:
      #         SSEAlgorithm: 'aws:kms'

To JSON:

{
    "AWSTemplateFormatVersion": "2010-09-09",
    "Description": "Example for creating an S3 Bucket",
    "Resources": {
        "MyBucket": {
            "Type": "AWS::S3::Bucket",
            "Properties": {
                "BucketName": "my-bucket"
            }
        }
    }
}

You'll lose the comments.

Ready to use cfn-flip? You can install it with pip or brew and find more info on how to use it here.

Wrap Up

I hope this helps you the next time you have a CloudFormation template in a format that you can't or don't want to use. You can flip between JSON and YAML and back again with cfn-flip at the command line, just beware that when going from YAML to JSON you'll lose out on those important comments.

Like what you read? Follow me here on Dev.to or on Twitter to stay updated!