[Proposal] Add required AWS permissions to resource documentation

[breathingdust]

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 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
• If you are interested in working on this issue or have submitted a pull request, please leave a comment
• The resources and data sources in this provider are generated from the CloudFormation schema, so they can only support the actions that the underlying schema supports. For this reason submitted bugs should be limited to defects in the generation and runtime code of the provider. Customizing behavior of the resource, or noting a gap in behavior are not valid bugs and should be submitted as enhancements to AWS via the CloudFormation Open Coverage Roadmap.

Description

The CloudFormation schema includes a list of permission required for each of its update handlers. This could be included in the documentation to directly understand what specific permissions are required without having to refer back to the AWS documentation.

The schema separates the permissions per handler type (Create/Read/Update/Delete/List). This separation likely doesn't make sense to include in the documentation, as the Terraform resource will need all of them to be able to manage all of its attribute. We should instead represent this as a single list deduplicating where necessary.

Using the following example from AWS_AccessAnalyzer_Analyzer.json

  "handlers": {
    "create": {
      "permissions": [
        "access-analyzer:CreateAnalyzer",
        "access-analyzer:TagResource",
        "iam:CreateServiceLinkedRole",
        "organizations:ListAWSServiceAccessForOrganization",
        "organizations:ListDelegatedAdministrators"
      ]
    },
    "read": {
      "permissions": [
        "access-analyzer:ListAnalyzers",
        "access-analyzer:GetAnalyzer",
        "access-analyzer:ListArchiveRules"
      ]
    },
    "update": {
      "permissions": [
        "access-analyzer:CreateArchiveRule",
        "access-analyzer:DeleteArchiveRule",
        "access-analyzer:ListAnalyzers",
        "access-analyzer:TagResource",
        "access-analyzer:UntagResource",
        "access-analyzer:UpdateArchiveRule"
      ]
    },
    "delete": {
      "permissions": [
        "access-analyzer:DeleteAnalyzer"
      ]
    },
    "list": {
      "permissions": [
        "access-analyzer:ListAnalyzers"
      ]
    }

We could represent the above in a separate "Permissions" heading in the resource documentation similar to the following:

Permissions

The following permissions are required for full management of this resource.

• "access-analyzer:CreateAnalyzer"
• "access-analyzer:ListAnalyzers"
• "access-analyzer:GetAnalyzer"
• "access-analyzer:DeleteAnalyzer"
• "access-analyzer:ListArchiveRules"
• "access-analyzer:CreateArchiveRule"
• "access-analyzer:UpdateArchiveRule"
• "access-analyzer:DeleteArchiveRule"
• "access-analyzer:TagResource"
• "access-analyzer:UntagResource"
• "iam:CreateServiceLinkedRole"
• "organizations:ListAWSServiceAccessForOrganization"
• "organizations:ListDelegatedAdministrators"

From an implementation point of view, this would require us being able to supply the documentation generation framework with this information, which would be enabled by #2024 if accepted.

Data-source permissions would be selected from the List/Read set of permissions.