Docs for IAM Role collections: policies vs attached_policies

[FrancescoRizzi]

After durdling around a bit I think I understand this, and may recommend an improvement to the documentation...

Doc Change 1:
The documentation for the IAM Role collection attached_policies should read:

A list of managed policies attached to the role.

wording from AWS IAM REST API doc for RoleDetails, AttachedManagedPolicies.member.N.

Instead of:

A collection of Policy resources

Doc Change 2:
The documentation for the IAM Role collection policies should read:

A list of inline policies embedded in the role.

wording from AWS IAM REST API doc for RoleDetails, RolePolicyList.member.N.

Instead of:

A collection of RolePolicy resources

Motivation:
These changes may help someone (like me) who is looking for ways to (for instance) delete an IAM Role, which, it turns out:

• requires you to delete/detach the Role Policies first, which, it turns out:
• is done differently for inline policies (see IAM Client delete_role_policy ) and managed policies (see IAM Client detach_role_policy ), which, it turns out:
• requires you to get a list of the policies first, which you might get via ListRolePolicies Paginator (yay!), which, it turns out:
• A) returns a list of Policy Names (whereas the delete_role_policy and detach_role_policy APis require the Policy ARNs) (sad_panda), and
• B) does not expose a way to distinguish between inline and managed policies, which, it turns out:
• B1) is not exposed by the RolePolicy resource (sadder_panda), and
• B2) is not exposed by IAM Client get_role_policy either (raging_panda)

[aidanmelen]

I also fumbled through the documentation as well. Perhaps the policies attribute could be renamed to be inline_policies. As for the attached_policies call, couldn't we instead simply say managed_policies? Just a suggestion.

[jamesls]

FWIW, I agree we should get these updated. The main issue here is these are generic docs for a collection (https://github.com/boto/boto3/blob/develop/boto3/docs/collection.py#L83-L84). We'd need some way to plumb in overrides.

[donotpush]

@FrancescoRizzi you made my day with this issue. I am running into the same issue, I want to delete roles using boto3.... Let's see if I can find the solution!

[ganatradeval]

I guess I have found a solution. Uploading link here. Hope it helps someone.
https://github.com/ganatradeval/AWS-Automation/blob/master/README.md

[tim-finnigan]

Here is documentation on deleting an IAM role using AWS APIs: https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_manage_delete.html#roles-managingrole-deleting-api

The generic docs for collections are still generated here but I'm not sure to what extent those should be customized.