cfn-stack
CLI for launching CloudFormation stacks using local parameter files
cfn-stack
is a simple CLI designed to join templates with YAML files that specify the stack name, template, and input parameters.
It is designed to work with stack files organized into a logical folder structure. A simple application might use the following stack configuration:
.
├── development
│ ├── _defaults.yml
│ ├── api.yml
│ └── web.yml
└── production
├── _defaults.yml
├── api.yml
└── web.yml
You'll point cfn-stack
to an individual stack configuration (e.g. production/api.yml
). A _defaults.yml
file can supply default parameters to every stack. These defaults are read recursively (up to the working directory) so you can apply defaults at multiple levels in the file tree.
Your stack file might look like this:
Template: api.ymlParameters: DnsName: api.web
The live stack that cfn-stack
creates will be named based on the file path. production/api.yml
is created as production-api
. This allows you to store stack configurations outside of AWS, under version control, while still retaining a clear relationship between your source files and CloudFormation.
Install
To use the CLI:
npm install --global cfn-stack
Or to use the API:
npm install --save cfn-stack
Usage
CLI
cfn-stack stacks/production/api.yml
API
var cfnStack = var stack = Name: 'my-stack' TemplateBody: fs Parameters: DnsName: 'api.web'
CLI
cfn-stack <stack>
Creates a live CloudFormation stack using the configuration specified in the stack
YAML file.
--stack-name
Type: string
A custom name to use for the stack. If omitted, a stack name will be generated using the stack file path.
cfn-stack stacks/production/api.yml --stack-name 'my-custom-name'
--load
Type: string
An expression that will be used to generate a shell command for loading/pre-processing the template. The token $0
will be replaced with the template path.
cfn-stack stacks/production/api.yml --load 'my-cfn-preprocessor $0'
--template-directory
Type: string
Default: templates/
Specifies the directory where template paths will be resolved.
--disable-rollback
Type: boolean
Default: false
Prevents CloudFormation from rolling back and deleting resources when stack creation fails. Does not apply to stack updates.
--region
Type: string
Default: us-east-1
The AWS region where the stack will be deployed.
API
cfnStack(stack, options, callback)
-> output
stack
Required
Type: object
A stack object defining the stack name, parameters, and template.
Name
Required
Type: string
The name that will be assigned to the stack.
Capabilities
Type: array
Default: []
An array of strings specifying stack capabilities.
Template
Required
Type: string
A JSON or YAML CloudFormation template string.
Parameters
Type: object
Default: undefined
The stack parameters expressed as an object of strings/numbers/arrays. All values will be coerced to strings (required by CloudFormation). Arrays will be converted to comma delimited lists.
options
region
Required
Type: string
The AWS region where the stack will be launched.
disableRollback
Type: boolean
Default: false
Disables rollback of stacks that cannot be created successfully.
update
Type: boolean
Default: false
Specifies that the stack already exists and should be updated instead of created. By default, the library will first try to create a stack and then update an existing one if it already exists.
License
MIT © Ben Drucker