gulp-cf-deploy
v2.2.1
Published
Gulp plugin for deploying AWS CloudFormation stacks
Downloads
2,348
Readme
Deploy CloudFormation stacks in Gulp
Does what it says on the can.
Why this package?
The headline benefit over other packages is the surfacing of stack errors:
Other benefits:
- Lists resources created / updated / deleted
- Errors are displayed ASAP, so you can get to fixing them while the rollback completes
- On failure a URL is provided direct to the stack details in the AWS console for full details
- Parameters can be passed as a hash / plain object (rather than in CloudFormation's verbose format)
- Waits for the stack to be deployed before finishing, so tasks in series can rely on the resources being available
- But does not wait for cleanup of old resources, which should not impact following tasks
- Keeps you updated while waiting for the deployment to complete
- Pipes the outputs of the stack as simplified JSON through the Gulp stream so you can save the outputs or process them further
- Defaults to deleting a failed stack creation rather than the CloudFormation default of 'rollback' which then has to be manually deleted to try again (however, even when the delete has completed the full details of the failed stack are still available at the console URL)
Requirements
This packages has a peer dependency on Gulp v4, which you can currently
install as gulp@next
.
Install
yarn add --dev gulp-cf-deploy
Or if you're still in npm world: npm install --save-dev gulp-cf-deploy
API
import cfDeploy from 'gulp-cf-deploy'
gulp.task('deploy:aws', () =>
gulp
.src('resources.yaml')
.pipe(cfDeploy(awsServiceOptions, stackNameOrOptions, parameters))
.pipe(gulp.dest('build')),
)
Will deploy (create or update) the CloudFormation stack defined in resources.yaml
and save it's outputs as build/resources.json
awsServiceOptions
: passed to new AWS.CloudFormation()
.
Provide your AWS credentials (if not already set in AWS.config
) and region
.
stackNameOrOptions
: passed to createStack()
or updateStack()
.
Often all that's needed is the StackName
in which case you can just pass the name as a string.
In addition:
StackName
: defaulted to the source file's 'stem', in the example above the stack will be namedresources
Parameters
: will be supplemented with the 3rd argumentparameters
TemplateBody
: is pulled from the source file's contentOnFailure
: set toDELETE
when creating a stack, otherwise the stack needs to be manually deleted to try again (even when deleted the stack can be inspected in the AWS Console for 30 days)Capabilities
: Needs to be set if creating IAM resources, see the SDK docs.
parameters
: a hash / plain object of parameters that is merged into Parameters
(if any) of stackNameOrOptions
.
For example: { Foo: 123, ... }
becomes [{ ParameterKey: 'Foo', ParameterValue: 123 }, ...]
Output Vinyl file: The Outputs
of the stack is simplified into a hash / plain object.
For example [{ OutputKey: 'Foo', OutputValue: 123 }, ...]
becomes { Foo: 123, ... }
.
The stream output is a file with the same properties as the source file expect:
contents
: JSON of the simplified outputs, pipe throughgulp-json-editor
to easily modifydata
: the simplified outputs objectextname
: extension is set tojson
- Name is unchanged: pipe through
gulp-rename
if you want to change it
Post-processing example
If you are creating IAM access keys then there are a couple of considerations.
- CloudFormation will only output the SecretAccessKey when the key is first created (or regenerated)
- When doing anything with IAM users you need to specify so in the stack options
---
Resources:
fooBucket:
Type: 'AWS::S3::Bucket'
Properties:
BucketName: 'bucket-of-foo'
bobUser:
Type: 'AWS::IAM::User'
Properties:
Policies: ...
bobAccessKey:
Type: 'AWS::IAM::AccessKey'
Properties:
Serial: 1
UserName: !Ref bobUser
Outputs:
fooBucketArn:
Value: !Sub 'arn:aws:s3:::${fooBucket}'
bobAccessKey:
Value: !Ref bobAccessKey
bobSecretKey:
Value: !GetAtt bobAccessKey.SecretAccessKey
CloudFormation will output fooBucketArn
and bobAccessKey
each deployment.
But bobSecretKey
will only be output when the keys are first created, or regenerated
(for example, if the Serial
was changed). Also, for security, you would want to be managing
you secret and access keys separately from other resource information (such as fooBucketArn
).
You can handle this as follows:
import AWS from 'aws-sdk/global'
import gulp from 'gulp'
import clone from 'gulp-clone'
import filter from 'gulp-filter'
import rename from 'gulp-rename'
import streamToPromise from 'stream-to-promise'
import jsonEditor from 'gulp-json-editor'
import omitBy from 'lodash/omitBy'
const region = 'ap-southeast-2'
gulp.task('deploy:aws', () => {
const cfOutput = gulp.src('deploy/resources.yaml').pipe(
cfDeploy(
{
credentials: new AWS.Config().credentials,
region,
},
{
Capabilities: ['CAPABILITY_IAM'], // Required because we are creating a user
StackName: `project-resources`,
},
),
)
const secrets = cfOutput
.pipe(clone())
.pipe(filter(file => file.data.bobSecretKey)) // Only perform if secret key was output
.pipe(
jsonEditor(resources => ({
accessKeyId: resources.bobAccessKey,
secretAccessKey: resources.bobSecretKey,
})),
)
.pipe(rename('bob-credentials.json'))
.pipe(gulp.dest('secrets', { mode: 0o600 }))
const resources = cfOutput
.pipe(
jsonEditor(resources => ({
...omitBy(resources, (v, k) => k.endsWith('Key')),
region,
})),
)
.pipe(gulp.dest('build')) // No need to rename, will be resources.json
return Promise.all([secrets, resources].map(streamToPromise))
})