resource/aws_api_gateway_deployment: Deprecate 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.

Deprecate attributes with a warning that they will be removed in a future version and recommend using a aws_api_gateway_stage resource.

• stage_name
• stage_description
• canary_settings

The attributes will be removed in #39958

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.