Skip to content

Commit b338fee

Browse files
gambol99gambol99
committed
docs: updating the docs
1 parent 97e8435 commit b338fee

File tree

1 file changed

+91
-2
lines changed

1 file changed

+91
-2
lines changed

‎modules/role/README.md

+91-2
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,93 @@
11
# AWS IAM OIDC Trust Role
22

3+
## Description
4+
5+
This module creates an two IAM roles with trust relationships to an OIDC provider. One role is read-only and the other is read-write. The read-only role is intended to be used by CI/CD pipelines to validate pull requests and changes, where as the read-write role applies the changes on the merge to main. In all cases the consumer must pass a IAM boundary policy to ensure that the roles are not able to escalate their permissions, or make changes to critical resources.
6+
7+
## Update Documentation
8+
9+
The `terraform-docs` utility is used to generate this README. Follow the below steps to update:
10+
11+
1. Make changes to the `.terraform-docs.yml` file
12+
2. Fetch the `terraform-docs` binary (https://terraform-docs.io/user-guide/installation/)
13+
3. Run `terraform-docs markdown table --output-file ${PWD}/README.md --output-mode inject .`
14+
15+
## Requirements
16+
17+
| Name | Version |
18+
| ------------------------------------------------------------------------ | ------- |
19+
| <a name="requirement_terraform"></a> [terraform](#requirement_terraform) | >= 1.0 |
20+
21+
## Providers
22+
23+
| Name | Version |
24+
| ------------------------------------------------ | ------- |
25+
| <a name="provider_aws"></a> [aws](#provider_aws) | n/a |
26+
27+
## Modules
28+
29+
No modules.
30+
31+
## Resources
32+
33+
| Name | Type |
34+
| ------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------- |
35+
| [aws_iam_policy.tfstate_apply](https://registry.terraform.io/providers/hashicorp/aws/latest/docs/resources/iam_policy) | resource |
36+
| [aws_iam_policy.tfstate_plan](https://registry.terraform.io/providers/hashicorp/aws/latest/docs/resources/iam_policy) | resource |
37+
| [aws_iam_policy.tfstate_remote](https://registry.terraform.io/providers/hashicorp/aws/latest/docs/resources/iam_policy) | resource |
38+
| [aws_iam_role.ro](https://registry.terraform.io/providers/hashicorp/aws/latest/docs/resources/iam_role) | resource |
39+
| [aws_iam_role.rw](https://registry.terraform.io/providers/hashicorp/aws/latest/docs/resources/iam_role) | resource |
40+
| [aws_iam_role.sr](https://registry.terraform.io/providers/hashicorp/aws/latest/docs/resources/iam_role) | resource |
41+
| [aws_iam_role_policy_attachment.ro](https://registry.terraform.io/providers/hashicorp/aws/latest/docs/resources/iam_role_policy_attachment) | resource |
42+
| [aws_iam_role_policy_attachment.rw](https://registry.terraform.io/providers/hashicorp/aws/latest/docs/resources/iam_role_policy_attachment) | resource |
43+
| [aws_iam_role_policy_attachment.tfstate_apply](https://registry.terraform.io/providers/hashicorp/aws/latest/docs/resources/iam_role_policy_attachment) | resource |
44+
| [aws_iam_role_policy_attachment.tfstate_plan](https://registry.terraform.io/providers/hashicorp/aws/latest/docs/resources/iam_role_policy_attachment) | resource |
45+
| [aws_iam_role_policy_attachment.tfstate_remote](https://registry.terraform.io/providers/hashicorp/aws/latest/docs/resources/iam_role_policy_attachment) | resource |
46+
| [aws_caller_identity.current](https://registry.terraform.io/providers/hashicorp/aws/latest/docs/data-sources/caller_identity) | data source |
47+
| [aws_iam_openid_connect_provider.this](https://registry.terraform.io/providers/hashicorp/aws/latest/docs/data-sources/iam_openid_connect_provider) | data source |
48+
| [aws_iam_policy_document.base](https://registry.terraform.io/providers/hashicorp/aws/latest/docs/data-sources/iam_policy_document) | data source |
49+
| [aws_iam_policy_document.dynamo](https://registry.terraform.io/providers/hashicorp/aws/latest/docs/data-sources/iam_policy_document) | data source |
50+
| [aws_iam_policy_document.ro](https://registry.terraform.io/providers/hashicorp/aws/latest/docs/data-sources/iam_policy_document) | data source |
51+
| [aws_iam_policy_document.rw](https://registry.terraform.io/providers/hashicorp/aws/latest/docs/data-sources/iam_policy_document) | data source |
52+
| [aws_iam_policy_document.sr](https://registry.terraform.io/providers/hashicorp/aws/latest/docs/data-sources/iam_policy_document) | data source |
53+
| [aws_iam_policy_document.tfstate_apply](https://registry.terraform.io/providers/hashicorp/aws/latest/docs/data-sources/iam_policy_document) | data source |
54+
| [aws_iam_policy_document.tfstate_plan](https://registry.terraform.io/providers/hashicorp/aws/latest/docs/data-sources/iam_policy_document) | data source |
55+
| [aws_iam_policy_document.tfstate_remote](https://registry.terraform.io/providers/hashicorp/aws/latest/docs/data-sources/iam_policy_document) | data source |
56+
| [aws_region.current](https://registry.terraform.io/providers/hashicorp/aws/latest/docs/data-sources/region) | data source |
57+
58+
## Inputs
59+
60+
| Name | Description | Type | Default | Required |
61+
| ------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------- | :------: |
62+
| <a name="input_additional_audiences"></a> [additional_audiences](#input_additional_audiences) | Additional audiences to be allowed in the OIDC federation mapping | `list(string)` | `[]` | no |
63+
| <a name="input_common_provider"></a> [common_provider](#input_common_provider) | The name of a common OIDC provider to be used as the trust for the role | `string` | `""` | no |
64+
| <a name="input_custom_provider"></a> [custom_provider](#input_custom_provider) | An object representing an `aws_iam_openid_connect_provider` resource | <pre>object({<br> url = string<br> audiences = list(string)<br> subject_reader_mapping = string<br> subject_branch_mapping = string<br> subject_tag_mapping = string<br> })</pre> | `null` | no |
65+
| <a name="input_description"></a> [description](#input_description) | Description of the role being created | `string` | n/a | yes |
66+
| <a name="input_force_detach_policies"></a> [force_detach_policies](#input_force_detach_policies) | Flag to force detachment of policies attached to the IAM role. | `bool` | `null` | no |
67+
| <a name="input_name"></a> [name](#input_name) | Name of the role to create | `string` | n/a | yes |
68+
| <a name="input_permission_boundary_arn"></a> [permission_boundary_arn](#input_permission_boundary_arn) | The ARN of the policy that is used to set the permissions boundary for the IAM role | `string` | `null` | no |
69+
| <a name="input_protected_branch"></a> [protected_branch](#input_protected_branch) | The name of the protected branch under which the read-write role can be assumed | `string` | `"main"` | no |
70+
| <a name="input_protected_tag"></a> [protected_tag](#input_protected_tag) | The name of the protected tag under which the read-write role can be assume | `string` | `"*"` | no |
71+
| <a name="input_read_only_inline_policies"></a> [read_only_inline_policies](#input_read_only_inline_policies) | Inline policies map with policy name as key and json as value. | `map(string)` | `{}` | no |
72+
| <a name="input_read_only_max_session_duration"></a> [read_only_max_session_duration](#input_read_only_max_session_duration) | The maximum session duration (in seconds) that you want to set for the specified role | `number` | `null` | no |
73+
| <a name="input_read_only_policy_arns"></a> [read_only_policy_arns](#input_read_only_policy_arns) | List of IAM policy ARNs to attach to the read-only role | `list(string)` | `[]` | no |
74+
| <a name="input_read_write_inline_policies"></a> [read_write_inline_policies](#input_read_write_inline_policies) | Inline policies map with policy name as key and json as value. | `map(string)` | `{}` | no |
75+
| <a name="input_read_write_max_session_duration"></a> [read_write_max_session_duration](#input_read_write_max_session_duration) | The maximum session duration (in seconds) that you want to set for the specified role | `number` | `null` | no |
76+
| <a name="input_read_write_policy_arns"></a> [read_write_policy_arns](#input_read_write_policy_arns) | List of IAM policy ARNs to attach to the read-write role | `list(string)` | `[]` | no |
77+
| <a name="input_repository"></a> [repository](#input_repository) | List of repositories to be allowed i nthe OIDC federation mapping | `string` | n/a | yes |
78+
| <a name="input_role_path"></a> [role_path](#input_role_path) | Path under which to create IAM role. | `string` | `null` | no |
79+
| <a name="input_shared_repositories"></a> [shared_repositories](#input_shared_repositories) | List of repositories to provide read access to the remote state | `list(string)` | `[]` | no |
80+
| <a name="input_tags"></a> [tags](#input_tags) | Tags to apply resoures created by this module | `map(string)` | `{}` | no |
81+
82+
## Outputs
83+
84+
| Name | Description |
85+
| ----------------------------------------------------------------------- | ----------- |
86+
| <a name="output_read_only"></a> [read_only](#output_read_only) | n/a |
87+
| <a name="output_read_write"></a> [read_write](#output_read_write) | n/a |
88+
| <a name="output_state_reader"></a> [state_reader](#output_state_reader) | n/a |
89+
90+
<!-- BEGIN_TF_DOCS -->
391
## Requirements
492

593
| Name | Version |
@@ -53,7 +141,7 @@ No modules.
53141
| <a name="input_description"></a> [description](#input\_description) | Description of the role being created | `string` | n/a | yes |
54142
| <a name="input_force_detach_policies"></a> [force\_detach\_policies](#input\_force\_detach\_policies) | Flag to force detachment of policies attached to the IAM role. | `bool` | `null` | no |
55143
| <a name="input_name"></a> [name](#input\_name) | Name of the role to create | `string` | n/a | yes |
56-
| <a name="input_permission_boundary_arn"></a> [permission\_boundary\_arn](#input\_permission\_boundary\_arn) | The ARN of the policy that is used to set the permissions boundary for the IAM role | `string` | `null` | no |
144+
| <a name="input_permission_boundary"></a> [permission\_boundary](#input\_permission\_boundary) | The name of the policy that is used to set the permissions boundary for the IAM role | `string` | n/a | yes |
57145
| <a name="input_protected_branch"></a> [protected\_branch](#input\_protected\_branch) | The name of the protected branch under which the read-write role can be assumed | `string` | `"main"` | no |
58146
| <a name="input_protected_tag"></a> [protected\_tag](#input\_protected\_tag) | The name of the protected tag under which the read-write role can be assume | `string` | `"*"` | no |
59147
| <a name="input_read_only_inline_policies"></a> [read\_only\_inline\_policies](#input\_read\_only\_inline\_policies) | Inline policies map with policy name as key and json as value. | `map(string)` | `{}` | no |
@@ -65,7 +153,7 @@ No modules.
65153
| <a name="input_repository"></a> [repository](#input\_repository) | List of repositories to be allowed i nthe OIDC federation mapping | `string` | n/a | yes |
66154
| <a name="input_role_path"></a> [role\_path](#input\_role\_path) | Path under which to create IAM role. | `string` | `null` | no |
67155
| <a name="input_shared_repositories"></a> [shared\_repositories](#input\_shared\_repositories) | List of repositories to provide read access to the remote state | `list(string)` | `[]` | no |
68-
| <a name="input_tags"></a> [tags](#input\_tags) | Tags to apply resoures created by this module | `map(string)` | `{}` | no |
156+
| <a name="input_tags"></a> [tags](#input\_tags) | Tags to apply resoures created by this module | `map(string)` | n/a | yes |
69157

70158
## Outputs
71159

@@ -74,3 +162,4 @@ No modules.
74162
| <a name="output_read_only"></a> [read\_only](#output\_read\_only) | n/a |
75163
| <a name="output_read_write"></a> [read\_write](#output\_read\_write) | n/a |
76164
| <a name="output_state_reader"></a> [state\_reader](#output\_state\_reader) | n/a |
165+
<!-- END_TF_DOCS -->

0 commit comments

Comments
 (0)