[Docs]: aws_cloudformation_stack_instances vs aws_cloudformation_stack_set_instance

[aristosvo]

Documentation Link

https://registry.terraform.io/providers/hashicorp/aws/latest/docs/resources/cloudformation_stack_set

Description

The documentation on both the aws_cloudformation_stack_instances and aws_cloudformation_stack_set_instance resource aren't clear about the relationship/features distinguishing the two.

It seems aws_cloudformation_stack_instances is the newest one and should solve the issues with aws_cloudformation_stack_set_instance, but it isn't propagated as the successor, while the functionality is really closely related.

Also questionable is the naming, why not aws_cloudformation_stack_set_instances?

References

#39683
#36794

Would you like to implement a fix?

Yes, but I would probably need some input from @YakDriver on the thoughts behind the new aws_cloudformation_stack_instances resource.

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

[ericofusco]

@aristosvo Sharing my 2c but @YakDriver feel free to correct me if I'm wrong.

The rationale behind a new resource was brought up in this issue: #24752 (comment).

Basically there were too many changes and fixes that needed to happen in the existing resource that was decided to create a new one to avoid any compatibility issues.

I do think the aws_cloudformation_stack_set_instance should be deprecated in favor of the new resource.

Regarding the naming, it looks like the resource name was overlooked I'm afraid. I agree it would made more sense for the resource to be called aws_cloudformation_stack_set_instances.

[stekern]

@ericofusco I might be wrong here, but a key use-case that aws_cloudformation_stack_set_instance supports and aws_cloudformation_stack_set_instances seems to lack is the ability to specify different parameter overrides for different targets (e.g., accounts) within the same stackset.

If I were to use aws_cloudformation_stack_set_instances, and wanted parameter ExampleParameter to have the value foo for account X and value bar for account Y, I would effectively need to create two stacksets? In that case, deprecating aws_cloudformation_stack_set_instance in favor of aws_cloudformation_stack_set_instances would be a step down in functionality.