GoFormation is a Go library for working with CloudFormation templates.
Go Other
Clone or download
PaulMaddox Merge pull request #97 from PaulMaddox/master
Removed semantic-release as it is breaking builds right now
Latest commit cb0dddd Jul 21, 2018

README.md

AWS GoFormation

Build Status GoDoc Reference Apache-2.0

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

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:

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.