docs(apigateway): add warning about split stack technique

[engineer-taro]

Issue #29690

Closes #29690

Reason for this change

Regarding the stack separation of RestApi and Resource, there is no documentation about the fact that Deployment is not automatically created. When I actually add resources to the code documented and try cdk deploy for the second time and beyond, a new deployment is not created, and the latest resources are not reflected.

Description of changes

I added a note and related links to the documentation.

Description of how you validated changes

Nothing. It is just to change the description.

Checklist

• My code adheres to the CONTRIBUTING GUIDE and DESIGN GUIDELINES

---

By submitting this pull request, I confirm that my contribution is made under the terms of the Apache-2.0 license

[aws-cdk-automation]

The pull request linter has failed. See the aws-cdk-automation comment below for failure reasons. If you believe this pull request should receive an exemption, please comment and provide a justification.

A comment requesting an exemption should contain the text Exemption Request. Additionally, if clarification is needed add Clarification Request to a comment.

✅ Updated pull request passes all PRLinter validations. Dismissing previous PRLinter review.

[go-to-k]

Thanks for this PR! I made some comments.

[go-to-k]

With this sentence, it may appear that a deployment will not be created even once... (But it will be created the first time.)

It would be also good to add a note that it needs to be deployed manually to reflect the latest resources.

And I think the Deployment might be good to be a lower case because it didn't seem to refer to the CDK resource (construct) name. (If you are referring to the CDK construct name Deployment, it would be better to enclose them in back quotation marks.)

Suggested change

	> **Warning:** With the above code, no Deployment is created even if there are changes to the resources, and the latest resources are not reflected.
	> **Warning:** With the above code, no deployment is created even if there are changes to the resources, and the latest resources are not reflected.

[go-to-k]

If we provide a workaround of using Deployment.addToLogicalId(), it might be good to provide example code.

And added automatically here, because I wrote above that a deployment needs to be done manually.

Suggested change

	To create a Deployment, you need to use [`Deployment.addToLogicalId()`](https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.aws_apigateway.Deployment.html#addwbrtowbrlogicalwbriddata).
	To create a deployment automatically, you need to use [`Deployment.addToLogicalId()`](https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.aws_apigateway.Deployment.html#addwbrtowbrlogicalwbriddata).

[go-to-k]

This may not be necessary.

#29691 (comment)

[go-to-k]

The reason I asked you to write specific workarounds in the above threads is because I thought that just posting the link in question would not be enough for users to know what to do.

If we write the workarounds, do we need to post the issue link here? Is there more information packed into the issue than that? (It's already closed, so just posting the link may cause users to close the page. If you want to include it, it might be a good idea to tell them what they should look for.)

[go-to-k]

(Is this a bug in the first place...? If it is a bug that needs to be resolved, perhaps the best course of action is to open a new issue and work on it. If it's not a bug, then I'm not sure, but maybe there's no need to post a link to the issue here...)

[engineer-taro]

@go-to-k

Thank you very much for the detailed review. It is challenging to determine whether this is a bug, as similar issues have been raised multiple times in the past. In those cases, workarounds have been shared, and the issues have either been closed or remain unresolved due to the time required to address them.

The reason why the deployment is not created is that the object obtained by RestApi.fromRestApiAttributes() does not have dynamic attributes such as latestDaployment.

Reference Issues:

• (aws-apigateway): RestApi imported with method fromRestApiAttributes not updating current deployment in stage #13526 (comment)
• (apigateway): support deployment salting for imported RestApi #12417 (comment)

The concern is that developers considering stack splitting may find it difficult to discover this problem.

The current issue with the documentation is that it shares the implementation of stack splitting where automatic deployment is not performed. Would it be appropriate to add the implementation of Deployment.addToLogicalId to the sample code?
However, even with this implementation, the issue of creating the deployment at the appropriate timing remains.

class DeployStack extends NestedStack {
  constructor(scope: Construct, props: DeployStackProps) {
    super(scope, 'integ-restapi-import-DeployStack', props);

    const deployment = new Deployment(this, 'Deployment', {
      api: RestApi.fromRestApiId(this, 'RestApi', props.restApiId),
    });
    if (props.methods) {
      for (const method of props.methods) {
        deployment.node.addDependency(method);
      }
    }
    const logicalId = // salted id
    deployment.addToLogicalId(logicalId)
    new Stage(this, 'Stage', { deployment });
  }
}

Alternatively, if this is a long-standing issue, should we wait for a resolution, even though the timeline is uncertain?

[go-to-k]

Thanks for clearing.

Would it be appropriate to add the implementation of Deployment.addToLogicalId to the sample code?
However, even with this implementation, the issue of creating the deployment at the appropriate timing remains.

I'm not sure, if the implementation is incomplete and remains the another issue, it may not be appropriate to recommend it... It would also be helpful to just state that deployment must be done manually when resources are changed. I think it's important to write only what we know completely.

Alternatively, if this is a long-standing issue, should we wait for a resolution, even though the timeline is uncertain?

I don't see the need to wait all, as there is no guarantee that the solution will be found, and in the meantime, there will be new users who will be in trouble.

[engineer-taro]

@go-to-k

Thank you for your review.
I have made the following changes. I would appreciate it if you could check them when you have time.

• I have noted that an API Gateway deployment is created during the initial deployment.
• I have omitted mentioning the incomplete implementation of addToLogicalId.
• I have noted that manual deployment is necessary after the second and subsequent CDK deployments.

[go-to-k]

Thanks for your changes. I have one last comment. I will approve this as soon as it is done.

[go-to-k]

It is good to insert line breaks at visually appropriate places in the document. (We can feel relief that these line breaks are not applied when they are actually displayed in the browser.)

Suggested change

	> **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.
	> **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.

[engineer-taro]

@go-to-k
Thank you! Made corrections!

[go-to-k]

Thank you! Looks good to me.

[mergify]

Thank you for contributing! Your pull request will be updated from main and then merged automatically (do not update manually, and be sure to allow changes to be pushed to your fork).

[aaythapa]

@mergify update

Pull request has been modified.

[mergify]

update

☑️ Nothing to do

• #commits-behind>0 [📌 update requirement]
• -closed [📌 update requirement]
• -conflict [📌 update requirement]
• queue-position=-1 [📌 update requirement]

[aws-cdk-automation]

AWS CodeBuild CI Report

• CodeBuild project: AutoBuildv2Project1C6BFA3F-wQm2hXv2jqQv
• Commit ID: a34c249
• Result: SUCCEEDED
• Build Logs (available for 30 days)

Powered by github-codebuild-logs, available on the AWS Serverless Application Repository

[mergify]

Thank you for contributing! Your pull request will be updated from main and then merged automatically (do not update manually, and be sure to allow changes to be pushed to your fork).

[aws-cdk-automation]

Comments on closed issues and PRs are hard for our team to see. If you need help, please open a new issue that references this one.