@jcoreio/cloudformation-tools
API
deployCloudFormationStack(options)deployCloudFormationStacks(options)describeCloudFormationFailure(options)getStackOutputs(options)getStackResources(options)getCurrentStackEvents(options)watchStackResources(options)printStackResources(options)
deployCloudFormationStack(options)
import { deployCloudFormationStack } from '@jcoreio/cloudformation-tools'Deploys a stack. Code is adapted from aws-cli's
deploy command. However, it can display stack resources
as they are getting created/updated
(if you set watchResources: true), and if the update
fails, it will log the failure events.
options object
awsConfig (ConfigurationOptions, optional)
General AWS service configuration options like region and credentials
cloudformation (AWS.CloudFormation, optional)
An AWS.CloudFormation instance. Will create one with the default options if you don't provide one
watchResources (boolean, optional)
If truthy, will watch and print out resource status while the stack create/update is in progress
watcher (StackResourceWatcher, optional)
Alternative to watchResources. If given, will watch and print out resource status while the stack create/update is in progress.
region (string, optional)
Destination AWS region for CloudFormation stack
approve (boolean, optional)
If true, lists changes and prompts for approval before deploying. Defaults to false.
StackName (string, required)
The name or the unique ID of the stack for which you are creating a change set. AWS CloudFormation generates the change set by comparing this stack's information with the information that you submit, such as a modified template or different parameter input values.
TemplateFile (string, optional)
The path to the file containing the CloudFormation template. You must specify either TemplateFile or
TemplateBody.
TemplateBody (string, optional)
A structure that contains the body of the revised template, with a minimum length of 1 byte and a maximum length of 51,200 bytes. AWS CloudFormation generates the change set by comparing this template with the template of the stack that you specified.
Parameters ({[string]: any} | Array<{ParameterKey: string, ParameterValue: string, UsePreviousValue?: boolean, ResolvedValue?: string}>, optional)
A list of Parameter structures that specify input parameters for the change set.
Capabilities (Array<string>, optional)
In some cases, you must explicity acknowledge that your stack template contains certain capabilities in order for AWS CloudFormation to create the stack.
RoleARN (string, optional)
The Amazon Resource Name (ARN) of an AWS Identity and Access Management (IAM) role that AWS CloudFormation assumes when executing the change set. AWS CloudFormation uses the role's credentials to make calls on your behalf. AWS CloudFormation uses this role for all future operations on the stack. As long as users have permission to operate on the stack, AWS CloudFormation uses this role even if the users don't have permission to pass it. Ensure that the role grants least privilege.
If you don't specify a value, AWS CloudFormation uses the role that was previously associated with the stack. If no role is available, AWS CloudFormation uses a temporary session that is generated from your user credentials.
NotificationARNs (Array<string>, optional)
The Amazon Resource Names (ARNs) of Amazon Simple Notification Service (Amazon SNS) topics that AWS CloudFormation associates with the stack. To remove all associated notification topics, specify an empty list.
Tags ({[string]: any} | Array<{Key: string, Value: string}, optional)
Key-value pairs to associate with this stack. AWS CloudFormation also propagates these tags to resources in the stack. You can specify a maximum of 50 tags.
s3 ({ Bucket: string, prefix?: ?string, SSEKMSKeyId?: ?string, forceUpload?: ?boolean }, optional)
If given, will upload the template body the given S3 bucket.
readOutputs (boolean, optional)
If true, stack outputs will be read and returned in the Outputs property. Defaults to false.
replaceIfCreateFailed (boolean, optional)
If true, will replace an existing stack of the same name if it's in CREATE_FAILED, ROLLBACK_FAILED,
ROLLBACK_COMPLETE or ROLLBACK_IN_PROGRESS state (note that these only refer to rollback after
create failure, and are distinct from the UPDATE_ROLLBACK_... states)
signalWatchable (() => mixed, optional)
If given, this function will be called once the stack create/update is ready to be watched.
Returns
A Promise that resolves or rejects when the deployment succeeds or fails
deployCloudFormationStacks(options)
import { deployCloudFormationStacks } from '@jcoreio/cloudformation-tools'Deploys multiple stacks in parallel.
options object
awsConfig (ConfigurationOptions, optional)
General AWS service configuration options like region and credentials
stacks (Array, required)
An array of arguments for deployCloudFormationStack, without the other options below or the approve option.
cloudformation (AWS.CloudFormation, optional)
An AWS.CloudFormation instance. Will create one with the default options if you don't provide one
watchResources (boolean, optional)
If truthy, will watch and print out resource status while the stacks are being created or updated.
s3 ({ Bucket: string, prefix?: ?string, SSEKMSKeyId?: ?string, forceUpload?: ?boolean }, optional)
If given, will upload the template bodies the given S3 bucket.
Returns
A Promise that will resolve after all stacks are deployed successfully, or reject immediately when any stack
deployment fails. If one stack deployment fails, the other deployments will not be canceled.
describeCloudFormationFailure(options)
import { describeCloudFormationFailure } from '@jcoreio/cloudformation-tools'Scans stack events for failures and prints them out with nice formatting, to help you debug.
options object
awsConfig (ConfigurationOptions, optional)
General AWS service configuration options like region and credentials
cloudformation (AWS.CloudFormation, optional)
An AWS.CloudFormation instance. Will create one with the default options if you don't provide one
StackName (string, required)
The name or unique id of a stack to describe failures for
stream (Writable, optional)
The writable stream to output to. Defaults to process.stderr.
Returns
A Promise that resolves when done logging, or rejects
if it failed to get stack events
getStackOutputs(options)
import { getStackOutputs } from '@jcoreio/cloudformation-tools'Gets a stack's outputs as an object
instead of an array of {OutputKey, OutputValue} objects.
options object
awsConfig (ConfigurationOptions, optional)
General AWS service configuration options like region and credentials
cloudformation (AWS.CloudFormation, optional)
An AWS.CloudFormation instance. Will create one with the default options if you don't provide one
StackName (string, required)
The name or unique id of a stack to get outputs of
Returns
A Promise that resolves to an {[OutputKey]: OutputValue} object, or rejects if it failed to get
the outputs.
getStackResources(options)
import { getStackOutputs } from '@jcoreio/cloudformation-tools'Gets all of a stack's resources, handling the paging for you.
options object
cloudformation (AWS.CloudFormation, optional)
An AWS.CloudFormation instance. Will create one with the default options if you don't provide one
StackName (string, required)
The name or unique id of a stack to get resources of
Returns
A Promise that resolves to array of stack resources,
or rejects if it failed ot get the resources.
getCurrentStackEvents(options)
import { getCurrentStackEvents } from '@jcoreio/cloudformation-tools'Gets all of the events from the most recent changeset, handling paging for you.
options object
awsConfig (ConfigurationOptions, optional)
General AWS service configuration options like region and credentials
cloudformation (AWS.CloudFormation, optional)
An AWS.CloudFormation instance. Will create one with the default options if you don't provide one
StackName (string, required)
The name or unique id of a stack to get events of
Returns
A AsyncIterable that yields stack events.
watchStackResources(options)
options object
Prints out one or more stacks' resources and their status in a table every 5 seconds, or on an interval you specify.
cloudformation (AWS.CloudFormation, optional)
An AWS.CloudFormation instance. Will create one with the default options if you don't provide one
StackName (string, StackName or StackNames is required)
The name or unique id of a stack to watch
StackNames (Array<string>, StackName or StackNames is required)
The names or unique ids of stacks to watch
delay (number, optional)
The interval delay in milliseconds
whilePending (`Promise, optional)
If given, the interval will be cleared once this promise resolves or rejects.
Returns
The interval ID from setInterval.
printStackResources(options)
Prints the given resources and their status in a table.
options object
resources (Array<Resource>, required)
The resources to print out
stream (Writable, optional)
The stream to print to. Defaults to process.stderr.
upsertSecurityGroup(options)
Ensures that a security group with the specified name exists in the VPC, creating it if needed.
options object
awsConfig (ConfigurationOptions, optional)
General AWS service configuration options like region and credentials
securityGroupName (string, required)
Name of the security group
securityGroupDescription (string, optional)
Description to use when creating the security group
vpcId (string, required)
ID of the VPC. Required because security groups exist within a VPC.
ec2 (AWS.EC2, conditional)
Optional EC2 class instance to use for API calls. If no EC2 class instance
is provided, one will be created using the region property. Either
ec2 or region must be provided.
region (string, conditional)
AWS region. Either ec2 or region must be provided.
Returns
A Promise that resolves to a {securityGroupId} object, or rejects if it failed to
ensure the security group exists.
getVPCIdBySubnetId(options)
Fetches and returns the ID of the VPC where the specified subnet is located.
options object
awsConfig (ConfigurationOptions, optional)
General AWS service configuration options like region and credentials
subnetId (string, required)
ID of the subnet
ec2 (AWS.EC2, conditional)
Optional EC2 class instance to use for API calls. If no EC2 class instance
is provided, one will be created using the region property. Either
ec2 or region must be provided.
region (string, conditional)
AWS region. Either ec2 or region must be provided.
Returns
A Promise that resolves to a string with the ID of the VPC
getCIDRByVPCId(options)
Fetches and returns the CIDR block IP address range of the specified VPC.
options object
awsConfig (ConfigurationOptions, optional)
General AWS service configuration options like region and credentials
vpcId (string, required)
ID of the VPC
ec2 (AWS.EC2, conditional)
Optional EC2 class instance to use for API calls. If no EC2 class instance
is provided, one will be created using the region property. Either
ec2 or region must be provided.
region (string, conditional)
AWS region. Either ec2 or region must be provided.
Returns
A Promise that resolves to a string with the IP address range of the VPC