Cloudformation Nested
A promise based library for packaging and deploying nested cloudformation stacks. Currently the aws SDK does not support nested stacks. This implementation is a thin wrapper over the AWS cli to provide native javascript support for nested cloudformation stacks.
Prerequisites
This library assumes that AWS cli is installed and configured. It can be installed following the instruction here.
to configure create an AWS user with sufficient permissions for your stack/s and configure the cli with...
aws configure
Getting Started
To install...
npm i cfn-nested
To create a class instance...
import CfnNested from 'cfn-nested';
// Or
const cfnNested = require('cfn-nested').default;
// This will instantiate the class and tie it to the bucket, template and stack name given as parameters. If the bucket does not exist it is created when package is called on the class.
const cfnNested = new CfnNested('cloudformation-bucket', './path/to/template/template.yml', 'MyStackName');
Packaging creates a deploy-able template pointing to templates in the s3 bucket provided on instantiation. The template is created in the file system on the relative path ./packaged/
let templateLocation;
templateLocation = await cfnNested.package();
// Or
cfnNested.package()
.then((result, error) => {
if (error) throw error;
templateLoctaion = result;
console.log('Packaged Template:', result);
});
Once packaged your stack can be deployed...
const stackDescription = await cfnNested.deploy();
// Or
cfnNested.deploy()
.then((result, error) => {
if (error) throw error;
console.log('Deployment Status', result.StackResources[0].ResourceStatus); //CREATE_COMPLETE
});
Example
A complete example is provided in the example folder. To run the example you can run the following commands from the example folder...
npm install
npm start
API
Constructor
Constructs a new instance of CfnNested.
constructor(bucketName: string, templateFilename: string, stackName: string, silent = false: bool)
Parameters
bucketName: Nested cloudformation templates are packaged into intermediate templates that must be stored in a bucket. This is the bucket name to use. The bucket does not need to exist prior to class instantiation. If the bucket does not exist it will be created on the the call of package.
templateFilename: The location of the base cloudformation template to use for this nested stack.
stackName: This is the name of the stack used when deploying or updating the stack.
silent(optional): If true console output is omitted.
Returns
CfnNested: The instance to operate on for this stack.
Package
Packages the stack.
package()
Returns
string: The location of the packaged cloudformation template
deploy
Deploys the stack.
deploy(parameters: object)
Parameters
parameters An object of key value pairs to be passed as parameters to the cloudformation template.
Returns
object: The JSON parsed output form the describe-stack aws cli command for the stack on completion of the stack creation.
delete
Deletes the nested stack
delete()
Returns
undefined:
stackExists
Checks for existence of the stack
stackExists()
Returns
bool: true if a stack with the given stack name exists in the configured AWS account.
bucketExists
bucketExists()
Returns
bool: true if the bucket already exists
describeStack
Describes the current state of the stack
describeStack()
Returns
object: The JSON parsed output form the describe-stack aws cli command against the stack name provided on instantiation.
deleteBucket
Deletes the configured bucket.
deleteBucket()
Returns
undefined:
createBucketIfNotExists
Creates the configured bucket. Note. This is called as part of package if the bucket does not already exist.
createBucketIfNotExists()
Returns
undefined:
Test
The tests are contained in the test directory. They are full end to end integration tests and require the AWS cli to be configured with an account to be run. Once the cli is configured the tests can be run using the command...
npm test