Feature/infrastructure docs autogen

.github/workflows/run-ci-cd.yaml

@@ -64,6 +64,18 @@ jobs:
           github_token: ${{ secrets.GITHUB_TOKEN }}
           tflint_version: v0.60.0
 
+      - name: Install terraform-docs
+        env:
+          TERRAFORM_DOCS_VERSION: v0.22.0
+        run: |
+          TARBALL="terraform-docs-${TERRAFORM_DOCS_VERSION}-linux-amd64.tar.gz"
+          BASE_URL="https://github.com/terraform-docs/terraform-docs/releases/download/${TERRAFORM_DOCS_VERSION}"
+          curl -sSLo "${TARBALL}" "${BASE_URL}/${TARBALL}" && \
+            curl -sSL "${BASE_URL}/terraform-docs-${TERRAFORM_DOCS_VERSION}.sha256sum" | grep -F "${TARBALL}" | sha256sum -c - && \
+            tar -xzf "${TARBALL}" terraform-docs && \
+            sudo install -m 755 terraform-docs /usr/local/bin/terraform-docs && \
+            rm -f "${TARBALL}" terraform-docs
+
       - name: Run pre-commit
         env:
           GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

.markdownlint.yaml

@@ -17,9 +17,15 @@ MD024: false
 # MD033/no-inline-html
 MD033: false
 
+# MD034/no-bare-urls
+MD034: false
+
 # MD041/first-line-heading
 MD041: false
 
 # MD046/code-block-style
 MD046:
   style: fenced
+
+# MD060 conflicts with terraform-docs generated table format
+MD060: false

.pre-commit-config.yaml

@@ -39,6 +39,11 @@ repos:
         files: ^infrastructure/.*\.tf$
         args:
           - --args=--config=__GIT_WORKING_DIR__/infrastructure/.tflint.hcl
+      - id: terraform_docs
+        files: ^infrastructure/.*\.tf$
+        args:
+          - --args=--output-file=README.md
+          - --args=--output-mode=inject
 
   - repo: https://github.com/astral-sh/ruff-pre-commit
     rev: aca6d4c8045a504e2812ea4bedff1d0a09e437bc  # v0.15.8
@@ -63,6 +68,8 @@ repos:
       - id: markdownlint
         args:
           - --fix
+          - --config
+          - .markdownlint.yaml
         files: \.md$
 
   - repo: https://github.com/jumanjihouse/pre-commit-hook-yamlfmt

infrastructure/.terraform-docs.yaml

@@ -0,0 +1,37 @@
+formatter: markdown table
+
+recursive:
+  enabled: false
+
+sections:
+  hide: []
+  show: []
+
+output:
+  mode: inject
+  template: |-
+    <!-- BEGIN_TF_DOCS -->
+    {{ .Content }}
+    <!-- END_TF_DOCS -->
+output-values:
+  enabled: false
+  from: ''
+
+sort:
+  enabled: true
+  by: name
+
+settings:
+  anchor: true
+  color: true
+  default: true
+  description: false
+  escape: true
+  hide-empty: false
+  html: true
+  indent: 2
+  lockfile: true
+  read-comments: true
+  required: true
+  sensitive: true
+  type: true

infrastructure/Makefile

@@ -12,3 +12,27 @@ test-infrastructure: ## Run infrastructure tests
 		terraform -chdir="$$module_dir" init -backend=false -input=false && \
 		terraform -chdir="$$module_dir" test || exit 1; \
 	done
+
+TERRAFORM_DOCS_VERSION := v0.22.0
+
+docs-infrastructure: ## Generate terraform-docs
+	@echo "Verifying terraform-docs version..."
+	@if ! terraform-docs --version | grep -q "$(TERRAFORM_DOCS_VERSION)"; then \
+		echo "Error: Required terraform-docs version is $(TERRAFORM_DOCS_VERSION)"; \
+		echo "Please install it: go install github.com/terraform-docs/terraform-docs@$(TERRAFORM_DOCS_VERSION)"; \
+		exit 1; \
+	fi
+	@cd $(dir $(abspath $(lastword $(MAKEFILE_LIST)))) && \
+	find bootstrap live state modules \
+		-name "main.tf" \
+		-not -path "*/.terraform/*" \
+		-not -path "*/tests/*" \
+		-print0 | \
+	while IFS= read -r -d '' tf; do \
+		dir=$$(dirname "$$tf"); \
+		echo "Generating docs for $$dir..."; \
+		terraform-docs markdown "$$dir" \
+		--config .terraform-docs.yaml \
+		--output-file README.md \
+		--output-mode inject || exit 1; \
+	done

infrastructure/README.md

@@ -389,3 +389,18 @@ aws ecs run-task \
   ```bash
   terraform destroy
   ```
+
+## Documentation
+
+Module READMEs are generated automatically during CI using `terraform-docs` `v0.22.0`.
+To ensure consistency, you must use the same version locally — the Makefile will exit with an error if the version does not match.
+
+### Install the required version
+
+Please refer to the [official terraform-docs installation guide](https://terraform-docs.io/user-guide/installation/) for instructions on how to install a specific release version for your operating system.
+
+### Generate docs locally
+
+```bash
+make docs-infrastructure
+```

infrastructure/bootstrap/README.md

@@ -76,3 +76,51 @@ Use the following inline permissions for the `nest-bootstrap` IAM User
  ]
 }
 ```
+
+<!-- BEGIN_TF_DOCS -->
+## Requirements
+
+| Name | Version |
+| ---- | ------- |
+| <a name="requirement_terraform"></a> [terraform](#requirement\_terraform) | ~> 1.14.0 |
+| <a name="requirement_aws"></a> [aws](#requirement\_aws) | ~> 6.36.0 |
+
+## Providers
+
+| Name | Version |
+| ---- | ------- |
+| <a name="provider_aws"></a> [aws](#provider\_aws) | 6.36.0 |
+
+## Modules
+
+No modules.
+
+## Resources
+
+| Name | Type |
+| ---- | ---- |
+| [aws_iam_policy.part_one](https://registry.terraform.io/providers/hashicorp/aws/latest/docs/resources/iam_policy) | resource |
+| [aws_iam_policy.part_two](https://registry.terraform.io/providers/hashicorp/aws/latest/docs/resources/iam_policy) | resource |
+| [aws_iam_role.terraform](https://registry.terraform.io/providers/hashicorp/aws/latest/docs/resources/iam_role) | resource |
+| [aws_iam_role_policy_attachment.attach_part_one](https://registry.terraform.io/providers/hashicorp/aws/latest/docs/resources/iam_role_policy_attachment) | resource |
+| [aws_iam_role_policy_attachment.attach_part_two](https://registry.terraform.io/providers/hashicorp/aws/latest/docs/resources/iam_role_policy_attachment) | resource |
+| [aws_caller_identity.current](https://registry.terraform.io/providers/hashicorp/aws/latest/docs/data-sources/caller_identity) | data source |
+| [aws_iam_policy_document.part_one](https://registry.terraform.io/providers/hashicorp/aws/latest/docs/data-sources/iam_policy_document) | data source |
+| [aws_iam_policy_document.part_two](https://registry.terraform.io/providers/hashicorp/aws/latest/docs/data-sources/iam_policy_document) | data source |
+
+## Inputs
+
+| Name | Description | Type | Default | Required |
+| ---- | ----------- | ---- | ------- | :------: |
+| <a name="input_aws_region"></a> [aws\_region](#input\_aws\_region) | The AWS region to deploy resources in. | `string` | `"us-east-2"` | no |
+| <a name="input_aws_role_external_id"></a> [aws\_role\_external\_id](#input\_aws\_role\_external\_id) | The external ID for role assumption. | `string` | n/a | yes |
+| <a name="input_environments"></a> [environments](#input\_environments) | The environments to create Terraform roles for. | `list(string)` | <pre>[<br/>  "staging",<br/>  "production"<br/>]</pre> | no |
+| <a name="input_project_name"></a> [project\_name](#input\_project\_name) | The name of the project. | `string` | `"nest"` | no |
+| <a name="input_shared_data_bucket_name"></a> [shared\_data\_bucket\_name](#input\_shared\_data\_bucket\_name) | Global S3 bucket for shared public data (e.g. nest.dump) | `string` | `"owasp-nest-shared-data"` | no |
+
+## Outputs
+
+| Name | Description |
+| ---- | ----------- |
+| <a name="output_terraform_role_arns"></a> [terraform\_role\_arns](#output\_terraform\_role\_arns) | The ARNs of the Terraform IAM roles, keyed by environment. |
+<!-- END_TF_DOCS -->