aws-apigateway: Canary Deployment Settings Not Removed from Stage

[FelixWe]

Describe the bug

When using an aws_apigateway.SpecRestApi with deploy: true and deploy options configured, I set a canary deployment on the stage via:

const canaryStage = apiGateway.deploymentStage.node.defaultChild as aws_apigateway.CfnStage;
canaryStage.canarySetting = {
    deploymentId: apiGateway.latestDeployment?.deploymentId,
    percentTraffic: canaryPercentTraffic,
    stageVariableOverrides: canaryVariables
};

After deployment the Canary Configuration works as expected.
However, if I remove this configuration from the code, the canary settings are removed from the CloudFormation stack (as seen in cdk diff) but still persist in the API Gateway stage after cdk deploy.

cdk diff output

[~] AWS::ApiGateway::Stage Gateway/ApiGateway/DeploymentStage.preview GatewayApiGatewayDeploymentStagepreviewFCB0F3EC
 ├─ [-] CanarySetting
 │   └─ {"DeploymentId":{"Ref":"..."},"PercentTraffic":50,"StageVariableOverrides":{"stage":"test"}}
...

Regression Issue

• Select this option if this issue appears to be a regression.

Last Known Working CDK Version

No response

Expected Behavior

Removing the canary configuration from the CDK code should also remove the canary deployment settings from the API Gateway stage.

Current Behavior

The canary settings persist on the deployed API Gateway stage despite being removed from the stack configuration.

Reproduction Steps

• Create an aws_apigateway.SpecRestApi with deploy: true and set deploy options.
• Apply a canary configuration to the stage using the code snippet above.
• Deploy the stack.
• Remove the canary configuration from the CDK code.
• Run cdk diff (shows removal) and then cdk deploy.
• Observe that the API Gateway stage still retains the canary settings.

Possible Solution

No response

Additional Information/Context

No response

CDK CLI Version

2.1004.0

Framework Version

No response

Node.js Version

v20.17.0

OS

mac-os

Language

TypeScript

Language Version

No response

Other information

No response

[pahud]

Hello @FelixWe,

Thank you for reporting this issue. I've been able to reproduce the problem with API Gateway canary deployment settings not being removed from the stage when they're removed from the CDK code.

Reproduction confirmed with these steps:

1. Create a SpecRestApi with deploy: true
2. Apply canary settings to the stage
3. Deploy successfully
4. Remove canary settings from code
5. Run cdk diff - correctly shows removal
6. Deploy again
7. Verify canary settings still exist in API Gateway

Root cause appears to be in how CloudFormation handles removal of the CanarySetting property - it updates its own state but doesn't trigger the proper API calls to remove settings from API Gateway.

Workaround: Instead of removing canary settings entirely, set to minimal values:

canaryStage.canarySetting = {
  deploymentId: apiGateway.latestDeployment?.deploymentId,
  percentTraffic: 0, 
  stageVariableOverrides: {}
};

This keeps the property in CloudFormation but effectively disables canary deployment.

I will reach out internally to check if this is a bug on CFN or API Gateway.

[pahud]

internal tracking: V1719710246

[pahud]

This is a known bug and the team is working on it. I'll update here when I hear any new updates.