README
Slapstack
Deploy parameterized AWS CloudFormation Stacks
Slapstack deploys AWS CloudFormation templates quickly, safely, and with multiple configurations.
Quickly: a simple command line makes it easy to remember the command:
npx slapstack stack.yml commit
Safely: plugins ensure all your work is committed, your Docker images are pushed, and Slack is notified.
Multiple configurations: "stack files" provide different parameters to your CloudFormation templates, and can import common settings.
Requirements
Installation
npm install --save-dev slapstack
Stack Files
Slapstack uses a configuration file called a "stack file" to provide the necessary parameters to deploy a CloudFormation template. Stack files can be written in either YAML or JSON. In this documentation we'll use YAML.
Example
Let's say you have a CloudFormation template to deploy an S3 bucket named
data-bucket.yml
with the following contents:
Parameters:
EnvironmentParameter:
Type: String
Resources:
DataBucket:
Type: AWS::S3::Bucket
Properties:
BucketName: !Sub "data-bucket-${EnvironmentParameter}"
If you wanted to deploy the same CloudFormation templates to two different
environments, you might create a data-bucket-development.yml
stack file with
these contents:
parameters:
EnvironmentParameter: development
stackName: data-bucket-development
template: data-bucket.yml
and a data-bucket-production.yml
stack file with these contents:
parameters:
EnvironmentParameter: production
stackName: data-bucket-production
template: data-bucket.yml
With these stack files you could run npx slapstack data-bucket-development.yml commit
to deploy the development version of your S3 bucket.
stackName
The stackName
key holds a string value that is the name of this stack in
CloudFormation.
stackPolicy
The stackPolicy
key holds a string which is a path of a file containing CloudFormation stack
policy file. Stack policies are a good way to prevent a stack update from
accidentally deleting your database.
template
The template
key holds a string value that is the path name to the
CloudFormation template file for this stack. The path is relative to the stack
file.
parameters
The parameters
key holds a key/value object of any parameters you want to pass
to your CloudFormation template.
imports
The imports
key holds an array of string values that is a list of paths of
files to merge into the current stack file before deployment. You could use this
to store common settings for each environment, or to store secrets in a separate
file that's ignored from version control.
Let's extract the production environment parameters into a production.yml
file
with these contents:
parameters:
EnvironmentParameter: production
Then we can modify the data-bucket-production.yaml
stack file to import our
new file like this:
imports:
- production.yml
stackName: data-bucket-production
template: data-bucket.yml
awsCliProfile
The awsCliProfile
key holds a string value that is the aws-cli profile name
to use when deploying this stack file. The default is "default". This allows you
to use different AWS credentials and accounts for each stack.
awsEcr
The awsEcr
key holds a key/value object that holds information for checking
that docker images are pushed to AWS ECR.
Specifying awsEcr
will cause Slapstack to ensure that a tag named the same
as the commit
from the slapstack invocation exists in the named repository. If
the tag does not exist, the deployment will fail.
awsEcr:
parameter: ImageParameter
profile: my_aws_cli_profile_name
region: us-east-1
repository: 000000000000.dkr.ecr.us-east-1.amazonaws.com/organization/repository
capabilities
The capabilities
key holds a list of capabilities to send to CloudFormation
when processing your template. See the CreateStack
documentation.
A common example would be including CAPABILITY_IAM when your template contains
an IAM resource.
dockerHub
The dockerHub
key holds a key/value object that holds information for checking
that docker images are pushed to Docker Hub.
Specifying dockerHub
will cause Slapstack to ensure that a tag named the same
as the commit
from the slapstack invocation exists in the named repository. If
the tag does not exist, the deployment will fail.
dockerHub:
repository: organization/repository
username: username
password: password
parameter: ImageParameter
The repository
sub-key represents a repository on Docker Hub and should be in the form of
organization/repository
. The username
sub-key is the name of a Docker Hub
user. The password
sub-key is the password for the user named in username
.
The parameter
sub-key is the name of a parameter that will be passed to your
CloudFormation template containing the full name of the docker image to deploy
in the form of organization/repository:tag
.
lambda
The lambda
key holds a key/value object of settings for uploading a code
package for AWS Lambda.
lambda:
folder: lambdas
bucket: my-lambda-bucket
parameter: CodeUriKeyParameter
The folder
sub-key is a path to a folder to zip and upload to S3. The bucket
sub-key is the name of a bucket where the zip file should be uploaded. The
parameter
sub-key is the name of a parameter that will be passed to your
CloudFormation template containing the URI to the zip file on S3.
slack
The slack
key holds a key/value object that holds information for sending a
message to a Slack channel when a deployment is started.
slack:
webhookUrl: https://hooks.slack.com/services/...
channel: my-channel