# Implement Canary Release

Canary release is a deployment strategy that reduces the risk of introducing a new software version in production by slowly rolling out the change to a small subset of users before making it available to everyone.

In API7 Enterprise, you can use the [`traffic-split`](https://docs.api7.ai/hub/traffic-split.md) plugin to distribute requests among different upstreams based on assigned weights.

## Prerequisites[​](#prerequisites "Direct link to Prerequisites")

* An API7 Enterprise instance is running.
* A Gateway Group is created and a Gateway instance is running.
* A [token from the Dashboard](https://docs.api7.ai/api7-gateway/reference/obtain-dashboard-token.md).

## Workflow Overview[​](#workflow-overview "Direct link to Workflow Overview")

The following diagram illustrates a canary release where 90% of traffic goes to version 1 and 10% goes to version 2:

<!-- -->

## Configure Traffic Splitting[​](#configure-traffic-splitting "Direct link to Configure Traffic Splitting")

In this example, we will create a service whose default upstream represents version 1 and then configure the `traffic-split` plugin on a route to send a smaller percentage of traffic to an inline version 2 upstream.

* Admin API
* ADC

```
curl -k "https://localhost:7443/apisix/admin/services/canary-service?gateway_group_id={gateway_group_id}" -X PUT \

  -H "X-API-KEY: ${API_KEY}" \

  -H "Content-Type: application/json" \

  -d '{

    "name": "canary-service",

    "upstream": {

      "type": "roundrobin",

      "scheme": "https",

      "pass_host": "node",

      "nodes": [

        {

          "host": "mock.api7.ai",

          "port": 443,

          "weight": 100

        }

      ]

    }

  }'



curl -k "https://localhost:7443/apisix/admin/routes/canary-route?gateway_group_id={gateway_group_id}" -X PUT \

  -H "X-API-KEY: ${API_KEY}" \

  -H "Content-Type: application/json" \

  -d '{

    "name": "canary-route",

    "methods": ["GET"],

    "paths": ["/headers"],

    "service_id": "canary-service",

    "plugins": {

      "traffic-split": {

        "rules": [

          {

            "weighted_upstreams": [

              {

                "weight": 10,

                "upstream": {

                  "type": "roundrobin",

                  "nodes": [

                    {

                      "host": "httpbin.org",

                      "port": 443,

                      "weight": 1

                    }

                  ]

                }

              },

              {

                "weight": 90

              }

            ]

          }

        ]

      }

    },

    "priority": 0

  }'
```

adc.yaml

```
services:

  - name: canary-service

    upstream:

      scheme: https

      pass_host: node

      nodes:

        - host: mock.api7.ai

          port: 443

          weight: 100

    routes:

      - name: canary-route

        uris:

          - /headers

        methods:

          - GET

        plugins:

          traffic-split:

            rules:

              - weighted_upstreams:

                  - weight: 10

                    upstream:

                      type: roundrobin

                      scheme: https

                      pass_host: node

                      nodes:

                        - host: httpbin.org

                          port: 443

                          weight: 1

                  - weight: 90

    labels:

      docs-example: canary-service
```

Preview the changes owned by this example and confirm that the diff contains no unintended updates or deletions:

```
adc diff -f adc.yaml \

  --include-resource-type service \

  --label-selector docs-example=canary-service
```

Synchronize the reviewed configuration:

```
adc sync -f adc.yaml \

  --include-resource-type service \

  --label-selector docs-example=canary-service
```

## Gradually Increase Traffic[​](#gradually-increase-traffic "Direct link to Gradually Increase Traffic")

As you gain confidence in version 2, update the weights to increase its traffic share.

* **50/50 split**: Set both weights to 50.
* **100% rollout**: Set version 2 weight to 100 and version 1 weight to 0, or update the service's default upstream to the new version and remove the plugin.

## Validate the Configuration[​](#validate-the-configuration "Direct link to Validate the Configuration")

Send multiple requests to the route and verify the distribution:

```
for i in $(seq 1 60); do curl -s "http://127.0.0.1:9080/headers" | grep -q 'X-Application-Owner' && echo v1 || echo v2; done | sort | uniq -c
```

The output should show a distribution close to your configured weights. In the local validation environment, 60 requests produced 56 `v1` responses and 4 `v2` responses for the `90/10` split.

## Rollback[​](#rollback "Direct link to Rollback")

If you detect issues with version 2, you can quickly roll back by setting the weight of version 1 to 100 and version 2 to 0.

```
{

  "weighted_upstreams": [

    {

      "upstream": {

        "type": "roundrobin",

        "scheme": "https",

        "pass_host": "node",

        "nodes": [

          {

            "host": "httpbin.org",

            "port": 443,

            "weight": 1

          }

        ]

      },

      "weight": 0

    },

    { "weight": 100 }

  ]

}
```

## Next Steps[​](#next-steps "Direct link to Next Steps")

* [Configure Upstream Health Checks](https://docs.api7.ai/api7-gateway/how-to-guides/traffic-management/health-check.md) — ensure traffic only reaches healthy backends.
* [Configure Rate Limiting](https://docs.api7.ai/api7-gateway/how-to-guides/traffic-management/rate-limiting.md) — protect your canary deployment from traffic spikes.
