resource/aws_api_gateway_deployment: Remove attributes that create stage

[gdavison]

Description

The resource type aws_api_gateway_deployment has three attributes, stage_name, stage_description, and canary_settings, that "silently" create a new stage that is not managed by Terraform, except that deleting the aws_api_gateway_deployment resource will also delete the stage. If stage_name refers to an existing stage, the stage will be modified.

We should prefer explicitly creating stages and assigning the deployment to the stage during creation or update. This will make it clear how the stage is managed. The ability to modify the stage using the deployment can also cause user confusion.

The attributes were deprecated in #39957 and #42244.

Remove attributes:

• stage_name
• stage_description
• canary_settings
• execution_arn
• invoke_url

Will also need to handle existing stages created by the aws_api_gateway_deployment. Possible implementation is to add a migrator that sets the stage ID as private state

Affected Resource(s) and/or Data Source(s)

• aws_api_gateway_deployment

Potential Terraform Configuration

No response

References

No response

Would you like to implement a fix?

None

[github-actions]

Community Note

Voting for Prioritization

• Please vote on this issue by adding a 👍 reaction to the original post to help the community and maintainers prioritize this request.
• Please see our prioritization guide for information on how we prioritize.
• Please do not leave "+1" or other comments that do not add relevant new information or questions, they generate extra noise for issue followers and do not help prioritize the request.

Volunteering to Work on This Issue

• If you are interested in working on this issue, please leave a comment.
• If this would be your first contribution, please review the contribution guide.

[YakDriver]

Based on our recent discussions about state upgrades, I don’t think maintaining private state to silently manage the stage is sustainable. It feels like a "deprecation of the deprecation"—kicking the can down the road until we eventually remove everything for real. In my opinion, we need to rip the bandaid off. The deprecation notice has been advising users to switch to the aws_api_gateway_stage resource for some time now.

I can add a recommendation to the upgrade guide explaining how to import the implicitly created stage into a managed aws_api_gateway_stage resource.

[YakDriver]

Closed by #42249