UsagePlan: No option to preserve added API stages to the usage plan if not included as part of construct instantiation

[ChaseBowen]

Describe the bug

Upon attempting to use the UsagePlan construct, it appears that the apiStages property is meant to be fully populated at deploy time. We have a use-case where we are deploying a UsagePlan and are having other microservices add their API stages/API Keys to the usage plan via the AWS SDK.

Upon re-deploying the UsagePlan, it appears to be resetting the state of the added API stages and clearing them out entirely. The API keys added are kept intact, but it appears that the API stages are fully managed by the CDK with no option to keep them intact as well similar to how the API keys are managed as part of a Usage Plan. Deployments where the logical id remains the same encounter this issue still (adding a new Tags key:value pair will reset the state of these added API stages).

There does not appear to be a way to maintain the state of these API stages that are added as part of a different process.

I looked into using the lower-level CfnUsagePlan construct, but did not see a way to accomplish this either. I am open to using this construct as well if there exists a way to do this.

Regression Issue

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

Last Known Working CDK Version

No response

Expected Behavior

The current added apiStages on the UsagePlan to be kept intact in the AWS deployed UsagePlan (or an option for this)

Current Behavior

All added API stages were removed (unexpected - unfortunate)

All added API keys stay intact (expected - good)

Reproduction Steps

Initial Deployment:

const plan = new UsagePlan(someScope, 'some-value', {
      name: 'some-name',
      quota: {
        limit: 1000,
        period: Period.DAY
      },
      throttle: {
        rateLimit: 10,
        burstLimit: 2
      }
    });

• Manually add API Stages to the UsagePlan

Second Deployment:

const plan = new UsagePlan(someScope, 'some-value', {
      name: 'some-name',
      quota: {
        limit: 1000,
        period: Period.DAY
      },
      throttle: {
        rateLimit: 10,
        burstLimit: 2
      }
    });
 Tags.of(plan).add('testAddedKey, 'testAddedValue');

• Watch as the API Stages are removed from the UsagePlan (no logical id change, apiStages solely maintained by CDK State)

Possible Solution

No response

Additional Information/Context

No response

CDK CLI Version

2.161.0 (build be5ad8b)

Framework Version

No response

Node.js Version

v20.9.0

OS

MacOS Sonoma 14.7.2

Language

TypeScript

Language Version

No response

Other information

No response

[khushail]

Hi @ChaseBowen , thanks for reaching out. AFAIU, construct deployed through CDK will be maintained and reset by CDK even if you make changes outside CDK.

In your scenario, what is happening is cdk deploys the construct, then outside changes are made and then CDK identifies the changes and reverts those back as per the syntheised template it had. So I don't think its a flaw in the CDK Process.

However CDK provides workaround for such scenario-

1. CDK Drift - cloudformation provides drift detection between deployed resources and changes done from outside CDK. but the changes you see, would have be done again by you. Here is a scenario how drift detection is implemented in cdk pipelines.
2. CDK Import - you can import the usage plan with cdk import. In such scenario, you would have to know the PlanKeyID and include it in the stack. However cdk import is experimental. Here is a guide on how to do CDK imports and resource imports

I hope this helps in your scenario. Let me know if you have questions.
Thanks

[ChaseBowen]

Hey @khushail

Sorry this may have been more of a feature request. I would like if the API stages were managed similar to how API keys are managed as part of a usage plan in terms of state. There is no apiKeys property on the UsagePlan construct, and they can only be added with plan.addApiKey() or through post-deploy means such as an SDK call. As such, the API keys associated with the usage plan are not wiped as part of an update operation.

I'm not sure that Drift Detection or CDK imports would solve the issue based on:

• Drift Detection provides no means of doing anything about the drift except for detecting it. Nothing for ensuring those stages are persistent on the usage plan.
• CDK imports may allow importing the stack into the current CDK project, but if importing the UsagePlan through the deployed resource, we will have another problem that the UsagePlan could never be updated. I'm really wanting the ability to maintaining the Usage Plan state with CDK, but making usage plan api stages act in a similar manner to that of usage plan api keys

Ideally, we could construct a new usage plan as such

// keeps existing api stages added by any means (sdk or similar)
new UsagePlan(someScope, 'some-value', { retainStages: true, ...} )


plan.addApiKey() // ADDS a new Api Key (not required by us since we wouldn't use this)
plan.addApiStage() // ADDS a new Api Stage (not required by us since we wouldn't use this)

[khushail]

@ChaseBowen , thanks for clarifcation around your usecase. So you want usagePlan to retain its stages.
I see there is a discussion around the somewhat similar topic, raised in the past for How to attach an existing usage plan to an api gateway using CDK and this comment thread has a resolution as well -#22944 (reply in thread).
However I don't see any option of preserving the API Stages. Converting this issue to FR and marking it as P2 which means it won't be immediately addressed by the team but would be on their radar. Hope that is helpful.