Amazon API Gateway
Developer Guide

The AWS Documentation website is getting a new look!
Try it now and let us know what you think. Switch to the new look >>

You can return to the original look by selecting English in the language selector above.

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 or an AWS SDK.

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:

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.

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:

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:

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" \ }]'