Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/davidgf/serverless-plugin-canary-deployments

Canary deployments for your Serverless application
https://github.com/davidgf/serverless-plugin-canary-deployments

aws aws-codedeploy aws-lambda canary-deployments ci-cd continuous-delivery continuous-deployment continuous-integration lambda-functions serverless serverless-framework serverless-plugin

Last synced: about 2 months ago
JSON representation

Canary deployments for your Serverless application

Awesome Lists containing this project

README 

        
[![npm version](https://badge.fury.io/js/serverless-plugin-canary-deployments.svg)](https://badge.fury.io/js/serverless-plugin-canary-deployments)



# Serverless Plugin Canary Deployments



A Serverless plugin to implement canary deployments of Lambda functions, making use of the [traffic shifting feature](https://docs.aws.amazon.com/lambda/latest/dg/lambda-traffic-shifting-using-aliases.html) in combination with [AWS CodeDeploy](https://docs.aws.amazon.com/lambda/latest/dg/automating-updates-to-serverless-apps.html)



## Contents



- [Installation](#installation)

- [Usage](#usage)

- [Configuration](#configuration)

- [How it works](#how)

- [Limitations](#limitations)

- [License](#license)



## Installation



`npm i --save-dev serverless-plugin-canary-deployments`



## Usage



To enable gradual deployments for Lambda functions, your `serverless.yml` should look like this:



```yaml

service: canary-deployments

provider:

  name: aws

  runtime: nodejs6.10

  iamRoleStatements:

    - Effect: Allow

      Action:

        - codedeploy:*

      Resource:

        - "*"



plugins:

  - serverless-plugin-canary-deployments



functions:

  hello:

    handler: handler.hello

    events:

      - http: GET hello

    deploymentSettings:

      type: Linear10PercentEvery1Minute

      alias: Live

      preTrafficHook: preHook

      postTrafficHook: postHook

      alarms:

        - FooAlarm          # When a string is provided, it expects the alarm Logical ID

        - name: BarAlarm    # When an object is provided, it expects the alarm name in the name property



  preHook:

    handler: hooks.pre

  postHook:

    handler: hooks.post

```



You can see a working example in the [example folder](./example/).



## Configuration



* `type`: (required) defines how the traffic will be shifted between Lambda function versions. It must be one of the following:

  - `Canary10Percent5Minutes`: shifts 10 percent of traffic in the first increment. The remaining 90 percent is deployed five minutes later.

  - `Canary10Percent10Minutes`: shifts 10 percent of traffic in the first increment. The remaining 90 percent is deployed 10 minutes later.

  - `Canary10Percent15Minutes`: shifts 10 percent of traffic in the first increment. The remaining 90 percent is deployed 15 minutes later.

  - `Canary10Percent30Minutes`: shifts 10 percent of traffic in the first increment. The remaining 90 percent is deployed 30 minutes later.

  - `Linear10PercentEvery1Minute`: shifts 10 percent of traffic every minute until all traffic is shifted.

  - `Linear10PercentEvery2Minutes`: shifts 10 percent of traffic every two minutes until all traffic is shifted.

  - `Linear10PercentEvery3Minutes`: shifts 10 percent of traffic every three minutes until all traffic is shifted.

  - `Linear10PercentEvery10Minutes`: shifts 10 percent of traffic every 10 minutes until all traffic is shifted.

  - `AllAtOnce`: shifts all the traffic to the new version, useful when you only need to execute the validation hooks.

* `alias`: (required) name that will be used to create the Lambda function alias.

* `preTrafficHook`: (optional) validation Lambda function that runs before traffic shifting. It must use the CodeDeploy SDK to notify about this step's success or failure (more info [here](https://docs.aws.amazon.com/codedeploy/latest/userguide/reference-appspec-file-structure-hooks.html)).

* `postTrafficHook`: (optional) validation Lambda function that runs after traffic shifting. It must use the CodeDeploy SDK to notify about this step's success or failure (more info [here](https://docs.aws.amazon.com/codedeploy/latest/userguide/reference-appspec-file-structure-hooks.html))

* `alarms`: (optional) list of CloudWatch alarms. If any of them is triggered during the deployment, the associated Lambda function will automatically roll back to the previous version.

* `triggerConfigurations`: (optional) list of CodeDeploy Triggers. See more details in the [CodeDeploy TriggerConfiguration Documentation](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-properties-codedeploy-deploymentgroup-triggerconfig.html), or [this CodeDeploy notifications guide](https://docs.aws.amazon.com/codedeploy/latest/userguide/monitoring-sns-event-notifications-create-trigger.html) for example uses



### Default configurations



You can set default values for all functions in a top-level custom deploymentSettings section.  E.g.:



```yaml

custom:

  deploymentSettings:

    codeDeployRole: some_arn_value

    codeDeployRolePermissionsBoundary: some_arn_value

    stages:

      - dev

      - prod



functions:

  ...

```



Some values are only available as top-level configurations.  They are:



* `codeDeployRole`: (optional) an ARN specifying an existing IAM role for CodeDeploy.  If absent, one will be created for you.  See the [codeDeploy policy](./example-code-deploy-policy.json) for an example of what is needed.

* `codeDeployRolePermissionsBoundary`: (optional) an ARN specifying an existing IAM permissions boundary, this permission boundary is set on the code deploy that is being created when codeDeployRole is not defined.

* `stages`: (optional) list of stages where you want to deploy your functions gradually. If not present, it assumes that are all of them.



## How it works



The plugin relies on the [AWS Lambda traffic shifting feature](https://docs.aws.amazon.com/lambda/latest/dg/lambda-traffic-shifting-using-aliases.html) to balance traffic between versions and [AWS CodeDeploy](https://docs.aws.amazon.com/lambda/latest/dg/automating-updates-to-serverless-apps.html) to automatically update its weight. It modifies the `CloudFormation` template generated by [Serverless](https://github.com/serverless/serverless), so that:



1. It creates a Lambda function Alias for each function with deployment settings.

2. It creates a CodeDeploy Application and adds a [CodeDeploy DeploymentGroup](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-codedeploy-deploymentgroup.html) per Lambda function, according to the specified settings.

3. It modifies events that trigger Lambda functions, so that they invoke the newly created alias.



## Limitations



For now, the plugin only works with Lambda functions invoked by



* API Gateway

* Stream based (such as the triggered by Kinesis, DynamoDB Streams or SQS)

* SNS based events

* S3 events

* CloudWatch Scheduled events

* CloudWatch Logs

* IoT rules

* AppSync DataSources



[More events](https://serverless.com/framework/docs/providers/aws/events/) will be added soon.



## License



ISC © [David García](https://github.com/davidgf)