Have ideas to improve npm?Join in the discussion! »

    serverless-plugin-canary-deployments

    0.6.0 • Public • Published

    npm version

    Serverless Plugin Canary Deployments

    A Serverless plugin to implement canary deployments of Lambda functions, making use of the traffic shifting feature in combination with AWS CodeDeploy

    Contents

    Installation

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

    Usage

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

    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.

    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).
    • 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)
    • 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, or this CodeDeploy notifications guide for example uses

    Default configurations

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

    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 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 to balance traffic between versions and AWS CodeDeploy to automatically update its weight. It modifies the CloudFormation template generated by 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 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

    More events will be added soon.

    License

    ISC © David García

    Install

    npm i serverless-plugin-canary-deployments

    DownloadsWeekly Downloads

    12,700

    Version

    0.6.0

    License

    ISC

    Unpacked Size

    514 kB

    Total Files

    72

    Last publish

    Collaborators

    • avatar
    • avatar