AWS CloudFormation Template Flip

1.3.0 · active · verified Thu Apr 09

cfn-flip is a Python library and command-line tool for converting AWS CloudFormation templates between JSON and YAML formats, making use of YAML's short function syntax where possible. The library is currently at version 1.3.0, with the last release in 2021, suggesting a maintenance rather than active rapid development cadence for the core library, though the CLI usage is deprecated.

Warnings

deprecated The command-line interface (CLI) of `cfn-flip` is officially deprecated. Users are advised to use `rain fmt` from the `aws-cloudformation/rain` project for CLI-based template formatting and conversion instead.
Fix: Migrate CLI usage from `cfn-flip` to `rain fmt`. For example, `cfn-flip -j template.yaml` becomes `rain fmt template.yaml --json`.
gotcha Converting JSON templates to YAML using `cfn-flip`'s default shorthand syntax for intrinsic functions (e.g., `!Ref`, `!GetAtt`) can unexpectedly cause CloudFormation Change Sets to propose resource replacement instead of modification, even if no logical change occurred. This can lead to unintended downtime or data loss.
Fix: When converting from JSON to YAML, consider using the `--long` option with the `cfn-flip` CLI (if still using it) or manually ensuring long-form function syntax in the YAML output to avoid unexpected resource replacements. Thoroughly review CloudFormation Change Sets before execution after conversion.
gotcha When converting a CloudFormation template from YAML to JSON format using `cfn-flip`, any comments present in the original YAML template will be lost in the resulting JSON output, as JSON does not natively support comments.
Fix: Be aware of this limitation and ensure important contextual information is not solely reliant on YAML comments if JSON conversion is part of your workflow. Consider documenting templates externally or retaining the YAML source if comments are critical.
gotcha `cfn-flip` uses a YAML parser that is more strict than the AWS CloudFormation service itself. This means that `cfn-flip` might flag certain YAML syntax issues (e.g., using tabs instead of spaces for indentation) as errors, even though CloudFormation might accept them.
Fix: Adhere strictly to the YAML specification (e.g., use spaces for indentation, not tabs) to ensure compatibility with `cfn-flip` and other YAML tooling like `cfn-lint`. This generally leads to more robust and portable templates.

Install

pip install cfn-flip Install with pip

Imports

flip
```
from cfn_flip import flip
```
General conversion function, attempts to detect input format.
to_yaml
```
from cfn_flip import to_yaml
```
Converts a JSON or YAML string to YAML format.
to_json
```
from cfn_flip import to_json
```
Converts a JSON or YAML string to JSON format.

Quickstart

This quickstart demonstrates how to use the `to_yaml` and `to_json` functions to convert CloudFormation templates between JSON and YAML formats within a Python script. It shows conversion from a JSON string to YAML and from a YAML string to JSON.

from cfn_flip import to_yaml, to_json

json_template = '''
{
  "AWSTemplateFormatVersion": "2010-09-09",
  "Description": "Example JSON template",
  "Resources": {
    "MyS3Bucket": {
      "Type": "AWS::S3::Bucket",
      "Properties": {
        "BucketName": "my-unique-example-bucket"
      }
    }
  }
}
'''

yaml_output = to_yaml(json_template)
print("--- JSON to YAML ---")
print(yaml_output)

yaml_template = '''
AWSTemplateFormatVersion: '2010-09-09'
Description: Example YAML template
Resources:
  MyLambdaFunction:
    Type: AWS::Lambda::Function
    Properties:
      Handler: index.handler
      Role: !GetAtt MyLambdaRole.Arn
      Code:
        S3Bucket: my-code-bucket
        S3Key: my-code.zip
      Runtime: python3.9
'''

json_output = to_json(yaml_template)
print("\n--- YAML to JSON ---")
print(json_output)

view raw JSON →