{"id":19665798,"url":"https://github.com/seanedwards/cfer","last_synced_at":"2025-09-25T23:05:04.659Z","repository":{"id":32254312,"uuid":"35828678","full_name":"seanedwards/cfer","owner":"seanedwards","description":"Toolkit and Ruby DSL for automating infrastructure using AWS CloudFormation","archived":false,"fork":false,"pushed_at":"2024-01-08T15:41:42.000Z","size":812,"stargazers_count":90,"open_issues_count":6,"forks_count":18,"subscribers_count":8,"default_branch":"master","last_synced_at":"2025-03-30T07:12:04.517Z","etag":null,"topics":["aws","cloudformation","ruby"],"latest_commit_sha":null,"homepage":"","language":"Ruby","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/seanedwards.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE.txt","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":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2015-05-18T16:17:43.000Z","updated_at":"2023-02-26T04:23:36.000Z","dependencies_parsed_at":"2024-06-19T15:29:10.985Z","dependency_job_id":"c226b754-6bb4-4376-a392-6d03b3b39367","html_url":"https://github.com/seanedwards/cfer","commit_stats":{"total_commits":266,"total_committers":14,"mean_commits":19.0,"dds":"0.18045112781954886","last_synced_commit":"28361f4ebc6df24b08cb7a8d36c93bfe938125df"},"previous_names":[],"tags_count":24,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/seanedwards%2Fcfer","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/seanedwards%2Fcfer/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/seanedwards%2Fcfer/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/seanedwards%2Fcfer/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/seanedwards","download_url":"https://codeload.github.com/seanedwards/cfer/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247457803,"owners_count":20941906,"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","cloudformation","ruby"],"created_at":"2024-11-11T16:24:50.673Z","updated_at":"2025-09-25T23:04:55.530Z","avatar_url":"https://github.com/seanedwards.png","language":"Ruby","readme":"# Cfer\n\n![Build Status](https://github.com/seanedwards/cfer/actions/workflows/build.yml/badge.svg?branch=master)\n[![Gem Version](https://badge.fury.io/rb/cfer.svg)](http://badge.fury.io/rb/cfer)\n\n\nCfer is a lightweight toolkit for managing CloudFormation templates.\n\nRead about Cfer [here](https://github.com/seanedwards/cfer/blob/master/examples/vpc.md).\n\n## Installation\n\nAdd this line to your application's Gemfile:\n\n```ruby\ngem 'cfer'\n```\n\nAnd then execute:\n\n    $ bundle\n\nOr install it yourself as:\n\n    $ gem install cfer\n\n## Usage\n\nTo quickly see Cfer in action, try converging the example stacks:\n\n```bash\ncfer converge vpc -t examples/vpc.rb --profile [YOUR-PROFILE] --region [YOUR-REGION]\ncfer converge instance -t examples/instance.rb --profile [YOUR-PROFILE] --region [YOUR-REGION] KeyName=[YOUR-EC2-SSH-KEY]\n```\n\nYou should see something like this:\n\n![Demo](https://raw.githubusercontent.com/seanedwards/cfer/master/doc/cfer-demo.gif)\n\n### Command line\n\n    COMMANDS\n        converge     Create or update a cloudformation stack according to the template\n        delete       Deletes a CloudFormation stack\n        describe     Fetches and prints information about a CloudFormation\n        estimate     Prints a link to the Amazon cost caculator estimating the cost of the resulting CloudFormation stack\n        generate     Generates a CloudFormation template by evaluating a Cfer template\n        help         show help\n        tail         Follows stack events on standard output as they occur\n\n### Template Anatomy\n\nSee the `examples` directory for some examples of complete templates.\n\n#### Parameters\n\nParameters may be defined using the `parameter` function:\n\n```ruby\nparameter :ParameterName,\n  type: 'String',\n  default: 'ParameterValue'\n```\n\nAny parameter can be referenced either in Ruby by using the `parameters` hash:\n\n```ruby\nparameters[:ParameterName]\n```\n\nParameters can also be used in a CloudFormation reference by using the `Fn::ref` function:\n\n```ruby\nFn::ref(:ParameterName)\n```\n\n#### Resources\n\nResources may be defined using the `resource` function:\n\n```ruby\nresource :ResourceName, 'AWS::CloudFormation::CustomResource', AttributeName: {:attribute_key =\u003e 'attribute_value'} do\n  property_name 'property_value'\nend\n```\n\nGets transformed into the corresponding CloudFormation block:\n\n```json\n\"ResourceName\": {\n  \"Type\": \"AWS::CloudFormation::CustomResource\",\n  \"AttributeName\": {\n    \"attribute_key\": \"attribute_value\"\n  },\n  \"Properties\": {\n    \"PropertyName\": \"property_value\"\n  }\n}\n```\n\n#### Outputs\n\nOutputs may be defined using the `output` function:\n\n```ruby\noutput :OutputName, Fn::ref(:ResourceName)\n```\n\nOutputs may have an optional description:\n\n```ruby\noutput :OutputName, Fn::ref(:ResourceName), description: 'The resource that does stuff'\n```\n\nOutputs may be retireved from other stacks anywhere in a template by using the `lookup_output` function.\n\n```ruby\nlookup_output('stack_name', 'output_name')\n```\n\nOutputs may also be exported for use by `Fn::ImportValue` in other cloudformation stacks:\n\n```ruby\noutput :OutputName, Fn::ref(:ResourceName), export: Fn::sub('${AWS::StackName}-OutputName')\n```\n\n#### Including code from multiple files\n\nTemplates can get pretty large, and splitting template code into multiple\nfiles can help keep things more manageable. The `include_template`\nfunction works in a similar way to ruby's `require_relative`, but\nwithin the context of the CloudFormation stack:\n\n```ruby\ninclude_template 'ec2.rb'\n```\n\nYou can also include multiple files in a single call:\n\n```ruby\ninclude_template(\n  'stack/ec2.rb',\n  'stack/elb.rb'\n)\n```\n\nThe path to included files is relative to the base template file\n(e.g. the `converge` command `-t` option).\n\n## SDK\n\nEmbedding the Cfer SDK involves interacting with two components: The `Client` and the `Stack`.\nThe Cfer `Client` is the interface with the Cloud provider.\n\n### Basic API\n\nThe simplest way to use Cfer from Ruby looks similar to the CLI:\n\n```ruby\n  Cfer.converge! '\u003cstack-name\u003e', template: '\u003ctemplate-file\u003e'\n```\n\nThis is identical to running `cfer converge \u003cstack-name\u003e --template \u003ctemplate-file\u003e`, but is better suited to embedding in Rakefiles, chef recipes, or your own Ruby scripts.\nSee the Rakefile in this repository for how this might look.\n\n### Cfn Client\n\nThe Client is a wrapper around Amazon's CloudFormation client from the AWS Ruby SDK.\nIts purpose is to interact with the CloudFormation API.\n\nCreate a new client:\n\n```ruby\nCfer::Cfn::Client.new(stack_name: \u003cstack_name\u003e)\n```\n\n`Cfer::Cfn::Client` also accepts options to be passed into the internal `Aws::CloudFormation::Client` constructor.\n\n#### `converge(stack)`\n\nCreates or updates the CloudFormation stack to match the input `stack` object. See below for how to create Cfer stack objects.\n\n```ruby\nclient.converge(\u003cstack\u003e)\n```\n\n#### `tail(options = {})`\n\nYields to the specified block for each CloudFormation event that qualifies given the specified options.\n\n```ruby\nclient.tail number: 1, follow: true do |event|\n  # Called for each CloudFormation event, as they occur, until the stack enters a COMPLETE or FAILED state.\nend\n```\n\n### Cfer Stacks\n\nA Cfer stack represents a baked CloudFormation template, which is ready to be converted to JSON.\n\nCreate a new stack:\n\n#### `stack_from_file`\n\n```ruby\nstack = Cfer::stack_from_file(\u003cfile\u003e, client: \u003cclient\u003e)\n```\n\n#### `stack_from_block`\n\n```ruby\nstack = Cfer::stack_from_block(client: \u003cclient\u003e) do\n  # Stack definition goes here\nend\n```\n\n## Contributing\n\nThis project uses [git-flow](http://nvie.com/posts/a-successful-git-branching-model/). Please name branches and pull requests according to that convention.\n\nAlways use `--no-ff` when merging into `develop` or `master`.\n\nThis project also contains a [Code of Conduct](https://github.com/seanedwards/cfer/blob/master/CODE_OF_CONDUCT.md), which should be followed when submitting feedback or contributions to this project.\n\n### New features\n\n* Branch from `develop`\n* Merge into `develop`\n* Name branch `feature/\u003cfeature-name\u003e`\n\n### Unreleased bugs\n\n* Branch from `develop`\n* Merge into `develop`\n* Name branch `bugfix/\u003cissue-id\u003e`\n\n### Bugfixes against releases\n\n* Branch from `master`\n* Merge into `develop` and `master`\n* Name branch `hotfix/\u003cissue-id\u003e`\n\n### Releases\n\n* Branch from `develop`\n* Merge into `develop` and `master`\n* Name branch `release/\u003cmajor.minor\u003e`\n\n# Release Notes\n\n[Change Log](https://github.com/seanedwards/cfer/blob/master/CHANGELOG.md)\n\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fseanedwards%2Fcfer","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fseanedwards%2Fcfer","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fseanedwards%2Fcfer/lists"}