awsteele/stackup repository overview

⁠stackup

Stackup provides a CLI and a simplified Ruby API for dealing with AWS CloudFormation stacks.

• Why?⁠
• Installation⁠
• Command-line usage⁠
  • Stack create/update⁠
  • Specifying parameters⁠
  • YAML support⁠
  • AWS credentials⁠
  • Using URLs as inputs⁠
  • Stack deletion⁠
  • Stack inspection⁠
• Programmatic usage⁠
• Rake integration⁠
• Docker image⁠

⁠Why?

Stackup provides some advantages over using awscli or aws-sdk directly:

• It treats stack changes as synchronous, streaming stack events until the stack reaches a stable state.

• A Stack#up facade for create/update frees you from having to know whether your stack already exists or not.

• Changes are (mostly) idempotent: "no-op" operations - e.g. deleting a stack that doesn't exist, or updating without a template change - are handled gracefully (i.e. without error).

⁠Installation

$ gem install stackup

⁠Command-line usage

The entry-point is the "stackup" command.

Most commands operate in the context of a named stack:

$ stackup STACK-NAME ...

Called with --list, it will list stacks:

$ stackup --list
foo-bar-test
zzz-production

⁠Stack create/update

Use sub-command "up" to create or update a stack, as appropriate:

$ stackup myapp-test up -t template.json

This will:

• update (or create) the named CloudFormation stack, using the specified template
• monitor events until the stack update is complete

For more details on usage, see

$ stackup STACK up --help

⁠Specifying parameters

Stack parameters can be be read from a file, e.g.

$ stackup myapp-test up -t template.json -p parameters.json

Parameters can be specified as simple key-value pairs:

{
  "IndexDoc": "index.html"
}

but also supports the extended JSON format used by the AWS CLI⁠:

[
  {
    "ParameterKey": "IndexDoc",
    "ParameterValue": "index.html",
    "UsePreviousValue": false
  }
]

You may specify -p multiple times; stackup will read and merge all the files:

$ stackup myapp-test up -t template.json \
  -p defaults.json \
  -p overrides.json

Or, you can specify parameters on the command-line, via -o:

$ stackup myapp-test up -t template.json \
  -o IndexDoc=index.html

⁠YAML support

stackup supports input files (template, parameters, tags) in YAML format, as well as JSON.

It also supports the abbreviated YAML syntax for Cloudformation functions⁠, though unlike the AWS CLI⁠, Stackup normalises YAML input to JSON before invoking CloudFormation APIs.

⁠AWS credentials

The stackup command-line looks for AWS credentials in the standard environment variables⁠.

You can also use the --with-role option to temporarily assume a different IAM role, for stack operations:

$ stackup myapp-test up -t template.json \
  --with-role arn:aws:iam::862905684840:role/deployment

⁠Using URLs as inputs

You can use either local files, or HTTP URLs, to specify inputs; stack template, parameters, etc.

$ stackup mystack up \
  -t https://s3.amazonaws.com/mybucket/stack-template.json

Where a template URL references an object in S3, stackup leverages CloudFormation's native support⁠ for such URLs, enabling use of much larger templates.

Non-S3 URLs are also supported, though in that case stackup must fetch the content itself:

$ stackup mystack up \
  -t https://raw.githubusercontent.com/realestate-com-au/stackup/master/examples/template.yml

⁠Stack deletion

Sub-command "delete" deletes the stack.

⁠Stack inspection

Inspect details of a stack with:

$ stackup myapp-test status
$ stackup myapp-test resources
$ stackup myapp-test outputs

⁠Programmatic usage

Get a handle to a Stack object as follows:

stack = Stackup.stack("my-stack")

You can pass an Aws::CloudFormation::Client, or client config, to Stackup, e.g.

stack = Stackup(credentials).stack("my-stack")

See {Stackup::Stack} for more details.

⁠Rake integration

Stackup integrates with Rake to generate handy tasks for managing a stack, e.g.

require "stackup/rake_tasks"

Stackup::RakeTasks.new("app") do |t|
  t.stack = "my-app"
  t.template = "app-template.json"
end

providing tasks:

rake app:diff       # Show pending changes to my-app stack
rake app:down       # Delete my-app stack
rake app:inspect    # Show my-app stack outputs and resources
rake app:up         # Update my-app stack

Parameters and tags may be specified via files, or as a Hash, e.g.

Stackup::RakeTasks.new("app") do |t|
  t.stack = "my-app"
  t.template = "app-template.json"
  t.parameters = "production-params.json"
  t.tags = { "environment" => "production" }
end

⁠Docker image

Stackup is also published as a Docker image. Basic usage is:

docker run --rm \
    -v `pwd`:/cwd \
    -e AWS_ACCESS_KEY_ID -e AWS_SECRET_ACCESS_KEY -e AWS_SESSION_TOKEN \
    -e AWS_DEFAULT_REGION \
    realestate/stackup:latest ...

If you're sensible, you'll replace "latest", with a specific version⁠.

The default working-directory within the container is /cwd; hence the volume mount to make files available from the host system.