Nerdy Poly Millionaires

    aws-blue-green-toolkit
    TypeScript icon, indicating that this package has built-in type declarations

    2.1.1 • Public • Published

    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>

    Install

    npm i aws-blue-green-toolkit

    DownloadsWeekly Downloads

    147

    Version

    2.1.1

    License

    MIT

    Unpacked Size

    213 kB

    Total Files

    93

    Last publish

    Collaborators

    • bbeesley