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