goformation

README

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 (
	"log"

	"github.com/awslabs/goformation"
)

func main() {

	// Open a template from file (can be JSON or YAML)
	template, err := goformation.Open("template.yaml")
	if err != nil {
		log.Fatalf("There was an error processing the template: %s", err)
	}

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

		// E.g. Found a AWS::Serverless::Function named GetHelloWorld (runtime: nodejs6.10)
		log.Printf("Found a %s named %s (runtime: %s)\n", function.AWSCloudFormationType(), name, function.Runtime)

	}

	// You can also search for specific resources by their logicalId
	search := "GetHelloWorld"
	function, err := template.GetAWSServerlessFunctionWithName(search)
	if err != nil {
		log.Fatalf("Function not found")
	}

	// E.g. Found a AWS::Serverless::Function named GetHelloWorld (runtime: nodejs6.10)
	log.Printf("Found a %s named %s (runtime: %s)\n", function.AWSCloudFormationType(), search, function.Runtime)

}

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.

Versioning

This library is automatically versioned and tagged using semantic-release.

Contributing

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

Documentation

Index

• func Open(filename string) (*cloudformation.Template, error)
• func OpenWithOptions(filename string, options *intrinsics.ProcessorOptions) (*cloudformation.Template, error)
• func ParseJSON(data []byte) (*cloudformation.Template, error)
• func ParseJSONWithOptions(data []byte, options *intrinsics.ProcessorOptions) (*cloudformation.Template, error)
• func ParseYAML(data []byte) (*cloudformation.Template, error)
• func ParseYAMLWithOptions(data []byte, options *intrinsics.ProcessorOptions) (*cloudformation.Template, error)

Functions

func Open

func Open(filename string) (*cloudformation.Template, error)

Open and parse a AWS CloudFormation template from file. Works with either JSON or YAML formatted templates.

func OpenWithOptions

func OpenWithOptions(filename string, options *intrinsics.ProcessorOptions) (*cloudformation.Template, error)

OpenWithOptions opens and parse a AWS CloudFormation template from file. Works with either JSON or YAML formatted templates. Parsing can be tweaked via the specified options.

func ParseJSON

func ParseJSON(data []byte) (*cloudformation.Template, error)

ParseJSON an AWS CloudFormation template (expects a []byte of valid JSON)

func ParseJSONWithOptions

func ParseJSONWithOptions(data []byte, options *intrinsics.ProcessorOptions) (*cloudformation.Template, error)

ParseJSONWithOptions an AWS CloudFormation template (expects a []byte of valid JSON) Parsing can be tweaked via the specified options.

func ParseYAML

func ParseYAML(data []byte) (*cloudformation.Template, error)

ParseYAML an AWS CloudFormation template (expects a []byte of valid YAML)

func ParseYAMLWithOptions

func ParseYAMLWithOptions(data []byte, options *intrinsics.ProcessorOptions) (*cloudformation.Template, error)

ParseYAMLWithOptions an AWS CloudFormation template (expects a []byte of valid YAML) Parsing can be tweaked via the specified options.