# goformation **Repository Path**: mirrors_weaveworks/goformation ## Basic Information - **Project Name**: goformation - **Description**: GoFormation is a Go library for working with CloudFormation templates. - **Primary Language**: Unknown - **License**: Apache-2.0 - **Default Branch**: master - **Homepage**: None - **GVP Project**: No ## Statistics - **Stars**: 0 - **Forks**: 0 - **Created**: 2020-08-19 - **Last Updated**: 2025-10-19 ## Categories & Tags **Categories**: Uncategorized **Tags**: None ## README ![AWS GoFormation logo](./static/logo.png) # AWS GoFormation ![Version](https://img.shields.io/github/v/release/awslabs/goformation?label=stable%20version) ![Commits since release](https://img.shields.io/github/commits-since/awslabs/goformation/latest) [![Actions Status](https://github.com/awslabs/goformation/workflows/Release/badge.svg)](https://github.com/awslabs/goformation/actions) ![Update Schema](https://github.com/awslabs/goformation/workflows/Update%20Schema/badge.svg) [![GoDoc Reference](https://godoc.org/gopkg.in/awslabs/goformation.v1?status.svg)](http://godoc.org/github.com/awslabs/goformation) ![Apache-2.0](https://img.shields.io/badge/Licence-Apache%202.0-blue.svg) ![Downloads](https://img.shields.io/github/downloads/awslabs/goformation/total) `GoFormation` is a Go library for working with AWS CloudFormation / AWS Serverless Application Model (SAM) templates. - [Main features](#main-features) - [Installation](#installation) - [Usage](#usage) - [Marshalling CloudFormation/SAM described with Go structs, into YAML/JSON](#marshalling-cloudformationsam-described-with-go-structs-into-yamljson) - [Unmarshalling CloudFormation YAML/JSON into Go structs](#unmarshalling-cloudformation-yamljson-into-go-structs) - [Updating CloudFormation / SAM Resources in GoFormation](#updating-cloudformation--sam-resources-in-goformation) - [Advanced](#advanced) - [AWS CloudFormation Intrinsic Functions](#aws-cloudformation-intrinsic-functions) - [Resolving References (Ref)](#resolving-references-ref) - [Versioning](#versioning) - [Contributing](#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/v4 ``` ## 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 ```go package main import ( "fmt" "strconv" "time" "github.com/awslabs/goformation/v4/cloudformation" "github.com/awslabs/goformation/v4/cloudformation/sns" ) func main() { // Create a new CloudFormation template template := cloudformation.NewTemplate() // Create an Amazon SNS topic, with a unique name based off the current timestamp template.Resources["MyTopic"] = &sns.Topic{ TopicName: "my-topic-" + strconv.FormatInt(time.Now().Unix(), 10), } // Create a subscription, connected to our topic, that forwards notifications to an email address template.Resources["MyTopicSubscription"] = &sns.Subscription{ TopicArn: cloudformation.Ref("MyTopic"), Protocol: "email", Endpoint: "some.email@example.com", } // Let's see the JSON AWS CloudFormation template j, err := template.JSON() if err != nil { fmt.Printf("Failed to generate JSON: %s\n", err) } else { fmt.Printf("%s\n", string(j)) } // and also the YAML AWS CloudFormation template 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: ```javascript { "AWSTemplateFormatVersion": "2010-09-09", "Resources": { "MyTopic": { "Properties": { "TopicName": "my-topic-1536878058" }, "Type": "AWS::SNS::Topic" }, "MyTopicSubscription": { "Properties": { "Endpoint": "some.email@example.com", "Protocol": "email", "TopicArn": { "Ref": "MyTopic" } }, "Type": "AWS::SNS::Subscription" } } } ``` ...and the following YAML template: ```yaml AWSTemplateFormatVersion: 2010-09-09 Resources: MyTopic: Properties: TopicName: my-topic-1536878058 Type: AWS::SNS::Topic MyTopicSubscription: Properties: Endpoint: some.email@example.com Protocol: email TopicArn: Ref: MyTopic Type: AWS::SNS::Subscription ``` When creating templates, you can use the following convenience functions to use [AWS CloudFormation Intrinsics](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/intrinsic-function-reference.html): - `cloudformation.Ref(logicalName string)` - `cloudformation.GetAtt(logicalName string, attribute string)` - `cloudformation.ImportValue(name string)` - `cloudformation.Base64(input string)` - `cloudformation.CIDR(ipBlock, count, cidrBits string)` - `cloudformation.FindInMap(mapName, topLevelKey, secondLevelKey string)` - `cloudformation.GetAZs(region string)` - `cloudformation.Join(delimiter string, values []string)` - `cloudformation.Select(index string, list []string)` - `cloudformation.Split(delimiter, source string)` - `cloudformation.Sub(value string)` - `And(conditions []string)` - `Equals(value1, value2 string)` - `If(value, ifEqual, ifNotEqual string)` - `Not(conditions []string)` - `Or(conditions []string)` ### Unmarshalling CloudFormation YAML/JSON into Go structs GoFormation also works the other way - parsing JSON/YAML CloudFormation/SAM templates into Go structs. ```go package main import ( "log" "github.com/awslabs/goformation/v4" ) 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.GetAllServerlessFunctionResources() 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.GetServerlessFunctionWithName(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/](cloudformation/) directory. These can be generated, from the latest [AWS CloudFormation Resource Specification](http://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/cfn-resource-specification.html) 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](http://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/intrinsic-function-reference.html) are supported in GoFormation: - [x] [Fn::Base64](intrinsics/fnbase64.go) - [x] [Fn::FindInMap](intrinsics/fnfindinmap.go) - [x] [Fn::Join](intrinsics/fnjoin.go) - [x] [Fn::Select](intrinsics/fnselect.go) - [x] [Fn::Split](intrinsics/fnsplit.go) - [x] [Fn::Sub](intrinsics/fnsub.go) - [x] [Ref](intrinsics/ref.go) - [x] [Fn::And](intrinsics/fnand.go) - [x] [Fn::Equals](intrinsics/fnequals.go) - [x] [Fn::If](intrinsics/fnif.go) - [x] [Fn::Not](intrinsics/fnnot.go) - [x] [Fn::Or](intrinsics/fnor.go) - [ ] Fn::GetAtt - [x] [Fn::GetAZs](intrinsics/fngetazs.go) - [ ] Fn::ImportValue Any unsupported intrinsic functions will return `nil`. #### Resolving References (Ref) When converting a YAML/JSON template to go, the intrinsic 'Ref' function as implemented will resolve all of the [pseudo parameters](http://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/intrinsic-function-reference-ref.html) such as `AWS::AccountId` with their default value as listed on [the bottom of this page](http://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/intrinsic-function-reference-ref.html). 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](https://github.com/semantic-release/semantic-release). ## Contributing Contributions and feedback are welcome! Proposals and pull requests will be considered and responded to. For more information, see the [CONTRIBUTING](CONTRIBUTING.md) file.