Update a canary release - Amazon API Gateway
Update a canary release using the API Gateway consoleUpdate a canary release using the AWS CLI

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:

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