ardeshir / goformation

GoFormation is a Go library for working with CloudFormation templates.

AWS GoFormation

GoFormation is a Go library for working with AWS CloudFormation / AWS Serverless Application Model (SAM) templates.

• AWS GoFormation
  • Main features
  • Installation
  • Usage
    • Marshalling CloudFormation/SAM described with Go structs, into YAML/JSON
    • Unmarshalling CloudFormation YAML/JSON into Go structs
  • Updating CloudFormation / SAM Resources in GoFormation
  • Advanced
    • AWS CloudFormation Intrinsic Functions
      • Resolving References (Ref)
  • Contributing

Main features

• Describe AWS CloudFormation and AWS SAM templates as Go objects (structs), and then turn it into JSON/YAML.
• Parse JSON/YAML AWS CloudFormation and AWS SAM templates and turn them into Go structs.
• Strongly typed Go structs generated for every AWS CloudFormation and AWS SAM resource.
• Automatically generated, from the published AWS CloudFormation Resource Specification.

Installation

As with other Go libraries, GoFormation can be installed with go get.

$ go get github.com/awslabs/goformation

Usage

Marshalling CloudFormation/SAM described with Go structs, into YAML/JSON

Below is an example of building a CloudFormation template programmatically, then outputting the resulting JSON

package main

import (
	"fmt"

	"github.com/awslabs/goformation/cloudformation"
)

func main() {

	// Create a new CloudFormation template
	template := cloudformation.NewTemplate()

	// An an example SNS Topic
	template.Resources["MySNSTopic"] = &cloudformation.AWSSNSTopic{
		DisplayName: "test-sns-topic-display-name",
		TopicName:   "test-sns-topic-name",
		Subscription: []cloudformation.AWSSNSTopic_Subscription{
			cloudformation.AWSSNSTopic_Subscription{
				Endpoint: "test-sns-topic-subscription-endpoint",
				Protocol: "test-sns-topic-subscription-protocol",
			},
		},
	}

	// ...and a Route 53 Hosted Zone too
	template.Resources["MyRoute53HostedZone"] = &cloudformation.AWSRoute53HostedZone{
		Name: "example.com",
	}

	// Let's see the JSON
	j, err := template.JSON()
	if err != nil {
		fmt.Printf("Failed to generate JSON: %s\n", err)
	} else {
		fmt.Printf("%s\n", string(j))
	}

	y, err := template.YAML()
	if err != nil {
		fmt.Printf("Failed to generate YAML: %s\n", err)
	} else {
		fmt.Printf("%s\n", string(y))
	}

}

Would output the following JSON template:

{
  "AWSTemplateFormatVersion": "2010-09-09",
  "Resources": {
    "MyRoute53HostedZone": {
      "Type": "AWS::Route53::HostedZone",
      "Properties": {
        "Name": "example.com"
      }
    },
    "MySNSTopic": {
      "Type": "AWS::SNS::Topic",
      "Properties": {
        "DisplayName": "test-sns-topic-display-name",
        "Subscription": [
          {
            "Endpoint": "test-sns-topic-subscription-endpoint",
            "Protocol": "test-sns-topic-subscription-protocol"
          }
        ],
        "TopicName": "test-sns-topic-name"
      }
    }
  }
}

...and the following YAML template:

AWSTemplateFormatVersion: 2010-09-09
Resources:
  MyRoute53HostedZone:
    Type: AWS::Route53::HostedZone
    Properties:
      Name: example.com
  MySNSTopic:
    Type: AWS::SNS::Topic
    Properties:
      DisplayName: test-sns-topic-display-name
      Subscription:
      - Endpoint: test-sns-topic-subscription-endpoint
        Protocol: test-sns-topic-subscription-protocol
      TopicName: test-sns-topic-name

Unmarshalling CloudFormation YAML/JSON into Go structs

GoFormation also works the other way - parsing JSON/YAML CloudFormation/SAM templates into Go structs.

package main

import (
    "fmt"
    "github.com/awslabs/goformation"
    "github.com/awslabs/goformation/cloudformation"
)

func main() {

    // Open a template from file (can be JSON or YAML)
    template, err := goformation.Open("template.yaml")

    // ...or provide one as a byte array ([]byte)
    template, err := goformation.ParseYAML(data)

    // You can then inspect all of the values
    for name, resource := range template.Resources {

        // E.g. Found a resource with name MyLambdaFunction and type AWS::Lambda::Function
        log.Printf("Found a resource with name %s and type %s", name, resource.Type)

    }

    // You can extract all resources of a certain type
    // Each AWS CloudFormation / SAM resource is a strongly typed struct
    functions := template.GetAllAWSLambdaFunctionResources()
    for name, function := range functions {

        // E.g. Found a AWS::Lambda::Function with name MyLambdaFunction and nodejs6.10 handler 
        log.Printf("Found a %s with name %s and %s handler", name, function.Type(), function.Handler)

    }

}

Updating CloudFormation / SAM Resources in GoFormation

AWS GoFormation contains automatically generated Go structs for every CloudFormation/SAM resource, located in the cloudformation/ directory. These can be generated, from the latest AWS CloudFormation Resource Specification published for us-east-1 by just running go generate:

$ go generate

Generated 587 AWS CloudFormation resources from specification v1.4.2
Generated 17 AWS SAM resources from specification v2016-10-31
Generated JSON Schema: schema/cloudformation.schema.json

The GoFormation build pipeline automatically checks for any updated AWS CloudFormation resources on a daily basis, and creates a pull request against this repository if any are found.

Advanced

AWS CloudFormation Intrinsic Functions

The following AWS CloudFormation Intrinsic Functions are supported in GoFormation:

• Fn::Base64
• Fn::FindInMap
• Fn::Join
• Fn::Select
• Fn::Split
• Fn::Sub
• Ref
• Fn::And
• Fn::Equals
• Fn::If
• Fn::Not
• Fn::Or
• Fn::GetAtt
• Fn::GetAZs
• Fn::ImportValue

Any unsupported intrinsic functions will return nil.

Resolving References (Ref)

The intrinsic 'Ref' function as implemented will resolve all of the pseudo parameters such as AWS::AccountId with their default value as listed on the bottom of this page.

If a reference is not a pseudo parameter, GoFormation will try to resolve it within the AWS CloudFormation template. Currently, this implementation only searches for Parameters with a name that matches the ref, and returns the Default if it has one.

Contributing

Contributions and feedback are welcome! Proposals and pull requests will be considered and responded to. For more information, see the CONTRIBUTING file.