Menu
Amazon API Gateway
Developer Guide

Update a Canary Release

After a canary release is deployed, you may want to adjust the percentage of the canary traffic or enable or disable the use of a stage cache to optimize the test performance. You can also modify stage variables used in the canary release when the execution context is updated. To make such updates, call the stage:update operation with new values on canarySettings.

You can update a canary release using the API Gateway console, the AWS CLI update-stage command, an AWS SDK, and the API Gateway REST API's stage:update link-relation.

Update a Canary Release Using the API Gateway Console

To use the API Gateway console to update existing canary settings on a stage, do the following:

  1. Sign in to the API Gateway console and choose an existing API in the primary navigation pane.

  2. Choose Stages under the API and then choose an existing stage under the Stages list to open the Stage Editor.

  3. Choose the Canary tab in the Stage Editor.

  4. Update Percentage of requests directed to Canary by increasing or decreasing the percentage number between 0.0 and 100.0, inclusive.

  5. Update Canary Stage Variables, including adding, removing, or modifying a desired stage variable.

  6. Update the Enable use of stage cache option by selecting or clearing the check box.

  7. Save the changes.

Update a Canary Release Using the AWS CLI

To use the AWS CLI to update a canary, call the update-stage command.

To enable or disable the use of a stage cache for the canary, call the update-stage command as follows:

Copy
aws apigateway update-stage \ --rest-api-id {rest-api-id} \ --stage-name '{stage-name}' \ --patch-operations op=replace,path=/canarySettings/useStageCache,value=true

To adjust the canary traffic percentage, call update-stage to replace the /canarySettings/percentTraffic value on the stage.

Copy
aws apigateway update-stage \ --rest-api-id {rest-api-id} \ --stage-name '{stage-name}' \ --patch-operations op=replace,path=/canarySettings/percentTraffic,value=25.0

To update canary stage variables, including adding, replacing, or removing a canary stage variable:

Copy
aws apigateway update-stage \ --rest-api-id {rest-api-id} \ --stage-name '{stage-name}' \ --patch-operations '[{ \ "op": "replace", \ "path": "/canarySettings/stageVariableOverides/newVar" \ "value": "newVal", \ }, { \ "op": "replace", \ "path": "/canarySettings/stageVariableOverides/var2" \ "value": "val4", \ }, { \ "op": "remove", \ "path": "/canarySettings/stageVariableOverides/var1" \ }]'

You can update all of the above by combining the operations into a single patch-operations value:

Copy
aws apigateway update-stage \ --rest-api-id {rest-api-id} \ --stage-name '{stage-name}' \ --patch-operations '[{ \ "op": "replace", \ "path": "/canary/percentTraffic", \ "value": "20.0" \ }, { \ "op": "replace", \ "path": "/canary/useStageCache", \ "value": "true" \ }, { \ "op": "remove", \ "path": "/canarySettings/stageVariableOverrides/var1" \ }, { \ "op": "replace", \ "path": "/canarySettings/stageVariableOverrides/newVar", \ "value": "newVal" \ }, { \ "op": "replace", \ "path": "/canarySettings/stageVariableOverrides/val2", \ "value": "val4" \ }]'

Update a Canary Release Using the API Gateway REST API

To enable or disable the use of a stage cache for the canary, call stage:update as follows:

Copy
PATCH /restapis/{rest-api-id}/stages/{stage-name} { "patchOperations": [{ "op": "replace", "path": "/canarySettings/useStageCache", "value: "true" }] }

To adjust the canary traffic percentage, call stage:update to replace the /canarySettings/percentTraffic value on the stage.

Copy
PATCH /restapis/{rest-api-id}/stages/{stage-name} { "patchOperations": [{ "op": "replace", "path": "/canarySettings/percentTraffic", "value": "25.0" }] }

To update canary stage variables, including adding, changing, or removing the canary stage variable, use the following example:

Copy
PATCH /restapis/{rest-api-id}/stages/{stage-name} { "patchOperations": [{ "op": "replace", "path": "/canarySettings/stageVariableOverrides/newVar", "value": "newVal" }, { "op": "replace", "path": "/canarySettings/stageVariableOverrides/var2", "value": "val4" }, { "op": "remove", "path": "/canary/overriddenStageVariables/var1", }] }

You can combine all of the above operations into a single PATCH request.