Skip to content

Commit ba64b02

Browse files
larskslarsks
committed
Auto generate tf reference docs
1 parent 34d773c commit ba64b02

10 files changed

Lines changed: 306 additions & 2 deletions

File tree

‎.pre-commit-config.yaml‎

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -32,3 +32,10 @@ repos:
3232
name: check-account-ids
3333
language: script
3434
entry: ./scripts/check-account-ids.sh
35+
36+
- id: terraform-docs
37+
pass_filenames: false
38+
name: terraform-docs
39+
language: script
40+
files: \.tf$
41+
entry: ./scripts/terraform-docs-hook.sh

‎.terraform-docs.yml‎

Lines changed: 9 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,9 @@
1+
formatter: markdown table
2+
3+
output:
4+
file: REFERENCE.md
5+
mode: inject
6+
7+
sort:
8+
enabled: true
9+
by: required

‎modules/.terraform-docs.yml‎

Lines changed: 9 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,9 @@
1+
formatter: markdown table
2+
3+
output:
4+
file: README.md
5+
mode: inject
6+
7+
sort:
8+
enabled: true
9+
by: required

‎modules/bucket/README.md‎

Lines changed: 63 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,63 @@
1+
# Bucket
2+
3+
Manage AWS S3 buckets.
4+
5+
## Example usage
6+
7+
To create a simple bucket:
8+
9+
```hcl
10+
module "example_bucket" {
11+
source = "./modules/bucket"
12+
name = "example-bucket"
13+
}
14+
```
15+
16+
To create Glacier Flexible Retrieval bucket:
17+
18+
```hcl
19+
module "example_bucket" {
20+
source = "./modules/bucket"
21+
name = "example-bucket"
22+
storage_class = "GLACIER"
23+
}
24+
```
25+
26+
<!-- BEGIN_TF_DOCS -->
27+
## Requirements
28+
29+
No requirements.
30+
31+
## Providers
32+
33+
| Name | Version |
34+
| ---- | ------- |
35+
| <a name="provider_aws"></a> [aws](#provider\_aws) | n/a |
36+
37+
## Modules
38+
39+
No modules.
40+
41+
## Resources
42+
43+
| Name | Type |
44+
| ---- | ---- |
45+
| [aws_s3_bucket.this](https://registry.terraform.io/providers/hashicorp/aws/latest/docs/resources/s3_bucket) | resource |
46+
| [aws_s3_bucket_lifecycle_configuration.this](https://registry.terraform.io/providers/hashicorp/aws/latest/docs/resources/s3_bucket_lifecycle_configuration) | resource |
47+
| [aws_s3_bucket_public_access_block.this](https://registry.terraform.io/providers/hashicorp/aws/latest/docs/resources/s3_bucket_public_access_block) | resource |
48+
49+
## Inputs
50+
51+
| Name | Description | Type | Default | Required |
52+
| ---- | ----------- | ---- | ------- | :------: |
53+
| <a name="input_name"></a> [name](#input\_name) | Name of the S3 bucket | `string` | n/a | yes |
54+
| <a name="input_allow_public_access"></a> [allow\_public\_access](#input\_allow\_public\_access) | When false, block all public access to the bucket | `bool` | `false` | no |
55+
| <a name="input_storage_class"></a> [storage\_class](#input\_storage\_class) | S3 storage class for lifecycle transition (e.g. GLACIER, GLACIER\_IR, STANDARD\_IA, DEEP\_ARCHIVE). When null, no lifecycle rule is created. | `string` | `null` | no |
56+
57+
## Outputs
58+
59+
| Name | Description |
60+
| ---- | ----------- |
61+
| <a name="output_arn"></a> [arn](#output\_arn) | The ARN of the bucket |
62+
| <a name="output_id"></a> [id](#output\_id) | The name of the bucket |
63+
<!-- END_TF_DOCS -->

‎modules/github-oidc/README.md‎

Lines changed: 78 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,78 @@
1+
# GitHub OIDC
2+
3+
Manage policies to permit GitHub workflows to authenticate against AWS. For more information, see:
4+
5+
- From GitHub: [Configuring OpenID Connect in Amazon Web Services][github-oidc]
6+
- From AWS: [Use IAM roles to connect GitHub Actions to actions in AWS][aws-oidc]
7+
8+
## Example usage
9+
10+
To create the policies:
11+
12+
```hcl
13+
module "github-oidc" {
14+
source = "./modules/github-oidc"
15+
dns_policy_arn = aws_iam_policy.route53_records.arn
16+
}
17+
```
18+
19+
To configure a GitHub workflow to authenticate against AWS, create a secret `AWS_ROLE_ARN` using the value of one of the role ARNs output by this module:
20+
21+
```sh
22+
gh secret set AWS_ROLE_ARN -b arn:aws:iam::012345678901:role/github-actions-dns
23+
```
24+
25+
And then in your workflow use `aws-actions/configure-aws-credentials` to acquire credentials:
26+
27+
```yaml
28+
- uses: aws-actions/configure-aws-credentials@v4
29+
with:
30+
role-to-assume: ${{ secrets.AWS_ROLE_ARN }}
31+
aws-region: us-east-1
32+
```
33+
34+
[github-oidc]: https://docs.github.com/en/actions/how-tos/secure-your-work/security-harden-deployments/oidc-in-aws
35+
[aws-oidc]: https://aws.amazon.com/blogs/security/use-iam-roles-to-connect-github-actions-to-actions-in-aws/
36+
37+
<!-- BEGIN_TF_DOCS -->
38+
## Requirements
39+
40+
No requirements.
41+
42+
## Providers
43+
44+
| Name | Version |
45+
| ---- | ------- |
46+
| <a name="provider_aws"></a> [aws](#provider\_aws) | n/a |
47+
48+
## Modules
49+
50+
No modules.
51+
52+
## Resources
53+
54+
| Name | Type |
55+
| ---- | ---- |
56+
| [aws_iam_openid_connect_provider.github](https://registry.terraform.io/providers/hashicorp/aws/latest/docs/resources/iam_openid_connect_provider) | resource |
57+
| [aws_iam_role.github_actions_admin](https://registry.terraform.io/providers/hashicorp/aws/latest/docs/resources/iam_role) | resource |
58+
| [aws_iam_role.github_actions_dns](https://registry.terraform.io/providers/hashicorp/aws/latest/docs/resources/iam_role) | resource |
59+
| [aws_iam_role_policy.github_actions_admin_deny_dangerous](https://registry.terraform.io/providers/hashicorp/aws/latest/docs/resources/iam_role_policy) | resource |
60+
| [aws_iam_role_policy_attachment.github_actions_admin](https://registry.terraform.io/providers/hashicorp/aws/latest/docs/resources/iam_role_policy_attachment) | resource |
61+
| [aws_iam_role_policy_attachment.github_actions_dns_permissions](https://registry.terraform.io/providers/hashicorp/aws/latest/docs/resources/iam_role_policy_attachment) | resource |
62+
| [aws_iam_policy_document.github_actions_admin_assume_role](https://registry.terraform.io/providers/hashicorp/aws/latest/docs/data-sources/iam_policy_document) | data source |
63+
| [aws_iam_policy_document.github_actions_admin_deny_dangerous](https://registry.terraform.io/providers/hashicorp/aws/latest/docs/data-sources/iam_policy_document) | data source |
64+
| [aws_iam_policy_document.github_actions_dns_assume_role](https://registry.terraform.io/providers/hashicorp/aws/latest/docs/data-sources/iam_policy_document) | data source |
65+
66+
## Inputs
67+
68+
| Name | Description | Type | Default | Required |
69+
| ---- | ----------- | ---- | ------- | :------: |
70+
| <a name="input_dns_policy_arn"></a> [dns\_policy\_arn](#input\_dns\_policy\_arn) | ARN of the managed IAM policy for Route53 record management | `string` | n/a | yes |
71+
72+
## Outputs
73+
74+
| Name | Description |
75+
| ---- | ----------- |
76+
| <a name="output_github_actions_admin_role_arn"></a> [github\_actions\_admin\_role\_arn](#output\_github\_actions\_admin\_role\_arn) | ARN of the IAM role for GitHub Actions with admin permissions |
77+
| <a name="output_github_actions_dns_role_arn"></a> [github\_actions\_dns\_role\_arn](#output\_github\_actions\_dns\_role\_arn) | ARN of the IAM role for GitHub Actions with DNS management permissions |
78+
<!-- END_TF_DOCS -->

‎modules/github-oidc/outputs.tf‎

Lines changed: 4 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,9 @@
11
output "github_actions_admin_role_arn" {
2-
value = aws_iam_role.github_actions_admin.arn
2+
description = "ARN of the IAM role for GitHub Actions with admin permissions"
3+
value = aws_iam_role.github_actions_admin.arn
34
}
45

56
output "github_actions_dns_role_arn" {
6-
value = aws_iam_role.github_actions_dns.arn
7+
description = "ARN of the IAM role for GitHub Actions with DNS management permissions"
8+
value = aws_iam_role.github_actions_dns.arn
79
}

‎modules/iam-policy/route53-single-zone/README.md‎

Lines changed: 41 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,41 @@
1+
# Route53 Single Zone Policy
2+
3+
<!-- BEGIN_TF_DOCS -->
4+
## Requirements
5+
6+
No requirements.
7+
8+
## Providers
9+
10+
| Name | Version |
11+
| ---- | ------- |
12+
| <a name="provider_aws"></a> [aws](#provider\_aws) | n/a |
13+
14+
## Modules
15+
16+
No modules.
17+
18+
## Resources
19+
20+
| Name | Type |
21+
| ---- | ---- |
22+
| [aws_iam_policy.this](https://registry.terraform.io/providers/hashicorp/aws/latest/docs/resources/iam_policy) | resource |
23+
| [aws_iam_policy_document.this](https://registry.terraform.io/providers/hashicorp/aws/latest/docs/data-sources/iam_policy_document) | data source |
24+
| [aws_route53_zone.this](https://registry.terraform.io/providers/hashicorp/aws/latest/docs/data-sources/route53_zone) | data source |
25+
26+
## Inputs
27+
28+
| Name | Description | Type | Default | Required |
29+
| ---- | ----------- | ---- | ------- | :------: |
30+
| <a name="input_policy_name"></a> [policy\_name](#input\_policy\_name) | Name for the IAM policy | `string` | n/a | yes |
31+
| <a name="input_zone_name"></a> [zone\_name](#input\_zone\_name) | Name of the Route53 hosted zone (e.g. example.com) | `string` | n/a | yes |
32+
| <a name="input_policy_description"></a> [policy\_description](#input\_policy\_description) | Description for the IAM policy | `string` | `""` | no |
33+
34+
## Outputs
35+
36+
| Name | Description |
37+
| ---- | ----------- |
38+
| <a name="output_policy_arn"></a> [policy\_arn](#output\_policy\_arn) | n/a |
39+
| <a name="output_zone_arn"></a> [zone\_arn](#output\_zone\_arn) | n/a |
40+
| <a name="output_zone_id"></a> [zone\_id](#output\_zone\_id) | n/a |
41+
<!-- END_TF_DOCS -->

‎modules/iam-user/README.md‎

Lines changed: 44 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,44 @@
1+
# IAM User
2+
3+
<!-- BEGIN_TF_DOCS -->
4+
## Requirements
5+
6+
No requirements.
7+
8+
## Providers
9+
10+
| Name | Version |
11+
| ---- | ------- |
12+
| <a name="provider_aws"></a> [aws](#provider\_aws) | n/a |
13+
14+
## Modules
15+
16+
No modules.
17+
18+
## Resources
19+
20+
| Name | Type |
21+
| ---- | ---- |
22+
| [aws_iam_access_key.this](https://registry.terraform.io/providers/hashicorp/aws/latest/docs/resources/iam_access_key) | resource |
23+
| [aws_iam_user.this](https://registry.terraform.io/providers/hashicorp/aws/latest/docs/resources/iam_user) | resource |
24+
| [aws_iam_user_policy_attachment.this](https://registry.terraform.io/providers/hashicorp/aws/latest/docs/resources/iam_user_policy_attachment) | resource |
25+
| [aws_secretsmanager_secret.access_key](https://registry.terraform.io/providers/hashicorp/aws/latest/docs/resources/secretsmanager_secret) | resource |
26+
| [aws_secretsmanager_secret_version.access_key](https://registry.terraform.io/providers/hashicorp/aws/latest/docs/resources/secretsmanager_secret_version) | resource |
27+
28+
## Inputs
29+
30+
| Name | Description | Type | Default | Required |
31+
| ---- | ----------- | ---- | ------- | :------: |
32+
| <a name="input_name"></a> [name](#input\_name) | Name of the IAM user | `string` | n/a | yes |
33+
| <a name="input_access_keys"></a> [access\_keys](#input\_access\_keys) | Map of access key labels to descriptions | `map(string)` | `{}` | no |
34+
| <a name="input_policy_arns"></a> [policy\_arns](#input\_policy\_arns) | Map of managed policy ARNs to attach to the user (key = stable name, value = ARN) | `map(string)` | `{}` | no |
35+
| <a name="input_tags"></a> [tags](#input\_tags) | Tags to apply to the IAM user | `map(string)` | `{}` | no |
36+
37+
## Outputs
38+
39+
| Name | Description |
40+
| ---- | ----------- |
41+
| <a name="output_access_keys"></a> [access\_keys](#output\_access\_keys) | n/a |
42+
| <a name="output_arn"></a> [arn](#output\_arn) | n/a |
43+
| <a name="output_name"></a> [name](#output\_name) | n/a |
44+
<!-- END_TF_DOCS -->

‎modules/permission-set/README.md‎

Lines changed: 44 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,44 @@
1+
# Permission Set
2+
3+
<!-- BEGIN_TF_DOCS -->
4+
## Requirements
5+
6+
No requirements.
7+
8+
## Providers
9+
10+
| Name | Version |
11+
| ---- | ------- |
12+
| <a name="provider_aws"></a> [aws](#provider\_aws) | n/a |
13+
14+
## Modules
15+
16+
No modules.
17+
18+
## Resources
19+
20+
| Name | Type |
21+
| ---- | ---- |
22+
| [aws_ssoadmin_account_assignment.this](https://registry.terraform.io/providers/hashicorp/aws/latest/docs/resources/ssoadmin_account_assignment) | resource |
23+
| [aws_ssoadmin_customer_managed_policy_attachment.this](https://registry.terraform.io/providers/hashicorp/aws/latest/docs/resources/ssoadmin_customer_managed_policy_attachment) | resource |
24+
| [aws_ssoadmin_managed_policy_attachment.this](https://registry.terraform.io/providers/hashicorp/aws/latest/docs/resources/ssoadmin_managed_policy_attachment) | resource |
25+
| [aws_ssoadmin_permission_set.this](https://registry.terraform.io/providers/hashicorp/aws/latest/docs/resources/ssoadmin_permission_set) | resource |
26+
27+
## Inputs
28+
29+
| Name | Description | Type | Default | Required |
30+
| ---- | ----------- | ---- | ------- | :------: |
31+
| <a name="input_instance_arn"></a> [instance\_arn](#input\_instance\_arn) | ARN of the SSO instance | `string` | n/a | yes |
32+
| <a name="input_name"></a> [name](#input\_name) | Name of the permission set | `string` | n/a | yes |
33+
| <a name="input_assignments"></a> [assignments](#input\_assignments) | Map of account assignments (key = stable name, value = assignment config) | <pre>map(object({<br/> principal_id = string<br/> principal_type = string<br/> target_id = string<br/> }))</pre> | `{}` | no |
34+
| <a name="input_customer_managed_policy_names"></a> [customer\_managed\_policy\_names](#input\_customer\_managed\_policy\_names) | Map of customer managed policy names to attach (key = stable name, value = policy name) | `map(string)` | `{}` | no |
35+
| <a name="input_description"></a> [description](#input\_description) | Description of the permission set | `string` | `null` | no |
36+
| <a name="input_managed_policy_arns"></a> [managed\_policy\_arns](#input\_managed\_policy\_arns) | Map of AWS managed policy ARNs to attach (key = stable name, value = ARN) | `map(string)` | `{}` | no |
37+
| <a name="input_session_duration"></a> [session\_duration](#input\_session\_duration) | Session duration in ISO 8601 format | `string` | `"PT2H"` | no |
38+
39+
## Outputs
40+
41+
| Name | Description |
42+
| ---- | ----------- |
43+
| <a name="output_arn"></a> [arn](#output\_arn) | ARN of the permission set |
44+
<!-- END_TF_DOCS -->

‎scripts/terraform-docs-hook.sh‎

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,7 @@
1+
#!/bin/sh
2+
3+
terraform-docs .
4+
5+
for dir in $(find modules -name '*.tf' -exec dirname {} \; | sort -u); do
6+
terraform-docs --config modules/.terraform-docs.yml "$dir"
7+
done

0 commit comments

Comments
 (0)