README
¶
AWS GoFormation
GoFormation is a Go library for working with AWS CloudFormation / AWS Serverless Application Model (SAM) templates.
- AWS GoFormation
Main features
- Describe CloudFormation / SAM templates as Go structs, and then turn it into JSON/YAML
- Parse JSON/YAML CloudFormation / SAM templates and turn them into Go structs
Installation
As with other Go libraries, GoFormation can be installed with go get.
$ go get github.com/awslabs/goformation
Usage
Marhsalling CloudFormation/SAM described with Go structs, into YAML/JSON
Below is an example of building a CloudFormation template programatically, then outputting the resulting JSON
package main
import (
"fmt"
"github.com/awslabs/goformation"
"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.Print(j)
}
y, err := template.YAML()
if err != nil {
fmt.Printf("Failed to generate JSON: %s\n", err)
} else {
fmt.Print(y)
}
}
Would output the following JSON template
{
"AWSTemplateFormatVersion": "2010-09-09",
"Resources": {
"MyRoute53HostedZone": {
"Name": "example.com"
},
"MySNSTopic": {
"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:
Name: example.com
MySNSTopic:
DisplayName: test-sns-topic-display-name
Subscription:
- Endpoint: test-sns-topic-subscription-endpoint
Protocol: test-sns-topic-subscription-protocol
TopicName: test-sns-topic-name
Unmarhalling 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.Parse(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
Our aim is to automatically update GoFormation whenever the AWS CloudFormation Resource Specification changes, via an automated pull request to this repository. This is not currently in place.
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.
Warning: YAML short form intrinsic functions (e.g. !Sub)
While this library supports both JSON and YAML AWS CloudFormation templates, it cannot handle short form intrinsic functions in YAML templates (e.g. !Sub).
We will be adding support soon, however we need to patch Go's YAML library as it doesn't currently support tags.
If you use a short form intrinsic function today, you'll either get the unresolved value (if the recieving field is a string field), or the template will fail to parse (if it's recieving field is a non-string field).
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 ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
Types ¶
This section is empty.
Source Files
Directories