README
aws-blue-green-toolkit
Utility functions to help with performing blue/green and canary deployments in AWS infrastructure
background
AWS support for blue/green and canary deployments is provided by CodeDeploy. CodeDeploy is great in what it does, but it only really manages swapping versions for web services. Any services that sit behind the public facing API don't get managed by the CodeDeploy flow.
A common pattern for blue/green and canary deployments is to not just use a pair of services for the web component, but use a pair of services for the whole pipeline, eg data ingestion, databases, queues, data manipulation lambdas etc. You can manage starting, hydrating, and using these services as part of the CodeDeploy pipeline through the use of hooks (in the form of lambdas). Using these hook lambdas you can manage blue/green or canary deployments of a whole stack of services using the aws-sdk, unfortunately this normally means writing a lot of code to manage the process.
This module is a set of utility functions that I use to reduce the boilerplate required to set up these deploment hook lambdas.
example architecture
For an example web api, using a node application in docker, with a SQL data store, and data updates being published on an SNS topic, the architecture may looks something like this:
In order to manage blue/green deployments for this service, CodeDeploy will directly handle deploying the new ECS service, attaching target groups to load balancers, flipping traffic over to the new service, and tearing down the old containers.
Unfortunately this really only covers less than half of the architecture. Everything from the data updates topic through to the database is up to you to manage through hooks. When deploying a new version of the service, the steps required will be something like this:
- Replacement database cluster is started or created
- Autoscaling minimum capacity on the new db cluster is set to match the current capacity of the active cluster
- Replacement database is purged and the latest schema is created
- SNS subscriptions are enabled for the replacement queue
- SQS subscription lambda is enabled for the replacement stack
- A new task set is created in the ECS service, it is bound to the replacement stack's database
- The new task set is placed in a testing target group, this is attached to a testing port on the load balancer
- Automated tests are carried out against the replacement service via the testing port
- The replacement stack becomes the active stack, what was the active stack is now the old stack.
- Autoscaling minimum capacity on the active set is reverted to the normal value, database will scale in when traffic is lower.
- SNS subscriptions are disabled for the old stack
- SQS subscription for the old stack's ingest queue is disabled
- Old database cluster is stopped or deleted
- The old SQS queues are purged
- The old ECS taskset is destroyed
CodeDeploy will carry out steps 6, 7, 9, and 15. This module contains tools to help you perform the other steps from your deployment hook lambda functions.
api
Table of Contents
- AuroraTools
- CloudWatchTools
- ClusterState
- StackReference
- DynamoTools
- AuroraConfig
- CloudWatchConfig
- AwsConfig
- DynamoConfig
- KinesisConfig
- LambdaConfig
- LatestLambdaMetricsMap
- LatestLambdaMetric
- SnsConfig
- TopicData
- SqsConfig
- KinesisTools
- LambdaTools
- SnsTools
- SqsTools
AuroraTools
src/main/AuroraTools.ts:12-248
Toolkit for Aurora operations
getClusterState
Gets the current state of one of the Aurora clusters
Parameters
reference
StackReference Reference to a db cluster
Returns Promise<ClusterState>
scaleIn
src/main/AuroraTools.ts:108-110
Reverts a cluster's minimum reader count to the configured minimum
Parameters
reference
StackReference Reference to a db cluster
Returns Promise<void>
scaleOut
src/main/AuroraTools.ts:118-123
Scales out a cluster to match it's partner's size
Parameters
reference
StackReference Reference to a db cluster
Returns Promise<void>
getReaderCount
src/main/AuroraTools.ts:131-145
Get a count of the number of active readers for a cluster
Parameters
reference
StackReference Reference to a db cluster
Returns Promise<number> The number of active readers
startDatabase
src/main/AuroraTools.ts:153-156
Starts a stopped db cluster
Parameters
reference
StackReference Reference to a db cluster
Returns Promise<void>
stopDatabase
src/main/AuroraTools.ts:164-167
Stops a running db cluster
Parameters
reference
StackReference Reference to a db cluster
Returns Promise<void>
deleteDatabase
src/main/AuroraTools.ts:175-207
Deletes a running db cluster
Parameters
reference
StackReference Reference to a db cluster
Returns Promise<void>
applyTags
src/main/AuroraTools.ts:216-247
Parses a message from an rds event subscription, if the event was triggered by a scale out operation, the tags defined in config are applied to the newly created reader.
Parameters
record
SNSEventRecord An SNS event record of the type published by rds event streams
Returns Promise<void>
CloudWatchTools
src/main/CloudwatchTools.ts:10-66
Toolkit for CloudWatch operations
disableAlarmsActions
src/main/CloudwatchTools.ts:52-55
Disable all alarm actions
Parameters
reference
StackReference Reference to a subscription queue stack
Returns Promise<void>
enableAlarmsActions
src/main/CloudwatchTools.ts:62-65
Enable all alarm actions
Parameters
reference
StackReference Reference to a subscription queue stack
Returns Promise<void>
ClusterState
Enum for describing the state of an RDS cluster
Type: number
StackReference
Enum for referencing blue or green stacks
Type: number
DynamoTools
Toolkit for Dynamo operations
deleteTable
Deletes a dynamo table
Parameters
reference
StackReference Reference to a active table
Returns Promise<void>
AuroraConfig
src/main/@types/aurora-tools.ts:9-14
Extends AwsConfig
Configuration options for the Aurora toolkit
CloudWatchConfig
src/main/@types/cloudwatch-tools.ts:9-12
Extends AwsConfig
Configuration options for the CloudWatch toolkit
AwsConfig
src/main/@types/common.ts:6-12
Base config used in all tool kits
DynamoConfig
src/main/@types/dynamo-tools.ts:9-13
Extends AwsConfig
Configuration options for the Aurora toolkit
KinesisConfig
src/main/@types/kinesis-tools.ts:9-13
Extends AwsConfig
Configuration options for the Aurora toolkit
LambdaConfig
src/main/@types/lambda-tools.ts:9-13
Extends AwsConfig
Configuration options for the Lambda toolkit
LatestLambdaMetricsMap
src/main/@types/lambda-tools.ts:20-22
Map of Lambda metrics with the latest data
LatestLambdaMetric
src/main/@types/lambda-tools.ts:29-33
Latest metric data for each metric
SnsConfig
src/main/@types/sns-tools.ts:9-12
Extends AwsConfig
Configuration options for the SNS toolkit
TopicData
src/main/@types/sns-tools.ts:19-25
Parameters to describe an SNS topic subscription
SqsConfig
src/main/@types/sqs-tools.ts:9-12
Extends AwsConfig
Configuration options for the SQS toolkit
KinesisTools
src/main/KinesisTools.ts:15-86
Toolkit for Kinesis data stream operations
registerConsumer
src/main/KinesisTools.ts:44-53
Registers a new consumer for a Kinesis data stream
Parameters
reference
StackReference Reference to an active stack
Returns Promise<RegisterStreamConsumerOutput>
deregisterConsumer
src/main/KinesisTools.ts:61-68
Deregisters an existing consumer for a Kinesis data stream
Parameters
reference
StackReference Reference to an active stack
Returns Promise<void>
describeConsumer
src/main/KinesisTools.ts:76-85
Describes a consumer for a Kinesis data stream
Parameters
reference
StackReference Reference to an active stack
Returns Promise<DescribeStreamConsumerOutput>
LambdaTools
src/main/LambdaTools.ts:22-315
Toolkit for Lambda operations
enableRule
Enables a lambda's cloudwatch events rule (ie, cron trigger)
Parameters
reference
StackReference Reference to a lambda stack
Returns Promise<void>
disableRule
src/main/LambdaTools.ts:101-103
Disables a lambda's cloudwatch events rule (ie, cron trigger)
Parameters
reference
StackReference Reference to a lambda stack
Returns Promise<void>
createEventSourceMapping
src/main/LambdaTools.ts:113-128
Creates a lambda's event source mapping (eg, a Kinesis stream)
Parameters
reference
StackReference Reference to a lambda stackeventSourceArn
string The ARN of the event sourcesourceSpecificParams
Omit<Lambda.CreateEventSourceMappingRequest, ("FunctionName"
|"EventSourceArn"
)> Any params specific to the event source (optional, default{}
)
Returns Promise<EventSourceMappingConfiguration>
listEventSourceMappings
src/main/LambdaTools.ts:136-155
Lists all event source mappings for the referenced function
Parameters
reference
StackReference Reference to a lambda stack
Returns Promise<EventSourceMappingsList>
enableEventMapping
src/main/LambdaTools.ts:181-183
Enables a lambda's event mappings (eg, an SQS subscription)
Parameters
reference
StackReference Reference to a lambda stack
Returns Promise<void>
disableEventMapping
src/main/LambdaTools.ts:191-193
Disables a lambda's event mappings (eg, an SQS subscription)
Parameters
reference
StackReference Reference to a lambda stack
Returns Promise<void>
deleteEventMapping
src/main/LambdaTools.ts:203-205
Deletes a lambda's event mapping (eg, a Kinesis stream)
You may use the listEventSourceMappings
method if you
need to retrieve UUIDs of the function event sources
Parameters
UUID
StackReference The identifier of the event source mapping
Returns Promise<void>
getVersion
src/main/LambdaTools.ts:214-220
Gets the currently running version of a lambda fn
Parameters
reference
StackReference Reference to a lambda stack
Returns Promise<string> The lambda version
getAlias
src/main/LambdaTools.ts:230-236
Returns details about a Lambda function alias.
Parameters
reference
StackReference Reference to a lambda stackName
string The name of the alias to return data about
Returns Promise<AliasConfiguration>
getLatestMetrics
src/main/LambdaTools.ts:245-314
Returns the latest metrics about a Lambda function alias.
Parameters
reference
StackReference Reference to a lambda stack
Returns Promise<LatestLambdaMetricsMap>
SnsTools
Toolkit for SNS operations
enableSubscription
Enables an SNS subscription
Parameters
reference
StackReference Reference to a subscription queue stack
Returns Promise<void>
disableSubscription
Disables an SNS subscription
Parameters
reference
StackReference Reference to a subscription queue stack
Returns Promise<void>
SqsTools
Toolkit for SQS operations
purgeQueues
Purges a queue pair (q and dlq) based on config and queue reference
Parameters
reference
StackReference Reference to a subscription queue stack
Returns Promise<void>