Documentation needs improvement (!)

[tf42src]

Trying to create a role with a "federated" principal. Seems impossible.

1. This needs an example:
   https://registry.terraform.io/modules/terraform-aws-modules/iam/aws/latest/submodules/iam-assumable-role-with-oidc

2. Trying to use it like this: resource "iam-assumable-role-with-oidc" "github_actions_eks_role" { .. }, running tf init results in:

│ Could not retrieve the list of available versions for provider hashicorp/iam-assumable-role-with-oidc: provider registry registry.terraform.io does not have a
│ provider named registry.terraform.io/hashicorp/iam-assumable-role-with-oidc

3. Same issue for resource "iam_iam-assumable-role-with-oidc" "github_actions_eks_role" { .. }

4. All links on the fields just link to itself. e.g. this one. That's not helpful.

5. Why is there a boolean variable whether to create a role or not (create_role)? The whole purpose is to create a role. Doesn't make sense to me.

6. What is the purpose of specifying the number of attached policies (number_of_role_policy_arns)? Also doesn't make sense to me. Should just count itself based on # attached policies.

7. A lot of the other fields are not self-explanatory (e.g. role_path - why is that required?). A simple example how to use would be so much more user friendly.

[tf42src]

@bryantbiggs any comment?

[bryantbiggs]

I'm not sure what to comment here - it seems like you are not familiar with some of the Terraform module norms and conventions so I would suggest first digging into the Terraform documentation and then starting to look at modules, and then module implementations (not just ours, there are many modules out there and some really well written ones on the registry)

[tf42src]

Maybe there are, but the one I am referring to [1] is not. The documentation is pretty much non-existant and what exists partially does not makes sense. Hence I think it can be improved. So why not keep this ticket open and make things better?

[1] resource "iam-assumable-role-with-oidc" "github_actions_eks_role"

[bryantbiggs]

its there https://github.com/terraform-aws-modules/terraform-aws-iam/tree/master/examples/iam-assumable-role-with-oidc

but what I think you are actually looking for is

terraform-aws-iam/examples/iam-github-oidc/main.tf

Line 37 in ef31aca

module "iam_github_oidc_role" {

[tf42src]

Thanks for the link, but I still don't see how that addresses my original points.

E.g. pick my 5. Why is there a boolean variable whether to create a role or not (create_role)? The whole purpose is to create a role. Doesn't make sense to me.

Can you explain what create_role is for?

[bryantbiggs]

It determines whether a role is created or not

[tf42src]

It determines whether a role is created or not

but the whole purpose of the module is to create a role:

https://registry.terraform.io/modules/terraform-aws-modules/iam/aws/latest/submodules/iam-assumable-role-with-oidc