diff --git a/packages/@aws-cdk-testing/framework-integ/test/aws-apigateway/test/integ.restapi.import-deploymentstage.js.snapshot/integtest-restapi-import-deployment-stage.assets.json b/packages/@aws-cdk-testing/framework-integ/test/aws-apigateway/test/integ.restapi.import-deploymentstage.js.snapshot/integtest-restapi-import-deployment-stage.assets.json index 7a9d0b4b5ede4..5b4179790967a 100644 --- a/packages/@aws-cdk-testing/framework-integ/test/aws-apigateway/test/integ.restapi.import-deploymentstage.js.snapshot/integtest-restapi-import-deployment-stage.assets.json +++ b/packages/@aws-cdk-testing/framework-integ/test/aws-apigateway/test/integ.restapi.import-deploymentstage.js.snapshot/integtest-restapi-import-deployment-stage.assets.json @@ -1,7 +1,7 @@ { "version": "36.0.0", "files": { - "c3065e2b174aec5c2983ead9d08adf6eeae1a88b04f53c1f2a44224959876568": { + "1a7cdf8b4c5b047b60dd9576b5c74e4bdb4b8cac8155a39b3f08d61773c0bf87": { "source": { "path": "integtest-restapi-import-deployment-stage.template.json", "packaging": "file" @@ -9,7 +9,7 @@ "destinations": { "current_account-current_region": { "bucketName": "cdk-hnb659fds-assets-${AWS::AccountId}-${AWS::Region}", - "objectKey": "c3065e2b174aec5c2983ead9d08adf6eeae1a88b04f53c1f2a44224959876568.json", + "objectKey": "1a7cdf8b4c5b047b60dd9576b5c74e4bdb4b8cac8155a39b3f08d61773c0bf87.json", "assumeRoleArn": "arn:${AWS::Partition}:iam::${AWS::AccountId}:role/cdk-hnb659fds-file-publishing-role-${AWS::AccountId}-${AWS::Region}" } } diff --git a/packages/@aws-cdk-testing/framework-integ/test/aws-apigateway/test/integ.restapi.import-deploymentstage.js.snapshot/integtest-restapi-import-deployment-stage.template.json b/packages/@aws-cdk-testing/framework-integ/test/aws-apigateway/test/integ.restapi.import-deploymentstage.js.snapshot/integtest-restapi-import-deployment-stage.template.json index c12401dfc426d..dd31a8b983c66 100644 --- a/packages/@aws-cdk-testing/framework-integ/test/aws-apigateway/test/integ.restapi.import-deploymentstage.js.snapshot/integtest-restapi-import-deployment-stage.template.json +++ b/packages/@aws-cdk-testing/framework-integ/test/aws-apigateway/test/integ.restapi.import-deploymentstage.js.snapshot/integtest-restapi-import-deployment-stage.template.json @@ -25,7 +25,7 @@ } } }, - "MyManualDeployment92F2175C35a2644115e0765ad867f11b599a51c1": { + "MyManualDeployment92F2175Ccc11cdc8066f1062a899dd200fc12825": { "Type": "AWS::ApiGateway::Deployment", "Properties": { "RestApiId": { @@ -35,7 +35,9 @@ }, "DependsOn": [ "myapiGETF990CE3C" - ] + ], + "UpdateReplacePolicy": "Retain", + "DeletionPolicy": "Retain" } }, "Parameters": { diff --git a/packages/@aws-cdk-testing/framework-integ/test/aws-apigateway/test/integ.restapi.import-deploymentstage.js.snapshot/manifest.json b/packages/@aws-cdk-testing/framework-integ/test/aws-apigateway/test/integ.restapi.import-deploymentstage.js.snapshot/manifest.json index 43ffeac3199c5..561d6750f7ac9 100644 --- a/packages/@aws-cdk-testing/framework-integ/test/aws-apigateway/test/integ.restapi.import-deploymentstage.js.snapshot/manifest.json +++ b/packages/@aws-cdk-testing/framework-integ/test/aws-apigateway/test/integ.restapi.import-deploymentstage.js.snapshot/manifest.json @@ -18,7 +18,7 @@ "validateOnSynth": false, "assumeRoleArn": "arn:${AWS::Partition}:iam::${AWS::AccountId}:role/cdk-hnb659fds-deploy-role-${AWS::AccountId}-${AWS::Region}", "cloudFormationExecutionRoleArn": "arn:${AWS::Partition}:iam::${AWS::AccountId}:role/cdk-hnb659fds-cfn-exec-role-${AWS::AccountId}-${AWS::Region}", - "stackTemplateAssetObjectUrl": "s3://cdk-hnb659fds-assets-${AWS::AccountId}-${AWS::Region}/c3065e2b174aec5c2983ead9d08adf6eeae1a88b04f53c1f2a44224959876568.json", + "stackTemplateAssetObjectUrl": "s3://cdk-hnb659fds-assets-${AWS::AccountId}-${AWS::Region}/1a7cdf8b4c5b047b60dd9576b5c74e4bdb4b8cac8155a39b3f08d61773c0bf87.json", "requiresBootstrapStackVersion": 6, "bootstrapStackVersionSsmParameter": "/cdk-bootstrap/hnb659fds/version", "additionalDependencies": [ @@ -49,7 +49,7 @@ "/integtest-restapi-import-deployment-stage/MyManualDeployment/Resource": [ { "type": "aws:cdk:logicalId", - "data": "MyManualDeployment92F2175C35a2644115e0765ad867f11b599a51c1" + "data": "MyManualDeployment92F2175Ccc11cdc8066f1062a899dd200fc12825" } ], "/integtest-restapi-import-deployment-stage/BootstrapVersion": [ 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 dc92e5ef6d4ae..92b08dafdc75d 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 @@ -7,7 +7,6 @@ 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'); @@ -15,11 +14,12 @@ api.root.addMethod('GET'); // Manually create a deployment that deploys to an existing stage const deployment = new apigateway.Deployment(stack, 'MyManualDeployment', { api: api, - stageName: 'myStage', + retainDeployments: true, }); -// Generate a new logical ID so the deployment reflects changes made to api -deployment.addToLogicalId(`Deployment-${Date.now()}`); +// Deploy to a stage that already exists in the account +// Here we are assuming the account has a stage named 'myStage' +deployment.deployToExistingStage('myStage'); 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 59036880bd97d..4a1ffa85f4ac7 100644 --- a/packages/aws-cdk-lib/aws-apigateway/README.md +++ b/packages/aws-cdk-lib/aws-apigateway/README.md @@ -1002,27 +1002,28 @@ const api = new apigateway.RestApi(this, 'books', { ``` ### Deploying to an existing stage -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. +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 use the `deployToExistingStage()` method to specify the stage name and create a new deployment to the stage. -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. +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. The `deployToExistingStage()` method calls `addToLogicalId()` with a timestamp to create a new `Deployment` resource. This ensures your deployment reflects the latest changes to the `RestApi` model. + +By default, the previous deployment will be deleted because of the logical ID update. If you wish to retain old deployment resources when the API changes, set the `retainDeployments` property to `true`. ```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', + retainDeployments: true // keep old deployments }); -// Generate a new logical ID so the deployment reflects changes made to api -deployment.addToLogicalId(`Deployment-${Date.now()}`); +// Deploy latest RestApi changes to an existing stage +deployment.deployToExistingStage('dev'); ``` -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. +If `deployToExistingStage()` is called with a stage name that does not correspond to an existing stage, +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 c245f82769110..0f43f63ca72f1 100644 --- a/packages/aws-cdk-lib/aws-apigateway/lib/deployment.ts +++ b/packages/aws-cdk-lib/aws-apigateway/lib/deployment.ts @@ -26,15 +26,6 @@ export interface DeploymentProps { * @default false */ readonly retainDeployments?: boolean; - - /** - * The name of the stage the API Gateway deployment deploys to. - * - * @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; } /** @@ -71,10 +62,6 @@ export class Deployment extends Resource { /** @attribute */ public readonly deploymentId: string; public readonly api: IRestApi; - /** - * The stage of the API gateway deployment. - */ - public readonly stageName?: string; private readonly resource: LatestDeploymentResource; @@ -84,7 +71,6 @@ export class Deployment extends Resource { this.resource = new LatestDeploymentResource(this, 'Resource', { description: props.description, restApi: props.api, - stageName: props.stageName, }); if (props.retainDeployments) { @@ -135,6 +121,18 @@ export class Deployment extends Resource { // dependencies between the underlying CfnResources. this.node.addDependency(method.node.defaultChild as CfnResource); } + + /** + * Deploy to an existing stage. Updates the logical ID of this Deployment resource + * so it will always create a new deployment and reflect the latest API changes. + * If this Deployment resource does not have `retainDeployments` set to `true`, + * calling this method will delete the old deployment resource. + * @param stageName The name of the stage + */ + public deployToExistingStage(stageName: string) { + this.resource.stageName = stageName; + this.resource.addToLogicalId(new Date().getTime()); + } } interface LatestDeploymentResourceProps {