grunt-aws-cloudformation v0.1.3
grunt-aws-cloudformation
A grunt task to perform AWS CloudFormation operations.
Installation
This is a task for the Grunt tool, if you are not familiar please start with the Getting Started guide to learn the basics for creating your Gruntfile and how to use Grunt plugins.
To add the CloudFormation task to your project, first install the plug-in to your project with the command:
$ npm install grunt-aws-cloudformation --save-devand then add the following line to your Gruntfile:
grunt.loadNpmTasks('grunt-aws-cloudformation');Overview
This plugin contains a single task called cloudformation. It can be used to perform the following actions:
- create-stack - Creates a new CloudFormation stack
- update-stack - Updates an existing CloudFormation stack
- delete-stack - Deletes an existing CloudFormation stack
- describe-stack - Describes an existing CloudFormation stack's status
Example
'use strict';
module.exports = function(grunt) {
grunt.loadNpmTasks('grunt-aws-cloudformation');
grunt.initConfig({
cloudformation: {
options: {
region: 'us-west-2',
accessKeyId: "AAAAAAAAAAAAAAAAA",
secretAccessKey: "XxXxXxXxXxXxXxXxXxXxXxXxXx"
},
createMyStack: {
action: "create-stack",
stackName: "my-stack",
params: {
SomeParameter: "Foo"
},
deleteIfExists: true,
src: ['templates/MyStack.template']
},
deleteMyStack: {
action: "delete-stack",
stackName: "my-stack"
}
}
});
grunt.registerTask("default", ["cloudformation:createMyStack"]);
};In this example, you could use the command grunt (or grunt cloudformation:createMyStack) to create the stack,
and the command grunt cloudformation:deleteMyStack would delete it. For more examples, see the tests defined in
this project's Gruntfile.js.
Authentication options
All CloudFormation actions can authenticate using either environment variables,
arguments specifying an access key/secret pair, a session token, or a saved configuration
profile (in ~/.aws/credentials).
options.accessKeyId
Type: String
Default value: the current value of the environment variable AWS_ACCESS_KEY_ID, if present
The AWS access key id credential to use for authentication.
options.secretAccessKey
Type: String
Default value: the current value of the environment variable AWS_SECRET_ACCESS_KEY, if present
The AWS secret access key credential to use for authentication.
options.sessionToken
Type: String
Default value: the current value of the environment variable AWS_SESSION_TOKEN, if present
The AWS session token to use for authentication.
options.profile
Type: String
The profile in the ~/.aws/credentials saved credentials to use.
Common options
The following options are shared by all CloudFormation actions.
options.region
Type: String
Required
The AWS region where the stack either already exists or will be created.
options.action
Type: String
Required
The action to perform, which must be one of:
- create-stack
- update-stack
- delete-stack
- describe-stack
Using the create-stack action
Use the create-stack action to create a new CloudFormation stack.
options.stackName
Type: String
Required
The name of the CloudFormation stack to be created.
options.templateBody
Type: String
The body of the template to be used to create the stack. This can also be specified as a src file in standard Grunt format. You must specify either a templateBody (or src file) or templateUrl parameter
options.templateUrl
Type: String
The URL to the template (e.g. on AWS S3) to be used to create the stack.
options.trackStatus
Type: Boolean
Default: true
When true, the grunt task will track the progress of the create action until it completes or fails,
displaying progress dots (or detailed information in --verbose mode). When false, the task
simply initiates the create stack process, in which case the Grunt task will
complete before the stack is created.
options.trackPollingPeriod
Type: Number
Default: 1000
When trackStatus is true, this option defines the polling period (in ms) used to update the status from AWS. This defaults to 1000ms (1 second).
options.outputKey
Type: String
If set, the grunt task will read all Output parameters after the creation of the stack, and append them to the
outputKey in the Grunt config, where a subsequent task could pick them up if desired. For example, if outputKey
is set to myTask.options, and there is an Output of foo, then it's value would be set (via grunt.config.set)
to the key myTask.options.foo. Note that trackStatus must also be set to true (its default), otherwise the
Grunt task will not wait for the template to be created and therefore won't get the Outputs.
options.params
Type: Object
An object specifying parameter values for the template.
options.capabilities
Type: String array
A list of values that you must specify before AWS CloudFormation can update certain stacks. Some stack templates might include resources that can affect permissions in your AWS account, for example, by creating new AWS Identity and Access Management (IAM) users. For those stacks, you must explicitly acknowledge their capabilities by specifying this parameter. The only valid values are CAPABILITY_IAM and CAPABILITY_NAMED_IAM.
Other create-stack options
The following parameters can be specified and are treated exactly as in the documentation for the createStack function
described in the AWS CloudFormation SDK's createStack function
options.disableRollback
options.onFailure
options.notificationARNs
options.resourceTypes
options.roleARN
options.stackPolicyBody
options.stackPolicyURL
options.tags
options.timeoutInMinutes
Using the update-stack action
Use the update-stack action to update an existing CloudFormation stack. You must specify either a templateBody (or src file)
or templateUrl parameter, or the usePreviousTemplate=true parameter.
options.stackName
Type: String
Required
The name of the CloudFormation stack to be updated.
options.templateBody
Type: String
The body of the template to be used to update the stack. This can also be specified as a src file in standard Grunt format.
options.templateUrl
Type: String
The URL to the template (e.g. on AWS S3) to be used to update the stack.
options.usePreviousTemplate
Type: Boolean
The body of the template to be used to create the stack. This can also be specified as a src file in standard Grunt format.
options.trackStatus
Type: Boolean
Default: true
When true, the grunt task will track the progress of the update action until it completes or fails,
displaying progress dots (or detailed information in --verbose mode). When false, the task
simply initiates the update stack process, in which case the Grunt task will complete before the stack is updated.
options.outputKey
Type: String
If set, the grunt task will read all Output parameters after the update of the stack, and append them to the
outputKey in the Grunt config, where a subsequent task could pick them up if desired. For example, if outputKey
is set to myTask.options, and there is an Output of foo, then it's value would be set (via grunt.config.set)
to the key myTask.options.foo. Note that trackStatus must also be set to true (its default), otherwise the
Grunt task will not wait for the template to be updated and therefore won't get the Outputs.
options.params
Type: Object
An object specifying parameter values for the template. Pass a string value to specify a new value, or pass the boolean
value true to use the previous value.
options.capabilities
Type: String array
A list of values that you must specify before AWS CloudFormation can update certain stacks. Some stack templates might include resources that can affect permissions in your AWS account, for example, by creating new AWS Identity and Access Management (IAM) users. For those stacks, you must explicitly acknowledge their capabilities by specifying this parameter. The only valid values are CAPABILITY_IAM and CAPABILITY_NAMED_IAM.
Other update-stack options
The following parameters can be specified and are treated exactly as in the documentation for the updateStack function
described in the AWS CloudFormation SDK's updateStack function
options.notificationARNs
options.resourceTypes
options.roleARN
options.stackPolicyBody
options.stackPolicyURL
options.tags
Using the delete-stack action
Use the delete-stack action to delete an existing CloudFormation stack.
options.stackName
Type: String
Required
The name of the CloudFormation stack to be deleted.
options.trackStatus
Type: Boolean
Default: true
When true, the grunt task will track the progress of the delete action until it completes or fails,
displaying progress dots (or detailed information in --verbose mode). When false, the task
simply initiates the delete stack process, in which case the Grunt task will complete before the stack is deleted.
Other delete-stack options
The following parameters can be specified and are treated exactly as in the documentation for the deleteStack function
described in the AWS CloudFormation SDK's deleteStack function
options.retainResources
options.roleARN
Using the describe-stack action
Use the describe-stack action to get the current status information about your stack and read Output values. Using
the --verbose flag will also print out all underlying stack information.
options.stackName
Type: String
The name of the CloudFormation stack to be described.