diff --git a/packages/@aws-cdk-testing/framework-integ/test/aws-apigateway/test/integ.restapi.import-deploymentstage.ts b/packages/@aws-cdk-testing/framework-integ/test/aws-apigateway/test/integ.restapi.import-deploymentstage.ts index 94a819f1561bd..dc92e5ef6d4ae 100644 --- a/packages/@aws-cdk-testing/framework-integ/test/aws-apigateway/test/integ.restapi.import-deploymentstage.ts +++ b/packages/@aws-cdk-testing/framework-integ/test/aws-apigateway/test/integ.restapi.import-deploymentstage.ts @@ -5,17 +5,22 @@ import * as integ from '@aws-cdk/integ-tests-alpha'; const app = new cdk.App(); const stack = new cdk.Stack(app, 'integtest-restapi-import-deployment-stage'); +// Set deploy to false so RestApi does not automatically create a Deployment const api = new apigateway.RestApi(stack, 'my-api', { + retainDeployments: true, deploy: false, }); api.root.addMethod('GET'); -// Create a new deployment that uses existing stage -new apigateway.Deployment(stack, 'MyManualDeployment', { +// Manually create a deployment that deploys to an existing stage +const deployment = new apigateway.Deployment(stack, 'MyManualDeployment', { api: api, stageName: 'myStage', }); +// Generate a new logical ID so the deployment reflects changes made to api +deployment.addToLogicalId(`Deployment-${Date.now()}`); + new integ.IntegTest(app, 'restapi-import-deployment-stage', { testCases: [stack], }); diff --git a/packages/aws-cdk-lib/aws-apigateway/README.md b/packages/aws-cdk-lib/aws-apigateway/README.md index aaa9d211226d1..8a0c9113f1a4a 100644 --- a/packages/aws-cdk-lib/aws-apigateway/README.md +++ b/packages/aws-cdk-lib/aws-apigateway/README.md @@ -997,19 +997,27 @@ const api = new apigateway.RestApi(this, 'books', { ``` ### Deploying to an existing stage -If you want to use an existing stage for a deployment, you can specify the stage name in the deployment as follows: +If you want to use an existing stage for a deployment, first set `{ deploy: false }` so that `RestApi` does not automatically create new `Deployment` and `Stage` resources. Then you can manually define a `apigateway.Deployment` resource and specify the stage name for your existing stage using the `stageName` property. + +Note that as long as the deployment's logical ID doesn't change, it will represent the snapshot in time when the resource was created. To ensure your deployment reflects changes to the `RestApi` model, use the method `addToLogicalId(data)` to augment the logical ID generated for the deployment resource. ```ts const restApi = new apigateway.RestApi(this, 'my-api', { deploy: false, }); +// Use `stageName` to deploy to an existing stage const deployment = new apigateway.Deployment(this, 'my-deployment', { api: restApi, stageName: 'dev', }); +// Generate a new logical ID so the deployment reflects changes made to api +deployment.addToLogicalId(`Deployment-${Date.now()}`); + ``` +If the `stageName` property is set but a stage with the corresponding name does not exist, a new stage +resource will be created with the provided stage name. ### Deep dive: Invalidation of deployments diff --git a/packages/aws-cdk-lib/aws-apigateway/lib/deployment.ts b/packages/aws-cdk-lib/aws-apigateway/lib/deployment.ts index 42670161e340f..c245f82769110 100644 --- a/packages/aws-cdk-lib/aws-apigateway/lib/deployment.ts +++ b/packages/aws-cdk-lib/aws-apigateway/lib/deployment.ts @@ -30,7 +30,9 @@ export interface DeploymentProps { /** * The name of the stage the API Gateway deployment deploys to. * - * @default - No stage name. + * @default - No stage name. If the `stageName` property is set but a stage with the + * corresponding name does not exist, a new stage resource will be created with the + * provided stage name. */ readonly stageName?: string; } @@ -69,10 +71,9 @@ export class Deployment extends Resource { /** @attribute */ public readonly deploymentId: string; public readonly api: IRestApi; - /** - * The stage of the API Gateway deployment. - */ + * The stage of the API gateway deployment. + */ public readonly stageName?: string; private readonly resource: LatestDeploymentResource;