Provide a recommended way to work with Role Policies

[t0yv0]

Hello!

• Vote on this issue by adding a 👍 reaction
• If you want to implement this feature, comment to let us know (we'll work with you on design, scheduling, etc.)

Issue details

Currently there are warnings on https://www.pulumi.com/registry/packages/aws/api-docs/iam/rolepolicyattachment/ and unexpected behavior of using that with aws.iam.PolicyAttachment. Having multiple ways to manage policies and roles is confusing to new users especially since our documentation and warnings/ runtime behavior do not steer to one recommended choice.

Quote:

NOTE: The usage of this resource conflicts with the aws.iam.PolicyAttachment resource and will permanently show a difference if both are defined.
NOTE: For a given role, this resource is incompatible with using the aws.iam.Role resource managed_policy_arns argument. When using that argument and this resource, both will attempt to manage the role’s managed policy attachments and Pulumi will show a permanent difference.

The task here is to figure out the recommended way to manage this infrastructure, and support users migrating to the recommended way with a combination of docs, deprecation and enhanced warnings.

Affected area/feature

[t0yv0]

Related: #2246