Canary Traffic Shifting

By using canary traffic shifting, you can evaluate a portion of your API traffic on the new upstream, while the legacy upstream continues to handle the rest of the traffic. This testing phase acts as a safety measure, confirming the new functionality before transitioning all traffic to it.

info

This differs from a canary release since the API version is not changed.

Prerequisites

1. Obtain a user account with Super Admin or API Provider role.
2. Publish a service.

Shift Traffic to New Canary Upstream Based on Percentage

info

Canary traffic shifting cannot be applied to individual routes. Canary rules affect all routes in the service.

In this tutorial, you will direct 10% of random traffic to a canary upstream hosted at a new server. The remaining 90% of traffic will continue to flow to the baseline upstream.

Once the testing is successfully concluded, the canary upstream will transit into the new baseline, and the legacy baseline upstream will be removed, completing the entire upgrade process.

1. Select Services from the side navigation bar and then select Swagger Petstore > 1.0.0 on Test Group.

2. In the Canary Rules field, click Start Canary.

3. In the Set Up Canary Rules field, do the following:

   • In the Conditions field, close the switch.
   • In the Weight field, enter 10%.

4. Click Next.

5. In the Choose or Create Canary Upstream field, choose to create a new upstream.

   • Modify the name of the new upstream to newupstream.
   • Adjust the host of the node to point to the new backend.
   • The rest of the properties will remain the same as the baseline upstream.

6. Click Next.

7. Confirm your information and then click Start. Your canary rules will work immediately.

8. Make API requests for testing and then loop the request API 10 times:

   for i in {1..5}; do curl 127.0.0.1:9080/pet/1;  done 

   Response to 9 requests:

   HTTP/1.1 200 OK
   
   {
     "name": "Dog",
     "photoUrls": [
       "https://example.com/dog-1.jpg",
       "https://example.com/dog-2.jpg"
     ],
     "id": 1,
     "category": {
       "id": 1,
       "name": "pets"
     },
     "tags": [
       {
         "id": 1,
         "name": "friendly"
       },
       {
         "id": 2,
         "name": "smart"
       }
     ],
     "status": "available"
   }

   Response to 1 request:

   HTTP/1.1 200 OK
   
   {
     "name": "TestDog on new upstream",
     "photoUrls": [
       "https://example.com/dog-1.jpg",
       "https://example.com/dog-2.jpg"
     ],
     "id": 1,
     "category": {
       "id": 1,
       "name": "pets"
     },
     "tags": [
       {
         "id": 1,
         "name": "friendly"
       },
       {
         "id": 2,
         "name": "smart"
       }
     ],
     "status": "available"
   }

9. In the Canary Rules field, click Edit.

   • From the dialog box, adjust the weight to 50%.
   • Click Edit.

10. Make more API requests to test the canary upstream.

11. In the Canary Rules field, click Finish. From the dialog box, do the following:

    • In the Baseline Upstream field, choose canary upstream: newupstream.
    • In the Delete Unselected Upstream field, open the switch.

12. Click Finish.

Shift Traffic to New Canary Upstream Based on Request Header

In this tutorial, you will direct an API request with the header "version = test" to a canary upstream, while the remaining traffic will continue to flow to the baseline upstream.

Once the testing is successfully concluded, the canary upstream will transition into the new baseline, and the legacy baseline upstream will be removed, completing the entire upgrade process.

1. Select Services from the side navigation bar and then select Swagger Petstore > 1.0.0 on Test Group.
2. In the Canary Rules field, click Start Canary.
3. In the Set Up Canary Rules field, do the following:
   • In the Conditions field, open the switch.
   • Fill in the header requirement with header version = test.
   • In the Weight field, enter 100%.
   • Click Next.
4. In the Choose or Create Canary Upstream field, choose to create a new upstream.
   • Modify the name of the new upstream to newupstream.
   • Adjust the host of the node to point to the new backend.
   • The rest of the properties will remain the same as the baseline upstream.
   • Click Next.
5. Confirm your information and then click Start. Your canary rules will affect immediately.
6. Make API requests for testing.

Response to requests with the correct header:

curl 127.0.0.1:9080/pet/1 -H "version:test" 

HTTP/1.1 200 OK

{
  "name": "TestDog on new upstream",
  "photoUrls": [
    "https://example.com/dog-1.jpg",
    "https://example.com/dog-2.jpg"
  ],
  "id": 1,
  "category": {
    "id": 1,
    "name": "pets"
  },
  "tags": [
    {
      "id": 1,
      "name": "friendly"
    },
    {
      "id": 2,
      "name": "smart"
    }
  ],
  "status": "available"
}

Response to requests with wrong header:

curl 127.0.0.1:9080/pet/1 -H "version:new"

HTTP/1.1 200 OK

{
  "name": "Dog",
  "photoUrls": [
    "https://example.com/dog-1.jpg",
    "https://example.com/dog-2.jpg"
  ],
  "id": 1,
  "category": {
    "id": 1,
    "name": "pets"
  },
  "tags": [
    {
      "id": 1,
      "name": "friendly"
    },
    {
      "id": 2,
      "name": "smart"
    }
  ],
  "status": "available"
}

Response to requests without header:

curl 127.0.0.1:9080/pet/1 

HTTP/1.1 200 OK

{
  "name": "Dog",
  "photoUrls": [
    "https://example.com/dog-1.jpg",
    "https://example.com/dog-2.jpg"
  ],
  "id": 1,
  "category": {
    "id": 1,
    "name": "pets"
  },
  "tags": [
    {
      "id": 1,
      "name": "friendly"
    },
    {
      "id": 2,
      "name": "smart"
    }
  ],
  "status": "available"
}

7. In the Canary Rules field, click Finish. From the dialog box, do the following:

   • In the Baseline Upstream field, choose canary upstream: newupstream.
   • In the Delete Unselected Upstream field, open the switch.

8. Click Finish.