forge

Forge

Forge is a simple tool which makes deploying CloudFormation stacks a bit easier in continuous delivery environments. In contrast to awscli, Forge provides a mechanism to create, update and delete CloudFormation stacks synchronously, while also providing output on the stack events, and an exit code reflecting the final state of the stack deployment.

Features

• Parameters and Tags defined as YAML/JSON files which contain a key-value object
• Lists in Parameter files will be collapsed into CommaDelimitedLists and passed into CloudFormation
• Only required parameters in a parameter file will be used, meaning you can share parameter files between stacks for common usage
• Automatic discovery and passthrough of CloudFormation capabilities (i.e. CAPABILITY_IAM and CAPABILITY_NAMED_IAM)
• Synchronous execution of actions against CloudFormation stacks
• Exit codes based on stack status
• Running stack event output on the command line
• Dynamically Create or Update stacks based on existing stack status
• Acceptance of "No updates to be performed." as a non-erroneous state
• Environment Variable Substitution in Parameter and Tag files
• YAML and JSON formatted stack policies
• Deploy using an assumed IAM role (often used to deploy stacks to other accounts)
  • Includes support for MFA specified on the command line or in ~/.aws/config
• Enable Termination Protection at deployment time
• Define multiple parameter files to merge/override parameters
• Override specific parameters on the command line

Available Parameters

To see what options are available to you, execute forge --help for the latest help applicable to your version of Forge

Getting Started

macOS

On macOS, just use Homebrew to install and you're done!

brew install nathandines/tap/forge

Other Platforms Download and Installation

Go to the latest release page on GitHub to download the latest stable version.

Next, move the downloaded binary to a directory which is on your path, and rename it to forge. On Unix systems, ~/bin or /usr/local/bin are good options depending on whether you want to restrict the install to just your user or install it system-wide. On Windows systems, a similar pattern is advised; %USERPROFILE%\bin for a single user, or %PROGRAMDATA%\bin for multiple users.

The final step to installation is to make sure the directory you installed Forge to is on the PATH. See this page for instructions on setting the PATH on Linux and Mac. This page contains instructions for setting the PATH on Windows.

Adding bash or zsh completion (optional)

Forge has the capability to generate shell completion for bash and zsh. Run one of the following commands (adjusting the destination for the output file as required for your machine) to enable shell completion for Forge on your system.

If you're not sure which shell you use, you probably use bash.

forge gen-bash-completion > /etc/bash_completion.d/forge
# or
forge gen-zsh-completion > ~/.zsh_completions.d/forge

Using Environment Variables in Parameter or Tag files

Environment variables can be referenced within parameter and tag files by using the following format: '{{ env `variable_name` }}' (the backticks MUST surround the variable name). This is because under the covers, Forge uses the Golang text templating engine, with an additional function (env) to assist with environment variable references.

YAML Note: The curly braces must be quoted when using YAML to ensure that the field is interpreted as a string

Example

---
Environment: '{{ env `ENVIRONMENT` }}'
Owner Email: '{{ env `USER` }}@example.com'

Example: Deploying a stack with tags and parameters

Requirements

• Forge installed on your machine and available in your PATH
• AWS Account with permissions to create a DHCP Option Set through CloudFormation

Setting up your environment

Start in an empty folder. Create the following files which will cover your tags, parameters, and CloudFormation template.

---
Tag One: This is an example tag
CostAllocationTag: Cost Center

---
DomainName: example.com
DNSServers:
  - 10.0.0.1
  - 10.0.0.2
  - 10.0.0.3
  - 10.0.0.4
UnrelatedParameter: This Will Not Be Used

---
DomainName: foobar.com

---
Parameters:
  DomainName:
    Type: String
  DNSServers:
    Type: CommaDelimitedList

Resources:
  DHCPOptions:
    Type: AWS::EC2::DHCPOptions
    Properties:
      DomainName: !Ref DomainName
      DomainNameServers: !Ref DNSServers

Deploying the example stack

Firstly, authenticate your CLI environment to AWS. Forge uses environment variables to authenticate to AWS services. You could choose to use a tool such as awskeyring to setup your environment, or reference an awscli profile using AWS_DEFAULT_PROFILE.

Once you're authenticated to the AWS services, you can now deploy your stack

forge deploy --stack-name test-stack \
  --template-file ./cfn_template.yml \
  --tags-file ./tags.yml \
  --parameters-file ./parameters1.yml \
  --parameters-file ./parameters2.yml

During deployment, you'll see event output of the creation of the stack. After deployment, upon logging into your AWS account, you should be able to see a new DHCP option set which has been deployed with the tags and parameters defined above.

Development

Get Dependencies

make deps

Build

make build

Test

make test

Linting

make lint

Clean workspace

make clean

Change AWS Service Endpoints

You can currently change the service endpoints for both CloudFormation and STS by setting the following environment variables when running Forge:

• AWS_ENDPOINT_CLOUDFORMATION
• AWS_ENDPOINT_IAM
• AWS_ENDPOINT_STS