From d0955d00ecd6293d0360798d3cb0ed80de156683 Mon Sep 17 00:00:00 2001 From: gracelu0 Date: Thu, 25 Apr 2024 14:21:28 -0700 Subject: [PATCH] Update readme and revert to stageName property --- ...estapi-import-deployment-stage.assets.json | 4 +-- ...tapi-import-deployment-stage.template.json | 2 +- .../manifest.json | 13 ++++++++-- .../integ.restapi.import-deploymentstage.ts | 6 +---- packages/aws-cdk-lib/aws-apigateway/README.md | 26 ++++++++++++++----- 5 files changed, 34 insertions(+), 17 deletions(-) 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..872628ace4441 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": { + "3bd472ac3fdbd7c291e3c4ef13df0429da6c1e0717dde5b304790b77637a72c3": { "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": "3bd472ac3fdbd7c291e3c4ef13df0429da6c1e0717dde5b304790b77637a72c3.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..8478cc7befcd1 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": { + "MyManualDeployment92F2175C6f3141cef1e8fea8ab3b3b8bc90df36d": { "Type": "AWS::ApiGateway::Deployment", "Properties": { "RestApiId": { 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..1193124952547 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}/3bd472ac3fdbd7c291e3c4ef13df0429da6c1e0717dde5b304790b77637a72c3.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": "MyManualDeployment92F2175C6f3141cef1e8fea8ab3b3b8bc90df36d" } ], "/integtest-restapi-import-deployment-stage/BootstrapVersion": [ @@ -63,6 +63,15 @@ "type": "aws:cdk:logicalId", "data": "CheckBootstrapVersion" } + ], + "MyManualDeployment92F2175C35a2644115e0765ad867f11b599a51c1": [ + { + "type": "aws:cdk:logicalId", + "data": "MyManualDeployment92F2175C35a2644115e0765ad867f11b599a51c1", + "trace": [ + "!!DESTRUCTIVE_CHANGES: WILL_DESTROY" + ] + } ] }, "displayName": "integtest-restapi-import-deployment-stage" 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..ab831188702b9 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,20 +7,16 @@ 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'); // Manually create a deployment that deploys to an existing stage -const deployment = new apigateway.Deployment(stack, 'MyManualDeployment', { +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 59036880bd97d..6534c53ef0ff7 100644 --- a/packages/aws-cdk-lib/aws-apigateway/README.md +++ b/packages/aws-cdk-lib/aws-apigateway/README.md @@ -270,7 +270,7 @@ The following example uses sets up two Resources '/pets' and '/books' in separat > **Warning:** In the code above, an API Gateway deployment is created during the initial CDK deployment. However, if there are changes to the resources in subsequent CDK deployments, a new API Gateway deployment is not automatically created. As a result, the latest state of the resources is not reflected. To ensure the latest state -of the resources is reflected, a manual deployment of the API Gateway is required after the CDK deployment. +of the resources is reflected, a manual deployment of the API Gateway is required after the CDK deployment. See [Controlled triggering of deployments](#controlled-triggering-of-deployments) for more info. ## Integration Targets @@ -941,7 +941,7 @@ Instructions for configuring your trust store can be found [here](https://aws.am By default, the `RestApi` construct will automatically create an API Gateway [Deployment] and a "prod" [Stage] which represent the API configuration you defined in your CDK app. This means that when you deploy your app, your API will -be have open access from the internet via the stage URL. +have open access from the internet via the stage URL. The URL of your API can be obtained from the attribute `restApi.url`, and is also exported as an `Output` from your stack, so it's printed when you `cdk @@ -1004,7 +1004,7 @@ const api = new apigateway.RestApi(this, 'books', { 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. +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. If you update the `stageName` property, you should be triggering a new deployment (i.e. with an updated logical ID). To ensure your deployment reflects changes to the `RestApi` model, see [Controlled triggering of deployments](#controlled-triggering-of-deployments). ```ts const restApi = new apigateway.RestApi(this, 'my-api', { deploy: false, @@ -1014,16 +1014,28 @@ const restApi = new apigateway.RestApi(this, 'my-api', { 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()}`); - ``` 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. +### Controlled triggering of deployments + +By default, the `RestApi` construct deploys changes immediately. If you want to +control when deployments happen, set `{ deploy: false }` and create a `Deployment` construct yourself. Add a revision counter to the construct ID, and update it in your source code whenever you want to trigger a new deployment: +```ts +const restApi = new apigateway.RestApi(this, 'my-api', { + deploy: false, +}); + +const deploymentRevision = 5; // Bump this counter to trigger a new deployment +new apigateway.Deployment(this, `Deployment${deploymentRevision}`, { + api: restApi +}); +``` + ### Deep dive: Invalidation of deployments API Gateway deployments are an immutable snapshot of the API. This means that we