cfn-create-or-update

When integrating CloudFormation into your CI/CD pipeline you are faced with the challenge of creating a CloudFormation stack on the first run of the pipeline, while you need to update the stack for all following pipeline runs. If you use the AWS CLI this is painful. You may also have your code and template in the same repository. Therefore code changes without the template. But the AWS CLI threats an update without changes to a stack as an error which is not the behavior that you need in your pipeline.

cfn-create-or-update can create or update a CloudFormation stack. If no updates are to be performed, no error is thrown. cfn-create-or-update behaves exactly as the AWS CLI regarding input values, output will be different.

Installation

To install the CLI tool cfn-create-or-update, run:

npm install -g cfn-create-or-update

To create or update a stack, run:

cfn-create-or-update --stack-name test --template-body file://template.yml

The first time you run this command, a stack will be created. The second time an update will be performed but only if the template has changes.

CLI parameters

cfn-create-or-update behaves exactly as the AWS CLI regarding input values. Supported parameters (as documented in the AWS CLI create-stack or update-stack):

cfn-create-or-update
--stack-name
--template-body
--template-url
--parameters
--capabilities 
--resource-types
--role-arn
--stack-policy-body
--stack-policy-url
--notification-arns
--tags

Global parameters (as documented in the AWS CLI

--profile
--region

If you use a parameter of type List<?> or CommaDelimitedList, you have to supply the values like this:

--parameters ParameterKey=SubnetIds,ParameterValue=\"subnet-3353611c,subnet-c3d51189\"

Only used during create, otherwise ignored (as documented in the AWS CLI create-stack):

--disable-rollback | --no-disable-rollback
--timeout-in-minutes
--on-failure

Only used during update, otherwise ignored (as documented in the AWS CLI update-stack):

--use-previous-template | --no-use-previous-template]
--stack-policy-during-update-body
--stack-policy-during-update-url

Additional parameters

--wait

Environment variables

• both AWS_REGION and AWS_DEFAULT_REGION work
• HTTPS_PROXY is used if set
• AWS_PROFILE is used if set
• AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY, and optionally AWS_SESSION_TOKEN are used of set

Multi-Factor Authentication

If your AWS CLI profile has a mfa_serial property, then multi-factor authentication is required. You will be prompted to enter your 6-digit MFA token code via the console.

$ cfn-create-or-update --profile admin-role --stack-name mystack --template-body file://mystack.yml
? MFA token for arn:aws:iam::000000000000:mfa/myusername: 123456
{}

Contribution

If you want to create a Pull-Request please make sure that make test runs without failures.

Code Style

make jshint

Unit Tests

make mocha

Circular depdendencies

make circular

Test coverage

make coverage
open coverage/lcov-report/index.html