Address confusion about `allUsers` and `allAuthenticatedUsers` in IAM resource documentation

[SarahFrench]

Community Note

• Please vote on this issue by adding a 👍 reaction to the original issue to help the community and maintainers prioritize this request
• Please do not leave "+1" or "me too" comments, they generate extra noise for issue followers and do not help prioritize the request
• If you are interested in working on this issue or have submitted a pull request, please leave a comment. If the issue is assigned to the "modular-magician" user, it is either in the process of being autogenerated, or is planned to be autogenerated soon. If the issue is assigned to a user, that user is claiming responsibility for the issue. If the issue is assigned to "hashibot", a community member has claimed the issue already.

Description

Making this issue after seeing this bug report: https://github.com/hashicorp/terraform-provider-google/issues/13592

Not all services support this list of members in the docs, which is hardcoded as part of the IAM docs template (mmv1/templates/terraform/resource_iam.html.markdown.erb).

It might be useful to allow service-specific information to those generated pages, perhaps as an explicit Exceptions for [PRODUCT NAME] section . I'm not sure if there are enough exceptions to warrant this though.

See comments for recommendations about how to address this with smaller changes.

New or Affected Resource(s)

• Documentation generation for IAM resources google_*_iam

Potential Terraform Configuration

N/A

References

• Example of issue where the homogenous IAM resource documentation lead to some confusion : https://github.com/hashicorp/terraform-provider-google/issues/13592#issuecomment-1410187375
• Members argument in that resource's docs - https://registry.terraform.io/providers/hashicorp/google/latest/docs/resources/cloud_run_v2_job_iam#member/members

[SarahFrench]

I submitted this as a typical Enhancement as it changes user-facing documentation, but it requires changes to how IAM docs are generated widely in the provider and impacts other developers working on the provider

[rileykarson]

Addtl notes:

• Maybe link directly to API docs?
• Consider deemphasizing the special roles like allUsers (we're not sure how general they are)

[SarahFrench]

Also: can add example showing how to include workload identity federation in member(s) argument