stackit
stackit is a CLI tool to synchronously and idempotently operate on AWS
CloudFormation stacks - a perfect complement for continuous integration systems
and developers who prefer the comfort of the command line.
Where
The latest compiled stackit binaries for Linux, macOS and Windows can be
downloaded from the project's GitHub Releases
page.
Why
CloudFormation is inherently asychronous and this is reflected in the usage
of the AWS CLI tools - a create-stack or update-stack operation exits long
before the stack has reached its final state. stackit treats a stack update
synchronously, streaming stack events to the CLI until the stack reaches a
steady state.
AWS CLI commands for CloudFormation aren't idempotent. If you call create-stack
when a stack already exists, the behaviour is different to if it doesn't.
Likewise with update-stack. This means you either have to manually create a
stack before putting it under CI, or script up a "does it exist yet?" check
before deciding which command to invoke. stackit abstracts over these with
an up facade.
How
up
stackit up --stack-name some-other-name # use this stack name, fallback to yml for rest
stackit up \
--stack-name some-other-name \
--template sample.yml \
--param-value DockerImage=redis \
--param-value Cluster=some-ecs-cluster # no yml necessary
Note that there is JSON printed at the end of the up command. This is all the
Outputs defined in your CloudFormation template file. These are printed to
stdout. The event lines above them are printed to stderr.
This separation makes it easy to pipe output from stackit up to another
command without having to skip the log lines. Likewise, a non-zero exit code
indicates stack update/creation failure.
outputs
stackit outputs --stack-name <name> prints the stack's Outputs in JSON form,
without making any modifications to the stack.
tail
If an existing stack creation or update is in progress, stackit tail --stack-name <name>
will poll for events, similar to the up command.
down
stackit down --stack-name <name> will delete the named stack if it exists,
otherwise it will do nothing. Non-zero exit code indicates failure to delete
an existing stack.
More
All commands can be passed a --profile <name> parameter. This will use alternative
AWS credentials defined in a profile named in ~/.aws/config if it exists. If your
profile requires MFA credentials in order to assume a role, stackit will prompt
for those to be entered on stdin.
All commands can be passed a --region <region> parameter if you want to deploy
your stack in a different region.
TODO
stackit <stack-name> cancelstackit <stack-name> signal <logical-name>
Additional Flags
TODO: Document these properly
--service-role VAL--previous-param-value NAME--tag NAME=VAL(multiple)--notification-arn(multiple)--stack-policy VAL--previous-template--no-cancel-on-exit--no-destroy(not yet implemented)
for changes: (not yet implemented)
--name VAL--execute-if-no-destroy
Notes
- Change-sets return special exit code to indicate destructive (replacement, deletion) actions
- MFA support