Select your cookie preferences

We use essential cookies and similar tools that are necessary to provide our site and services. We use performance cookies to collect anonymous statistics, so we can understand how customers use our site and make improvements. Essential cookies cannot be deactivated, but you can choose “Customize” or “Decline” to decline performance cookies.

If you agree, AWS and approved third parties will also use cookies to provide useful site features, remember your preferences, and display relevant content, including relevant advertising. To accept or decline all non-essential cookies, choose “Accept” or “Decline.” To make more detailed choices, choose “Customize.”

Update a canary release

Focus mode
Update a canary release - Amazon API Gateway

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:

To update existing canary settings
  1. Sign in to the API Gateway console and choose an existing REST API.

  2. In the main navigation pane, choose Stages, and then choose an existing stage.

  3. Choose the Canary tab, and then choose Edit. You might need to choose the right arrow button to show the Canary tab.

  4. Update the Request distribution by increasing or decreasing the percentage number between 0.0 and 100.0, inclusive.

  5. Select or clear the Stage cache the check box.

  6. Add, remove, or modify Canary stage variables.

  7. Choose Save.

Update a canary release using the AWS CLI

To use the AWS CLI to update a canary, use the update-stage command and modify the patch operation for each parameter of the canary.

The following update-stage command updates if the canary uses the stage cache:

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

The following update-stage command updates the canary traffic percentage:

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

The following update-stage updates stage variables. The example shows how to create a new stage variable named newVar, override the var2 stage variable, and remove the var1 stage variable:

aws apigateway update-stage \ --rest-api-id {rest-api-id} \ --stage-name '{stage-name}' \ --patch-operations '[{ "op": "replace", "path": "/canarySettings/stageVariableOverrides/newVar", "value": "newVal" }, { "op": "replace", "path": "/canarySettings/stageVariableOverrides/var2", "value": "val4" }, { "op": "remove", "path": "/canarySettings/stageVariableOverrides/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": "/canarySettings/percentTraffic", "value": "20.0" }, { "op": "replace", "path": "/canarySettings/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" }]'

PrivacySite termsCookie preferences
© 2025, Amazon Web Services, Inc. or its affiliates. All rights reserved.