feat(infrastructure): add terraform-docs generation#4501
feat(infrastructure): add terraform-docs generation#4501zeel2104 wants to merge 2 commits intoOWASP:mainfrom
Conversation
github-actions
bot
added
docs
Summary by CodeRabbit
WalkthroughAdds terraform-docs integration: config, Makefile target, a Python orchestration script, pre-commit hook and CI install step, plus auto-generated Terraform README sections for infrastructure projects and modules. No runtime code changes; mostly documentation and tooling additions. Changes
Estimated code review effort🎯 3 (Moderate) | ⏱️ ~20 minutes Possibly related PRs
Suggested labels
Suggested reviewers
🚥 Pre-merge checks | ✅ 4 | ❌ 1❌ Failed checks (1 warning)
✅ Passed checks (4 passed)
✏️ Tip: You can configure your own custom pre-merge checks in the settings. ✨ Finishing Touches🧪 Generate unit tests (beta)
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
![cubic-dev-ai[bot]](https://avatars.githubusercontent.com/in/1082092?s=60&v=4){kind=small}
There was a problem hiding this comment.
1 issue found across 22 files
Confidence score: 4/5
- This PR looks safe to merge overall, with minimal functional risk since the issue is in CI/pre-commit behavior rather than runtime code.
- In
.pre-commit-config.yaml, theterraform-docshook only running on.tfchanges can miss script/config-only updates, which may leave generated docs stale and create documentation drift. - Given the moderate severity (5/10) and clear scope, this is a maintainability/process concern rather than a likely user-facing regression.
- Pay close attention to
.pre-commit-config.yaml- broaden hook triggers so terraform docs regenerate when related scripts/configuration change.
Prompt for AI agents (unresolved issues)
Check if these issues are valid — if so, understand the root cause of each and fix them. If appropriate, use sub-agents to investigate and fix each issue separately.
<file name=".pre-commit-config.yaml">
<violation number="1" location=".pre-commit-config.yaml:49">
P2: terraform-docs hook only triggers on `.tf` changes, so script/config updates can skip regeneration and leave docs stale.</violation>
</file>
Reply with feedback, questions, or to request a fix. Tag @cubic-dev-ai to re-run a review.
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 3
🧹 Nitpick comments (3)
infrastructure/Makefile (1)
3-7: Consider consolidating directory discovery logic with the Python script.The Makefile hardcodes
infrastructure/bootstrap infrastructure/live infrastructure/stateand usesfindfor modules, whileinfrastructure/scripts/terraform_docs.pyhas its ownterraform_directories()function. This duplication could lead to drift if new Terraform projects are added.You could simplify by having the Makefile call the Python script directly:
♻️ Optional refactor to reduce duplication
terraform-docs-infrastructure: ## Generate terraform-docs for infrastructure projects and modules - `@for` dir in infrastructure/bootstrap infrastructure/live infrastructure/state $$(find infrastructure/modules -type f -name "*.tf" -not -path "*/.terraform/*" -exec dirname {} \; | sort -u); do \ - echo "Generating terraform-docs for $$dir..."; \ - terraform-docs --config "$(CURDIR)/infrastructure/.terraform-docs.yml" "$$dir" || exit 1; \ - done + `@python` infrastructure/scripts/terraform_docs.py🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@infrastructure/Makefile` around lines 3 - 7, The Makefile target terraform-docs-infrastructure duplicates directory discovery already implemented in infrastructure/scripts/terraform_docs.py::terraform_directories(); update the target to invoke that Python script to produce the list of Terraform directories and iterate over its output instead of hardcoding "infrastructure/bootstrap infrastructure/live infrastructure/state" plus find for modules — call the script (e.g., via $(PYTHON) -m infrastructure.scripts.terraform_docs or the script's CLI) to emit directories, then loop over those results and run terraform-docs with the existing config, preserving the error handling (exit 1 on failure).infrastructure/modules/networking/modules/nacl/README.md (1)
1-1: Use standard acronym casing in the heading.On Line 1, consider
# NACLinstead of# Naclfor consistency with AWS terminology.🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@infrastructure/modules/networking/modules/nacl/README.md` at line 1, Change the README heading from "# Nacl" to use standard acronym casing "# NACL" so it matches AWS terminology and project conventions; update the top-level heading string in the README (the line that currently reads "Nacl") to "NACL".infrastructure/modules/networking/README.md (1)
8-9: Update source module constraints to use exact version pins instead of semantic ranges.The README reflects
~> 1.14.0and~> 6.36.0because the source.tffiles in this module use semantic constraints. Per infrastructure policy, updateinfrastructure/modules/networking/main.tfand submodules (vpc-endpoint/main.tf,nacl/main.tf) to pin exact versions:required_version = "1.14.0"andversion = "6.36.0". After updating the source, regenerate this README to align with policy.🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@infrastructure/modules/networking/README.md` around lines 8 - 9, Update the Terraform constraints from semantic ranges to exact pins: in infrastructure/modules/networking/main.tf set required_version = "1.14.0" (replacing any "~> 1.14.0" constraint) and in the module blocks in vpc-endpoint/main.tf and nacl/main.tf set version = "6.36.0" (replacing any "~> 6.36.0" constraints); after making these changes regenerate or update the README table entries so the README reflects the exact pins (required_version and version) rather than semantic ranges.
🤖 Prompt for all review comments with AI agents
Verify each finding against the current code and only fix it if needed.
Inline comments:
In @.pre-commit-config.yaml:
- Around line 43-50: The CI will fail because the pre-commit hook with id
"terraform_docs" (entry: python infrastructure/scripts/terraform_docs.py)
expects the external binary "terraform-docs" on PATH; update the CI pre-commit
job setup in the run-ci-cd workflow to install or make available the
"terraform-docs" binary before running pre-commit (e.g., add a step to
download/install the appropriate release or use package manager) so the
terraform_docs hook can run successfully.
In `@infrastructure/modules/database/README.md`:
- Line 67: The README entry for the output named db_proxy_endpoint
(output_db_proxy_endpoint) incorrectly states it is "The endpoint of the RDS
proxy" unconditionally; update the description to reflect conditional behavior
based on the enable_rds_proxy flag (when enable_rds_proxy is true it returns the
RDS proxy endpoint, otherwise it returns the DB instance endpoint/address). Edit
the README line mentioning db_proxy_endpoint to describe both cases and
reference the enable_rds_proxy toggle so consumers understand which endpoint
will be returned.
In `@infrastructure/modules/networking/modules/vpc-endpoint/README.md`:
- Line 56: Update the output description for the Terraform output named
security_group_id (defined in outputs.tf) to explicitly state that the output is
null when no interface VPC endpoints are enabled (i.e., only gateway endpoints
such as S3 are enabled) and that a security group is created only if at least
one interface endpoint (CloudWatch Logs, ECR API, ECR DKR, Secrets Manager, or
SSM) is enabled; then regenerate the module README so the README.md table entry
for security_group_id reflects this clarified behavior.
---
Nitpick comments:
In `@infrastructure/Makefile`:
- Around line 3-7: The Makefile target terraform-docs-infrastructure duplicates
directory discovery already implemented in
infrastructure/scripts/terraform_docs.py::terraform_directories(); update the
target to invoke that Python script to produce the list of Terraform directories
and iterate over its output instead of hardcoding "infrastructure/bootstrap
infrastructure/live infrastructure/state" plus find for modules — call the
script (e.g., via $(PYTHON) -m infrastructure.scripts.terraform_docs or the
script's CLI) to emit directories, then loop over those results and run
terraform-docs with the existing config, preserving the error handling (exit 1
on failure).
In `@infrastructure/modules/networking/modules/nacl/README.md`:
- Line 1: Change the README heading from "# Nacl" to use standard acronym casing
"# NACL" so it matches AWS terminology and project conventions; update the
top-level heading string in the README (the line that currently reads "Nacl") to
"NACL".
In `@infrastructure/modules/networking/README.md`:
- Around line 8-9: Update the Terraform constraints from semantic ranges to
exact pins: in infrastructure/modules/networking/main.tf set required_version =
"1.14.0" (replacing any "~> 1.14.0" constraint) and in the module blocks in
vpc-endpoint/main.tf and nacl/main.tf set version = "6.36.0" (replacing any "~>
6.36.0" constraints); after making these changes regenerate or update the README
table entries so the README reflects the exact pins (required_version and
version) rather than semantic ranges.
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: Path: .coderabbit.yaml
Review profile: CHILL
Plan: Pro
Run ID: 1f8c68e4-50a5-4a9c-ae49-299858c63b35
📒 Files selected for processing (22)
.pre-commit-config.yamlinfrastructure/.terraform-docs.ymlinfrastructure/Makefileinfrastructure/README.mdinfrastructure/bootstrap/README.mdinfrastructure/live/README.mdinfrastructure/modules/alb/README.mdinfrastructure/modules/cache/README.mdinfrastructure/modules/database/README.mdinfrastructure/modules/kms/README.mdinfrastructure/modules/networking/README.mdinfrastructure/modules/networking/modules/nacl/README.mdinfrastructure/modules/networking/modules/vpc-endpoint/README.mdinfrastructure/modules/parameters/README.mdinfrastructure/modules/security/README.mdinfrastructure/modules/service/README.mdinfrastructure/modules/storage/README.mdinfrastructure/modules/storage/modules/s3-bucket/README.mdinfrastructure/modules/tasks/README.mdinfrastructure/modules/tasks/modules/task/README.mdinfrastructure/scripts/terraform_docs.pyinfrastructure/state/README.md
infrastructure/modules/networking/modules/vpc-endpoint/README.md
Outdated
Show resolved
Hide resolved
There was a problem hiding this comment.
Hi @zeel2104, Thanks for working on this!
Its required to always run make check when pushing your code otherwise CI checks will fail. So plz do.
There was a problem hiding this comment.
Hi @zeel2104, you need to address all bot comments and run make check-test. This is part of our CONTRIBUTING.md/#code-quality-checks guidelines. Please also sync the PR with main whenever you get a chance.
I am marking this PR as draft, feel free to mark it as ready when it's updated.
| hooks: | ||
| - id: terraform_docs | ||
| name: terraform-docs | ||
| entry: python infrastructure/scripts/terraform_docs.py |
There was a problem hiding this comment.
I think we can use this pre-commit hook instead: https://terraform-docs.io/how-to/pre-commit-hooks/
zeel2104
force-pushed
the
feat/terraform-docs-generation
branch
from
0f85019 to
b90e294
Compare
|
There was a problem hiding this comment.
Actionable comments posted: 1
🧹 Nitpick comments (1)
infrastructure/scripts/terraform_docs.py (1)
31-35: Fail fast if the terraform-docs config is missing.A pre-check for
infrastructure/.terraform-docs.ymlgives a clearer error before iterating directories.💡 Suggested patch
def main() -> int: + if not CONFIG_PATH.exists(): + print(f"terraform-docs config not found: {CONFIG_PATH}", file=sys.stderr) + return 1 + terraform_docs = shutil.which("terraform-docs") if terraform_docs is None: print("terraform-docs is required but was not found on PATH.", file=sys.stderr) return 1🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@infrastructure/scripts/terraform_docs.py` around lines 31 - 35, Add a fast-fail pre-check in main() to verify the existence of the terraform-docs config file before doing any directory iteration: check for the file "infrastructure/.terraform-docs.yml" (e.g., using os.path.exists or Path.exists) and if missing, print a clear error to stderr and return non-zero (1). Keep this check early in main() just after ensuring terraform-docs is on PATH so the subsequent directory traversal logic in main() can assume the config exists.
🤖 Prompt for all review comments with AI agents
Verify each finding against the current code and only fix it if needed.
Inline comments:
In @.github/workflows/run-ci-cd.yaml:
- Around line 67-73: Download the terraform-docs tarball into a file and
download the corresponding .sha256sum for TERRAFORM_DOCS_VERSION, then verify
the tarball checksum (e.g., using sha256sum --check or comparing the downloaded
checksum) before extracting and installing; update the Install terraform-docs
step to save the tarball, fetch the .sha256sum for v${TERRAFORM_DOCS_VERSION},
validate the checksum and abort the job on mismatch, and only then tar -xz and
sudo mv terraform-docs /usr/local/bin/terraform-docs to ensure artifact
integrity.
---
Nitpick comments:
In `@infrastructure/scripts/terraform_docs.py`:
- Around line 31-35: Add a fast-fail pre-check in main() to verify the existence
of the terraform-docs config file before doing any directory iteration: check
for the file "infrastructure/.terraform-docs.yml" (e.g., using os.path.exists or
Path.exists) and if missing, print a clear error to stderr and return non-zero
(1). Keep this check early in main() just after ensuring terraform-docs is on
PATH so the subsequent directory traversal logic in main() can assume the config
exists.
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: Path: .coderabbit.yaml
Review profile: CHILL
Plan: Pro
Run ID: e8180958-dca2-4a36-b7e5-13991c2ef8ed
📒 Files selected for processing (25)
.github/workflows/run-ci-cd.yaml.pre-commit-config.yamlinfrastructure/.terraform-docs.ymlinfrastructure/Makefileinfrastructure/README.mdinfrastructure/bootstrap/README.mdinfrastructure/live/README.mdinfrastructure/modules/alb/README.mdinfrastructure/modules/cache/README.mdinfrastructure/modules/database/README.mdinfrastructure/modules/database/outputs.tfinfrastructure/modules/kms/README.mdinfrastructure/modules/networking/README.mdinfrastructure/modules/networking/modules/nacl/README.mdinfrastructure/modules/networking/modules/vpc-endpoint/README.mdinfrastructure/modules/networking/modules/vpc-endpoint/outputs.tfinfrastructure/modules/parameters/README.mdinfrastructure/modules/security/README.mdinfrastructure/modules/service/README.mdinfrastructure/modules/storage/README.mdinfrastructure/modules/storage/modules/s3-bucket/README.mdinfrastructure/modules/tasks/README.mdinfrastructure/modules/tasks/modules/task/README.mdinfrastructure/scripts/terraform_docs.pyinfrastructure/state/README.md
✅ Files skipped from review due to trivial changes (21)
- infrastructure/README.md
- infrastructure/bootstrap/README.md
- infrastructure/modules/database/outputs.tf
- infrastructure/.terraform-docs.yml
- infrastructure/modules/networking/modules/vpc-endpoint/outputs.tf
- infrastructure/live/README.md
- infrastructure/state/README.md
- infrastructure/Makefile
- infrastructure/modules/storage/modules/s3-bucket/README.md
- infrastructure/modules/tasks/modules/task/README.md
- infrastructure/modules/kms/README.md
- infrastructure/modules/tasks/README.md
- infrastructure/modules/service/README.md
- infrastructure/modules/cache/README.md
- infrastructure/modules/storage/README.md
- infrastructure/modules/networking/modules/nacl/README.md
- infrastructure/modules/security/README.md
- infrastructure/modules/alb/README.md
- infrastructure/modules/networking/README.md
- infrastructure/modules/database/README.md
- infrastructure/modules/networking/modules/vpc-endpoint/README.md
🚧 Files skipped from review as they are similar to previous changes (1)
- .pre-commit-config.yaml
| - name: Install terraform-docs | ||
| run: | | ||
| TERRAFORM_DOCS_VERSION=0.20.0 | ||
| curl -sSL \ | ||
| "https://github.com/terraform-docs/terraform-docs/releases/download/v${TERRAFORM_DOCS_VERSION}/terraform-docs-v${TERRAFORM_DOCS_VERSION}-linux-amd64.tar.gz" \ | ||
| | tar -xz terraform-docs | ||
| sudo mv terraform-docs /usr/local/bin/terraform-docs |
There was a problem hiding this comment.
🧩 Analysis chain
🏁 Script executed:
# First, locate and read the workflow file
find . -name "run-ci-cd.yaml" -o -name "run-ci-cd.yml" | head -20Repository: OWASP/Nest
Length of output: 88
🏁 Script executed:
# Also check the general structure of .github/workflows directory
ls -la .github/workflows/ 2>/dev/null || echo "Directory not found"Repository: OWASP/Nest
Length of output: 821
🏁 Script executed:
# Read lines 67-73 from the workflow file to verify content
sed -n '67,73p' .github/workflows/run-ci-cd.yamlRepository: OWASP/Nest
Length of output: 438
🏁 Script executed:
# Also read more context around those lines to understand the full step
sed -n '60,80p' .github/workflows/run-ci-cd.yamlRepository: OWASP/Nest
Length of output: 887
🌐 Web query:
terraform-docs github releases sha256sum checksum verification
💡 Result:
To verify terraform-docs binary downloads from GitHub releases using SHA256 checksums: 1. Go to the official releases page: https://github.com/terraform-docs/terraform-docs/releases 2. Download the appropriate binary archive (tar.gz for Unix, zip for Windows) for your platform and the desired version, e.g., terraform-docs-v0.22.0-linux-amd64.tar.gz. 3. Download the corresponding terraform-docs-vX.Y.Z.sha256sum file from the same release assets. This file contains SHA256 checksums for all platform binaries. 4. Extract the binary if needed (tar -xzf terraform-docs-vX.Y.Z-PLATFORM.tar.gz). 5. Verify the checksum: - Linux/macOS: sha256sum -c terraform-docs-vX.Y.Z.sha256sum --ignore-missing (checks only the downloaded file). - macOS alternative: shasum -a 256 -c terraform-docs-vX.Y.Z.sha256sum --ignore-missing. Expected output: terraform-docs-vX.Y.Z-PLATFORM.tar.gz: OK Example for latest release (v0.22.0 as of 2026-04-07): - SHA256 for linux-amd64.tar.gz: b44fb93405a610153a0a04546c78ebf294e2a0d23500bd6cacfaf115634fda9d (from release page snippet). Official installation instructions recommend direct curl download but do not explicitly mention verification. However, releases include .sha256sum files (confirmed in v0.17.0, v0.20.0 releases) and individual asset SHA256 hashes displayed on the page, generated by GoReleaser. Unlike HashiCorp Terraform (which provides SHA256SUMS + .sig for GPG), terraform-docs does not publish GPG signatures. GitHub's release integrity + checksum matching provides sufficient verification for integrity. Latest release: v0.22.0 (2026-04-07). Always check the specific release page for current checksums.
Citations:
- 1: https://github.com/terraform-docs/terraform-docs/releases
- 2: https://github.com/terraform-docs/terraform-docs/releases/tag/v0.17.0
- 3: https://github.com/terraform-docs/terraform-docs/releases/tag/v0.20.0
- 4: https://terraform-docs.io/user-guide/installation
- 5: https://www.goreleaser.com
- 6: Use goreleaser for release workflow and tasks terraform-docs/terraform-docs#377
Verify release artifact integrity before installing terraform-docs.
The step downloads and installs an external binary without checksum verification. terraform-docs releases include .sha256sum files containing checksums for all platform binaries; add hash verification to reduce CI supply-chain risk.
🔐 Suggested hardening patch
- name: Install terraform-docs
run: |
+ set -euo pipefail
TERRAFORM_DOCS_VERSION=0.20.0
- curl -sSL \
- "https://github.com/terraform-docs/terraform-docs/releases/download/v${TERRAFORM_DOCS_VERSION}/terraform-docs-v${TERRAFORM_DOCS_VERSION}-linux-amd64.tar.gz" \
- | tar -xz terraform-docs
- sudo mv terraform-docs /usr/local/bin/terraform-docs
+ ARCHIVE="terraform-docs-v${TERRAFORM_DOCS_VERSION}-linux-amd64.tar.gz"
+ BASE_URL="https://github.com/terraform-docs/terraform-docs/releases/download/v${TERRAFORM_DOCS_VERSION}"
+ curl -fsSLO "${BASE_URL}/${ARCHIVE}"
+ curl -fsSLO "${BASE_URL}/terraform-docs-v${TERRAFORM_DOCS_VERSION}.sha256sum"
+ grep " ${ARCHIVE}$" "terraform-docs-v${TERRAFORM_DOCS_VERSION}.sha256sum" | sha256sum -c -
+ tar -xzf "${ARCHIVE}" terraform-docs
+ sudo install -m 0755 terraform-docs /usr/local/bin/terraform-docs🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.
In @.github/workflows/run-ci-cd.yaml around lines 67 - 73, Download the
terraform-docs tarball into a file and download the corresponding .sha256sum for
TERRAFORM_DOCS_VERSION, then verify the tarball checksum (e.g., using sha256sum
--check or comparing the downloaded checksum) before extracting and installing;
update the Install terraform-docs step to save the tarball, fetch the .sha256sum
for v${TERRAFORM_DOCS_VERSION}, validate the checksum and abort the job on
mismatch, and only then tar -xz and sudo mv terraform-docs
/usr/local/bin/terraform-docs to ensure artifact integrity.
4 participants
Proposed change
Resolves #4485
Add
terraform-docssupport for the infrastructure codebase.This PR:
terraform-docsconfiguration ininfrastructure/.terraform-docs.ymlbootstrap,live, andstateinfrastructure/modules<!-- BEGIN_TF_DOCS -->/<!-- END_TF_DOCS -->injection markersterraform_docshook works on Windows as well as Unix-like environmentsChecklist
make check-testlocally: all warnings addressed, tests passed