Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/awslabs/goformation

GoFormation is a Go library for working with CloudFormation templates.
https://github.com/awslabs/goformation

aws aws-cloudformation aws-sam cloudformation golang parser

Last synced: about 2 months ago
JSON representation

GoFormation is a Go library for working with CloudFormation templates.

Host: GitHub
URL: https://github.com/awslabs/goformation
Owner: awslabs
License: apache-2.0
Created: 2017-08-01T16:30:58.000Z (about 7 years ago)
Default Branch: master
Last Pushed: 2024-04-06T00:11:50.000Z (5 months ago)
Last Synced: 2024-04-06T01:26:58.420Z (5 months ago)
Topics: aws, aws-cloudformation, aws-sam, cloudformation, golang, parser
Language: Go
Homepage:
Size: 30.4 MB
Stars: 834
Watchers: 26
Forks: 193
Open Issues: 49
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- Contributing: CONTRIBUTING.md
- License: LICENSE
- Code of conduct: CODE_OF_CONDUCT.md
- Authors: AUTHORS.md

Awesome Lists containing this project

awesome-repositories - awslabs/goformation - GoFormation is a Go library for working with CloudFormation templates. (Go)
awesome-list - goformation

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.

- [AWS GoFormation](#aws-goformation)

	- [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/v7

```

## 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/v7/cloudformation"

	"github.com/awslabs/goformation/v7/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: cloudformation.String("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: cloudformation.String("[email protected]"),

	}

	// 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": "[email protected]",

        "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: [email protected]

      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/v7"

)

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](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/pseudo-parameter-reference.html) such as `AWS::AccountId` with their default value as listed on the 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](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.