docs(infrastructure): add Terraform on AWS section#46
Open
JacobPEvans-personal wants to merge 2 commits into
Open
docs(infrastructure): add Terraform on AWS section#46JacobPEvans-personal wants to merge 2 commits into
JacobPEvans-personal wants to merge 2 commits into
Conversation
Three new pages under Infrastructure → Terraform on AWS: - overview: isolation model (per-project IAM role, GitHub OIDC for CI, named operator IAM users with MFA), naming conventions, the SSE-S3 vs SSE-KMS pricing rationale, aws-vault keychain context, tagging, and tool versions. - aws-bootstrap: admin-runnable Terraform that provisions the state bucket, GitHub OIDC trust, and per-project IAM role. Includes the chicken-and-egg flow (local apply → init -migrate-state into the bucket the bootstrap just created). - consuming-repo: backend.tf with use_lockfile=true, providers.tf with default_tags, the operator's ~/.aws/config profile chain (mfa-base → tf-<project> via source_profile/role_arn), and the GitHub Actions workflow with aws-actions/configure-aws-credentials@v4 + OIDC. Plus a Terragrunt variant section. Three CardGroup cross-links added to existing pages: - infrastructure/overview.mdx (Cross-cutting topics) - security/tools/aws-vault.mdx (See also list) - infrastructure/terraform-check-placement.mdx (Where to go next) docs.json gains the new "Terraform on AWS" nested subgroup inside the Infrastructure group, alongside the existing CI/CD subgroup. Standards established: - One IAM role per repo; no shared "terraform" power-user. - GitHub OIDC only for CI; no static AWS_ACCESS_KEY_ID secrets. - S3 native locking via use_lockfile=true; no DynamoDB lock tables. - SSE-S3 (AES256) for state buckets; no per-project KMS keys — pricing wins, isolation already enforced at the IAM role boundary. - Bootstrap state lives in the bucket it provisions, under _bootstrap/terraform.tfstate. All Mermaid diagrams use the canonical theme directive and classDef palette; internal click directives only; no real account IDs, hostnames, or IPs anywhere in the new pages. Assisted-by: Claude <noreply@anthropic.com>
… repo The inline ~230-line Terraform snippet on the aws-bootstrap page is gone. The module code now lives in dryvist/terraform-aws-template (Apache-2.0, public). The page shows a ~45-line module-block usage pinned to v0.1.0; full input/output reference and the underlying resource list live in the module repo's README. Page is roughly half the length and easier to scan. The chicken-and-egg flow, verify commands, Mermaid diagram, and CardGroup are unchanged. Repo: https://github.com/dryvist/terraform-aws-template Release: https://github.com/dryvist/terraform-aws-template/releases/tag/v0.1.0 Assisted-by: Claude:claude-opus-4-7
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
use_lockfile = true), SSE-S3 (not SSE-KMS — pricing), aws-vault + MFA + AssumeRole for local dev.infrastructure/overview,security/tools/aws-vault, andterraform-check-placementpages route readers into the new section.Why SSE-S3 not SSE-KMS
Documented explicitly: SSE-KMS adds ~$1/month per project key plus per-API-call charges that scale with every CI build's state read/write (link to AWS KMS pricing). SSE-S3 is the same AES-256 cipher; access control is already enforced at the per-project IAM role boundary. App-layer secrets that genuinely need MFA-gated or cross-account key control belong in Bitwarden / Doppler, not the state bucket.
Test plan
npx mint dev(ormint devin the dev shell) — visit/infrastructure/terraform/overview,/infrastructure/terraform/aws-bootstrap,/infrastructure/terraform/consuming-repoand confirm rendering.tf-projectrole node on the overview diagram — should navigate to/infrastructure/terraform/aws-bootstrap. Click the bucket node — should navigate to/infrastructure/terraform/consuming-repo.diagram-project,hammer).mint broken-linksreports zero broken internal links (CI runs this).Out of scope (deliberately)
Multi-account state organization; AWS IAM Identity Center; existing-repo migration steps; bootstrap admin repo creation; CloudPosse / Gruntwork module wrappers; DynamoDB lock tables; bucket cross-region replication.
🤖 Generated with Claude Code