Widen Terraform docs coverage

[kiwigitops]

Pull Request

IMPORTANT: Before submitting, please remove all sensitive data, secrets, tokens, or confidential information. Ensure you've redacted any NDA-covered information, IP addresses, resource names, or security-related details that shouldn't be publicly disclosed.

Description

This PR widens Terraform documentation coverage so the docs generation/check scripts include:

• src/**/ci/terraform README files
• deploy/azdo README files
• generated and previously untracked Terraform README files in drift detection

It also adds the generated ci/terraform README files that were missing from the current docs coverage.

Related Issue

Closes #495.

Type of Change

• Bug fix (non-breaking change which fixes an issue)
• New feature (non-breaking change which adds functionality)
• Breaking change (fix or feature that would cause existing functionality to not work as expected)
• Blueprint modification or addition
• Component modification or addition
• Documentation update
• CI/CD pipeline change
• Other (please describe):

Implementation Details

• Updated scripts/update-all-terraform-docs.sh to discover Terraform docs under src/**/ci/terraform and deploy/azdo.
• Updated scripts/tf-docs-check.sh so generated and untracked README files are included when checking for Terraform docs drift.
• Generated the missing ci/terraform/README.md files.
• Applied follow-up lint fixes from the latest PR validation run.

Testing Performed

• Terraform plan/apply
• Blueprint deployment test
• Unit tests
• Integration tests
• Bug fix includes regression test (see Test Policy)
• Manual validation
• Other:
  • bash -n scripts/update-all-terraform-docs.sh
  • bash -n scripts/tf-docs-check.sh
  • scripts/update-all-terraform-docs.sh
  • scripts/tf-docs-check.sh reports generated README updates before they are committed
  • Latest CI Terraform Documentation Compliance Check passed on the PR

Validation Steps

1. Run scripts/update-all-terraform-docs.sh from the repository root.
2. Run scripts/tf-docs-check.sh from the repository root.
3. Confirm no generated Terraform README drift remains after the generated files are committed.
4. Review the generated src/**/ci/terraform/README.md files for expected terraform-docs content.

Checklist

• I have updated the documentation accordingly
• I have added tests to cover my changes
• All new and existing tests passed
• I have run terraform fmt on all Terraform code
• I have run terraform validate on all Terraform code
• I have run az bicep format on all Bicep code
• I have run az bicep build to validate all Bicep code
• I have checked for any sensitive data/tokens that should not be committed
• Lint checks pass (run applicable linters for changed file types)

Security Review

• No credentials, secrets, or tokens are hardcoded or logged
• RBAC and identity changes follow least-privilege principles
• No new network exposure or public endpoints introduced without justification
• Dependency additions or updates have been reviewed for known vulnerabilities
• Container image changes use pinned digests or SHA references

Additional Notes

This PR changes generated documentation and docs automation scope only. It does not change Terraform source, RBAC assignments, network exposure, dependencies, or container images. The security-reviewed label is still maintainer-applied.

The latest PR validation run also reported a Cargo audit failure in existing Rust crates outside this PR's changed files; the Terraform docs compliance check passed.

Screenshots (if applicable)

N/A.

[kiwigitops]

Quick follow-up: this Terraform docs coverage update is still current. The generated README updates are included, and the license/CLA check is green. I can split the generated files or adjust the drift-check scope if preferred.

[github-actions]

📚 Documentation Health Report

Generated on: 2026-06-23 08:50:09 UTC

📈 Documentation Statistics

Category	File Count
Main Documentation	222
Infrastructure Components	223
Blueprints	39
GitHub Resources	26
AI Assistant Guides (Copilot)	17
Total	527

🏗️ Three-Tree Architecture Status

• ✅ Bicep Documentation Tree: Auto-generated navigation
• ✅ Terraform Documentation Tree: Auto-generated navigation
• ✅ README Documentation Tree: Manual README organization

🔍 Quality Metrics

• Frontmatter Validation:
  success
• Link Validation: success

---

This report is automatically generated by the Documentation Automation workflow.

[bindsi]

Thanks for widening the Terraform docs coverage, @kiwigitops — the scope additions and the regenerated ci/terraform READMEs look like a helpful improvement! 🙏

One request before we proceed: would you mind updating the PR description to follow our pull request template? The current summary is a great start, but the template captures a few additional sections we rely on during review, including:

• Type of Change — so reviewers can quickly gauge impact (this looks like a CI/CD pipeline change + documentation update)
• Related Issue — you already reference Closes #495, which is perfect; the template just standardizes where it lives
• Checklist — especially the terraform fmt / terraform validate confirmations and the sensitive-data check
• Security Review — deploy/ is one of the security-sensitive paths called out in the template, so please complete that section

You can copy the structure straight from .github/PULL_REQUEST_TEMPLATE.md and fold your existing summary and test notes into the corresponding sections. Once the description is filled in, I'll continue the review. Thanks again! ✅

[katriendg]

Thanks so much for this contribution, and welcome to the project! 🎉 This is a clean, well-scoped fix for #495 — I verified it covers all 26 missing ci/terraform READMEs and correctly brings deploy/azdo into the drift-check scope, with no unexpected changes.

Before we can merge, could you please address a couple of process items:

1. Please use the PR template. The current description only has Summary and Tests. Please re-fill the description using the repository template so we can confirm change type, testing, checklist, and security items: .github/PULL_REQUEST_TEMPLATE.md

2. Security Review + label. This PR adds a file under a security-sensitive path (src/000-cloud/010-security-identity/ci/terraform/README.md) and touches deploy/-related tooling. Per the template's Security Review section, these paths require the security-reviewed label before merge. Please complete the Security Review checklist in the template so a maintainer can apply the label.

3. CI confirmation. Since deploy/azdo READMEs are now in the drift-check scope, please confirm the tf-docs-check / validation jobs are green on the latest commit before merge.

Thanks again — once the description is updated with the template and the security checklist is filled in, this should be good to go. 🙌

[github-actions]

📚 Documentation Health Report

Generated on: 2026-06-23 11:06:42 UTC

📈 Documentation Statistics

Category	File Count
Main Documentation	222
Infrastructure Components	223
Blueprints	39
GitHub Resources	26
AI Assistant Guides (Copilot)	17
Total	527

🏗️ Three-Tree Architecture Status

• ✅ Bicep Documentation Tree: Auto-generated navigation
• ✅ Terraform Documentation Tree: Auto-generated navigation
• ✅ README Documentation Tree: Manual README organization

🔍 Quality Metrics

• Frontmatter Validation:
  success
• Link Validation: success

---

This report is automatically generated by the Documentation Automation workflow.

[kiwigitops]

Updated the PR description to use the template and filled in the security section. I also pushed df79d6c to fix the latest shell/docs lint issues from CI: the shfmt diff in scripts/tf-docs-check.sh and the bare URL in the generated VPN Gateway README. The Terraform docs compliance check was already passing; Cargo audit is still failing in existing Rust crates outside this PR's changed files.