{"id":13430853,"url":"https://github.com/awslabs/goformation","last_synced_at":"2025-03-16T06:31:34.659Z","repository":{"id":23930488,"uuid":"99021999","full_name":"awslabs/goformation","owner":"awslabs","description":"GoFormation is a Go library for working with CloudFormation templates.","archived":false,"fork":false,"pushed_at":"2024-04-06T00:11:50.000Z","size":31837,"stargazers_count":834,"open_issues_count":49,"forks_count":193,"subscribers_count":26,"default_branch":"master","last_synced_at":"2024-04-06T01:26:58.420Z","etag":null,"topics":["aws","aws-cloudformation","aws-sam","cloudformation","golang","parser"],"latest_commit_sha":null,"homepage":"","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/awslabs.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":"AUTHORS.md","dei":null}},"created_at":"2017-08-01T16:30:58.000Z","updated_at":"2024-04-15T09:49:55.787Z","dependencies_parsed_at":"2024-04-15T09:59:39.197Z","dependency_job_id":null,"html_url":"https://github.com/awslabs/goformation","commit_stats":{"total_commits":730,"total_committers":67,"mean_commits":"10.895522388059701","dds":0.7643835616438356,"last_synced_commit":"df25a1d847c7d0e2f827d2d60a11f2b1f5c226ce"},"previous_names":["awslabs/aws-goformation"],"tags_count":235,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/awslabs%2Fgoformation","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/awslabs%2Fgoformation/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/awslabs%2Fgoformation/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/awslabs%2Fgoformation/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/awslabs","download_url":"https://codeload.github.com/awslabs/goformation/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":221656449,"owners_count":16858773,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["aws","aws-cloudformation","aws-sam","cloudformation","golang","parser"],"created_at":"2024-07-31T02:00:58.433Z","updated_at":"2024-10-27T09:31:00.625Z","avatar_url":"https://github.com/awslabs.png","language":"Go","funding_links":[],"categories":["Go","aws"],"sub_categories":[],"readme":"![AWS GoFormation logo](./static/logo.png)\n\n# AWS GoFormation\n\n![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)\n\n`GoFormation` is a Go library for working with AWS CloudFormation / AWS Serverless Application Model (SAM) templates.\n\n- [AWS GoFormation](#aws-goformation)\n\t- [Main features](#main-features)\n\t- [Installation](#installation)\n\t- [Usage](#usage)\n\t\t- [Marshalling CloudFormation/SAM described with Go structs, into YAML/JSON](#marshalling-cloudformationsam-described-with-go-structs-into-yamljson)\n\t\t- [Unmarshalling CloudFormation YAML/JSON into Go structs](#unmarshalling-cloudformation-yamljson-into-go-structs)\n\t- [Updating CloudFormation / SAM Resources in GoFormation](#updating-cloudformation--sam-resources-in-goformation)\n\t- [Advanced](#advanced)\n\t\t- [AWS CloudFormation Intrinsic Functions](#aws-cloudformation-intrinsic-functions)\n\t\t\t- [Resolving References (Ref)](#resolving-references-ref)\n\t- [Versioning](#versioning)\n\t- [Contributing](#contributing)\n\n## Main features\n\n * Describe AWS CloudFormation and AWS SAM templates as Go objects (structs), and then turn it into JSON/YAML.\n * Parse JSON/YAML AWS CloudFormation and AWS SAM templates and turn them into Go structs.\n * Strongly typed Go structs generated for every AWS CloudFormation and AWS SAM resource.\n * Automatically generated, from the published AWS CloudFormation Resource Specification.\n\n## Installation\n\nAs with other Go libraries, GoFormation can be installed with `go get`.\n\n```\n$ go get github.com/awslabs/goformation/v7\n```\n\n## Usage\n\n### Marshalling CloudFormation/SAM described with Go structs, into YAML/JSON\n\nBelow is an example of building a CloudFormation template programmatically, then outputting the resulting JSON\n\n```go\npackage main\n\nimport (\n\t\"fmt\"\n\t\"strconv\"\n\t\"time\"\n\n\t\"github.com/awslabs/goformation/v7/cloudformation\"\n\t\"github.com/awslabs/goformation/v7/cloudformation/sns\"\n)\n\nfunc main() {\n\n\t// Create a new CloudFormation template\n\ttemplate := cloudformation.NewTemplate()\n\n\t// Create an Amazon SNS topic, with a unique name based off the current timestamp\n\ttemplate.Resources[\"MyTopic\"] = \u0026sns.Topic{\n\t\tTopicName: cloudformation.String(\"my-topic-\" + strconv.FormatInt(time.Now().Unix(), 10)),\n\t}\n\n\t// Create a subscription, connected to our topic, that forwards notifications to an email address\n\ttemplate.Resources[\"MyTopicSubscription\"] = \u0026sns.Subscription{\n\t\tTopicArn: cloudformation.Ref(\"MyTopic\"),\n\t\tProtocol: \"email\",\n\t\tEndpoint: cloudformation.String(\"some.email@example.com\"),\n\t}\n\n\t// Let's see the JSON AWS CloudFormation template\n\tj, err := template.JSON()\n\tif err != nil {\n\t\tfmt.Printf(\"Failed to generate JSON: %s\\n\", err)\n\t} else {\n\t\tfmt.Printf(\"%s\\n\", string(j))\n\t}\n\n\t// and also the YAML AWS CloudFormation template\n\ty, err := template.YAML()\n\tif err != nil {\n\t\tfmt.Printf(\"Failed to generate YAML: %s\\n\", err)\n\t} else {\n\t\tfmt.Printf(\"%s\\n\", string(y))\n\t}\n\n}\n```\n\nWould output the following JSON template:\n\n```javascript\n{\n  \"AWSTemplateFormatVersion\": \"2010-09-09\",\n  \"Resources\": {\n    \"MyTopic\": {\n      \"Properties\": {\n        \"TopicName\": \"my-topic-1536878058\"\n      },\n      \"Type\": \"AWS::SNS::Topic\"\n    },\n    \"MyTopicSubscription\": {\n      \"Properties\": {\n        \"Endpoint\": \"some.email@example.com\",\n        \"Protocol\": \"email\",\n        \"TopicArn\": {\n          \"Ref\": \"MyTopic\"\n        }\n      },\n      \"Type\": \"AWS::SNS::Subscription\"\n    }\n  }\n}\n```\n\n...and the following YAML template:\n\n```yaml\nAWSTemplateFormatVersion: 2010-09-09\nResources:\n  MyTopic:\n    Properties:\n      TopicName: my-topic-1536878058\n    Type: AWS::SNS::Topic\n  MyTopicSubscription:\n    Properties:\n      Endpoint: some.email@example.com\n      Protocol: email\n      TopicArn:\n        Ref: MyTopic\n    Type: AWS::SNS::Subscription\n```\n\nWhen 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):\n\n - `cloudformation.Ref(logicalName string)`\n - `cloudformation.GetAtt(logicalName string, attribute string)`\n - `cloudformation.ImportValue(name string)`\n - `cloudformation.Base64(input string)`\n - `cloudformation.CIDR(ipBlock, count, cidrBits string)`\n - `cloudformation.FindInMap(mapName, topLevelKey, secondLevelKey string)`\n - `cloudformation.GetAZs(region string)`\n - `cloudformation.Join(delimiter string, values []string)`\n - `cloudformation.Select(index string, list []string)`\n - `cloudformation.Split(delimiter, source string)`\n - `cloudformation.Sub(value string)`\n - `And(conditions []string)`\n - `Equals(value1, value2 string)`\n - `If(value, ifEqual, ifNotEqual string)`\n - `Not(conditions []string)`\n - `Or(conditions []string)`\n\n### Unmarshalling CloudFormation YAML/JSON into Go structs\n\nGoFormation also works the other way - parsing JSON/YAML CloudFormation/SAM templates into Go structs.\n\n```go\npackage main\n\nimport (\n\t\"log\"\n\n\t\"github.com/awslabs/goformation/v7\"\n)\n\nfunc main() {\n\n\t// Open a template from file (can be JSON or YAML)\n\ttemplate, err := goformation.Open(\"template.yaml\")\n\tif err != nil {\n\t\tlog.Fatalf(\"There was an error processing the template: %s\", err)\n\t}\n\n\t// You can extract all resources of a certain type\n\t// Each AWS CloudFormation resource is a strongly typed struct\n\tfunctions := template.GetAllServerlessFunctionResources()\n\tfor name, function := range functions {\n\n\t\t// E.g. Found a AWS::Serverless::Function named GetHelloWorld (runtime: nodejs6.10)\n\t\tlog.Printf(\"Found a %s named %s (runtime: %s)\\n\", function.AWSCloudFormationType(), name, function.Runtime)\n\n\t}\n\n\t// You can also search for specific resources by their logicalId\n\tsearch := \"GetHelloWorld\"\n\tfunction, err := template.GetServerlessFunctionWithName(search)\n\tif err != nil {\n\t\tlog.Fatalf(\"Function not found\")\n\t}\n\n\t// E.g. Found a AWS::Serverless::Function named GetHelloWorld (runtime: nodejs6.10)\n\tlog.Printf(\"Found a %s named %s (runtime: %s)\\n\", function.AWSCloudFormationType(), search, function.Runtime)\n\n}\n```\n\n## Updating CloudFormation / SAM Resources in GoFormation\n\nAWS 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`:\n\n```\n$ go generate\n\nGenerated 587 AWS CloudFormation resources from specification v1.4.2\nGenerated 17 AWS SAM resources from specification v2016-10-31\nGenerated JSON Schema: schema/cloudformation.schema.json\n```\n\nThe 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.\n\n## Advanced\n\n### AWS CloudFormation Intrinsic Functions\n\nThe following [AWS CloudFormation Intrinsic Functions](http://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/intrinsic-function-reference.html) are supported in GoFormation:\n\n- [x] [Fn::Base64](intrinsics/fnbase64.go)\n- [x] [Fn::FindInMap](intrinsics/fnfindinmap.go)\n- [x] [Fn::Join](intrinsics/fnjoin.go)\n- [x] [Fn::Select](intrinsics/fnselect.go)\n- [x] [Fn::Split](intrinsics/fnsplit.go)\n- [x] [Fn::Sub](intrinsics/fnsub.go)\n- [x] [Ref](intrinsics/ref.go)\n- [x] [Fn::And](intrinsics/fnand.go)\n- [x] [Fn::Equals](intrinsics/fnequals.go)\n- [x] [Fn::If](intrinsics/fnif.go)\n- [x] [Fn::Not](intrinsics/fnnot.go)\n- [x] [Fn::Or](intrinsics/fnor.go)\n- [ ] Fn::GetAtt\n- [x] [Fn::GetAZs](intrinsics/fngetazs.go)\n- [ ] Fn::ImportValue\n\nAny unsupported intrinsic functions will return `nil`.\n\n#### Resolving References (Ref)\n\nWhen 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.\n\nIf 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.**\n\n\n## Versioning\n\nThis library is automatically versioned and tagged using [semantic-release](https://github.com/semantic-release/semantic-release).\n\n## Contributing\n\nContributions and feedback are welcome! Proposals and pull requests will be considered and responded to. For more information, see the [CONTRIBUTING](CONTRIBUTING.md) file.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fawslabs%2Fgoformation","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fawslabs%2Fgoformation","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fawslabs%2Fgoformation/lists"}