aws-blue-green-toolkit

Utility functions to help with performing blue/green and canary deployments in AWS infrastructure

Usage no npm install needed!

<script type="module">
  import awsBlueGreenToolkit from 'https://cdn.skypack.dev/aws-blue-green-toolkit';
</script>

README

test-and-publish codecov Commitizen friendly semantic-release

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:

  1. Replacement database cluster is started or created
  2. Autoscaling minimum capacity on the new db cluster is set to match the current capacity of the active cluster
  3. Replacement database is purged and the latest schema is created
  4. SNS subscriptions are enabled for the replacement queue
  5. SQS subscription lambda is enabled for the replacement stack
  6. A new task set is created in the ECS service, it is bound to the replacement stack's database
  7. The new task set is placed in a testing target group, this is attached to a testing port on the load balancer
  8. Automated tests are carried out against the replacement service via the testing port
  9. The replacement stack becomes the active stack, what was the active stack is now the old stack.
  10. Autoscaling minimum capacity on the active set is reverted to the normal value, database will scale in when traffic is lower.
  11. SNS subscriptions are disabled for the old stack
  12. SQS subscription for the old stack's ingest queue is disabled
  13. Old database cluster is stopped or deleted
  14. The old SQS queues are purged
  15. 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

src/main/AuroraTools.ts:12-248

Toolkit for Aurora operations

getClusterState

src/main/AuroraTools.ts:52-69

Gets the current state of one of the Aurora clusters

Parameters

Returns Promise<ClusterState>

scaleIn

src/main/AuroraTools.ts:108-110

Reverts a cluster's minimum reader count to the configured minimum

Parameters

Returns Promise<void>

scaleOut

src/main/AuroraTools.ts:118-123

Scales out a cluster to match it's partner's size

Parameters

Returns Promise<void>

getReaderCount

src/main/AuroraTools.ts:131-145

Get a count of the number of active readers for a cluster

Parameters

Returns Promise<number> The number of active readers

startDatabase

src/main/AuroraTools.ts:153-156

Starts a stopped db cluster

Parameters

Returns Promise<void>

stopDatabase

src/main/AuroraTools.ts:164-167

Stops a running db cluster

Parameters

Returns Promise<void>

deleteDatabase

src/main/AuroraTools.ts:175-207

Deletes a running db cluster

Parameters

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

Returns Promise<void>

enableAlarmsActions

src/main/CloudwatchTools.ts:62-65

Enable all alarm actions

Parameters

Returns Promise<void>

ClusterState

src/main/constants.ts:6-11

Enum for describing the state of an RDS cluster

Type: number

StackReference

src/main/constants.ts:18-21

Enum for referencing blue or green stacks

Type: number

DynamoTools

src/main/DynamoTools.ts:11-46

Toolkit for Dynamo operations

deleteTable

src/main/DynamoTools.ts:38-45

Deletes a dynamo table

Parameters

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

Returns Promise<RegisterStreamConsumerOutput>

deregisterConsumer

src/main/KinesisTools.ts:61-68

Deregisters an existing consumer for a Kinesis data stream

Parameters

Returns Promise<void>

describeConsumer

src/main/KinesisTools.ts:76-85

Describes a consumer for a Kinesis data stream

Parameters

Returns Promise<DescribeStreamConsumerOutput>

LambdaTools

src/main/LambdaTools.ts:22-315

Toolkit for Lambda operations

enableRule

src/main/LambdaTools.ts:91-93

Enables a lambda's cloudwatch events rule (ie, cron trigger)

Parameters

Returns Promise<void>

disableRule

src/main/LambdaTools.ts:101-103

Disables a lambda's cloudwatch events rule (ie, cron trigger)

Parameters

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 stack
  • eventSourceArn string The ARN of the event source
  • sourceSpecificParams 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

Returns Promise<EventSourceMappingsList>

enableEventMapping

src/main/LambdaTools.ts:181-183

Enables a lambda's event mappings (eg, an SQS subscription)

Parameters

Returns Promise<void>

disableEventMapping

src/main/LambdaTools.ts:191-193

Disables a lambda's event mappings (eg, an SQS subscription)

Parameters

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

Returns Promise<void>

getVersion

src/main/LambdaTools.ts:214-220

Gets the currently running version of a lambda fn

Parameters

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 stack
  • Name 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

Returns Promise<LatestLambdaMetricsMap>

SnsTools

src/main/SnsTools.ts:41-101

Toolkit for SNS operations

enableSubscription

src/main/SnsTools.ts:88-90

Enables an SNS subscription

Parameters

Returns Promise<void>

disableSubscription

src/main/SnsTools.ts:98-100

Disables an SNS subscription

Parameters

Returns Promise<void>

SqsTools

src/main/SqsTools.ts:11-50

Toolkit for SQS operations

purgeQueues

src/main/SqsTools.ts:36-49

Purges a queue pair (q and dlq) based on config and queue reference

Parameters

Returns Promise<void>