Implement Canary Release

Learn how to gradually shift traffic to a new version of your backend service using the traffic-split plugin.

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 plugin to distribute requests among different upstreams based on assigned weights.

Prerequisites

An API7 Enterprise instance is running.
A Gateway Group is created and a Gateway instance is running.
A token from the Dashboard.

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

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.

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

adc sync -f adc.yaml

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

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

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

Configure Upstream Health Checks — ensure traffic only reaches healthy backends.
Configure Rate Limiting — protect your canary deployment from traffic spikes.