{"id":13527503,"url":"https://github.com/davidgf/serverless-plugin-canary-deployments","last_synced_at":"2025-05-15T20:00:36.403Z","repository":{"id":28909919,"uuid":"117262830","full_name":"davidgf/serverless-plugin-canary-deployments","owner":"davidgf","description":"Canary deployments for your Serverless application","archived":false,"fork":false,"pushed_at":"2024-04-19T18:04:40.000Z","size":837,"stargazers_count":375,"open_issues_count":19,"forks_count":83,"subscribers_count":7,"default_branch":"master","last_synced_at":"2025-05-08T03:19:18.192Z","etag":null,"topics":["aws","aws-codedeploy","aws-lambda","canary-deployments","ci-cd","continuous-delivery","continuous-deployment","continuous-integration","lambda-functions","serverless","serverless-framework","serverless-plugin"],"latest_commit_sha":null,"homepage":"","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"isc","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/davidgf.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2018-01-12T16:21:52.000Z","updated_at":"2025-05-07T10:22:50.000Z","dependencies_parsed_at":"2024-01-03T02:25:35.842Z","dependency_job_id":"57c5bf65-0203-4c7a-aef9-e2e39217d20a","html_url":"https://github.com/davidgf/serverless-plugin-canary-deployments","commit_stats":{"total_commits":54,"total_committers":21,"mean_commits":"2.5714285714285716","dds":0.4444444444444444,"last_synced_commit":"95c591f1eeba8712484f5d448c1da6b1d6dcefa3"},"previous_names":[],"tags_count":16,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/davidgf%2Fserverless-plugin-canary-deployments","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/davidgf%2Fserverless-plugin-canary-deployments/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/davidgf%2Fserverless-plugin-canary-deployments/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/davidgf%2Fserverless-plugin-canary-deployments/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/davidgf","download_url":"https://codeload.github.com/davidgf/serverless-plugin-canary-deployments/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":254414454,"owners_count":22067261,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["aws","aws-codedeploy","aws-lambda","canary-deployments","ci-cd","continuous-delivery","continuous-deployment","continuous-integration","lambda-functions","serverless","serverless-framework","serverless-plugin"],"created_at":"2024-08-01T06:01:49.480Z","updated_at":"2025-05-15T20:00:35.863Z","avatar_url":"https://github.com/davidgf.png","language":"JavaScript","funding_links":[],"categories":["JavaScript","Serverless Framework Plugins"],"sub_categories":[],"readme":"[![npm version](https://badge.fury.io/js/serverless-plugin-canary-deployments.svg)](https://badge.fury.io/js/serverless-plugin-canary-deployments)\n\n# Serverless Plugin Canary Deployments\n\nA 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)\n\n## Contents\n\n- [Installation](#installation)\n- [Usage](#usage)\n- [Configuration](#configuration)\n- [How it works](#how)\n- [Limitations](#limitations)\n- [License](#license)\n\n## \u003ca name=\"installation\"\u003e\u003c/a\u003eInstallation\n\n`npm i --save-dev serverless-plugin-canary-deployments`\n\n## \u003ca name=\"usage\"\u003e\u003c/a\u003eUsage\n\nTo enable gradual deployments for Lambda functions, your `serverless.yml` should look like this:\n\n```yaml\nservice: canary-deployments\nprovider:\n  name: aws\n  runtime: nodejs6.10\n  iamRoleStatements:\n    - Effect: Allow\n      Action:\n        - codedeploy:*\n      Resource:\n        - \"*\"\n\nplugins:\n  - serverless-plugin-canary-deployments\n\nfunctions:\n  hello:\n    handler: handler.hello\n    events:\n      - http: GET hello\n    deploymentSettings:\n      type: Linear10PercentEvery1Minute\n      alias: Live\n      preTrafficHook: preHook\n      postTrafficHook: postHook\n      alarms:\n        - FooAlarm          # When a string is provided, it expects the alarm Logical ID\n        - name: BarAlarm    # When an object is provided, it expects the alarm name in the name property\n\n  preHook:\n    handler: hooks.pre\n  postHook:\n    handler: hooks.post\n```\n\nYou can see a working example in the [example folder](./example/).\n\n## \u003ca name=\"configuration\"\u003e\u003c/a\u003eConfiguration\n\n* `type`: (required) defines how the traffic will be shifted between Lambda function versions. It must be one of the following:\n  - `Canary10Percent5Minutes`: shifts 10 percent of traffic in the first increment. The remaining 90 percent is deployed five minutes later.\n  - `Canary10Percent10Minutes`: shifts 10 percent of traffic in the first increment. The remaining 90 percent is deployed 10 minutes later.\n  - `Canary10Percent15Minutes`: shifts 10 percent of traffic in the first increment. The remaining 90 percent is deployed 15 minutes later.\n  - `Canary10Percent30Minutes`: shifts 10 percent of traffic in the first increment. The remaining 90 percent is deployed 30 minutes later.\n  - `Linear10PercentEvery1Minute`: shifts 10 percent of traffic every minute until all traffic is shifted.\n  - `Linear10PercentEvery2Minutes`: shifts 10 percent of traffic every two minutes until all traffic is shifted.\n  - `Linear10PercentEvery3Minutes`: shifts 10 percent of traffic every three minutes until all traffic is shifted.\n  - `Linear10PercentEvery10Minutes`: shifts 10 percent of traffic every 10 minutes until all traffic is shifted.\n  - `AllAtOnce`: shifts all the traffic to the new version, useful when you only need to execute the validation hooks.\n* `alias`: (required) name that will be used to create the Lambda function alias.\n* `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)).\n* `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))\n* `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.\n* `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\n\n### Default configurations\n\nYou can set default values for all functions in a top-level custom deploymentSettings section.  E.g.:\n\n```yaml\ncustom:\n  deploymentSettings:\n    codeDeployRole: some_arn_value\n    codeDeployRolePermissionsBoundary: some_arn_value\n    stages:\n      - dev\n      - prod\n\nfunctions:\n  ...\n```\n\nSome values are only available as top-level configurations.  They are:\n\n* `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.\n* `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.\n* `stages`: (optional) list of stages where you want to deploy your functions gradually. If not present, it assumes that are all of them.\n\n## \u003ca name=\"how\"\u003e\u003c/a\u003eHow it works\n\nThe 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:\n\n1. It creates a Lambda function Alias for each function with deployment settings.\n2. 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.\n3. It modifies events that trigger Lambda functions, so that they invoke the newly created alias.\n\n## \u003ca name=\"limitations\"\u003e\u003c/a\u003eLimitations\n\nFor now, the plugin only works with Lambda functions invoked by\n\n* API Gateway\n* Stream based (such as the triggered by Kinesis, DynamoDB Streams or SQS)\n* SNS based events\n* S3 events\n* CloudWatch Scheduled events\n* CloudWatch Logs\n* IoT rules\n* AppSync DataSources\n\n[More events](https://serverless.com/framework/docs/providers/aws/events/) will be added soon.\n\n## \u003ca name=\"license\"\u003e\u003c/a\u003eLicense\n\nISC © [David García](https://github.com/davidgf)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdavidgf%2Fserverless-plugin-canary-deployments","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fdavidgf%2Fserverless-plugin-canary-deployments","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdavidgf%2Fserverless-plugin-canary-deployments/lists"}