EDP
terraform-bootstrap
Visual README

Terraform Bootstrap

First Terraform layer: remote state, locking, and GitHub OIDC roles for CI/CD.

S3 tfstateDynamoDB locksGitHub OIDCIAM rolesCI/CD trust
Terraform foundation

The first apply creates the shared state and CI trust layer

Bootstrap foundation This repo creates the AWS control resources that later Terraform and GitHub Actions workflows depend on. Operator runs bootstrap once Terraform apply dev / staging / prod Remote state backend S3 tfstate bucket DynamoDB lock table GitHub deploy trust OIDC provider Environment roles Infrastructure repos use S3 backend + locks GitHub Actions assume short-lived roles creates trust remote backend OIDC roles
State firstThe S3 bucket stores Terraform state, and DynamoDB prevents concurrent applies from corrupting it.
CI trustGitHub Actions receives short-lived AWS credentials through OIDC instead of long-lived access keys.
Downstream dependencyEvery later Terraform repo assumes this foundation already exists before it can deploy safely.
Repository focus

Foundation for every Terraform repo

Foundation for every Terraform repo The main responsibility of this repository as a left-to-right flow. Operator / GitHub ActionsStep 1Terraform bootstrapStep 2S3 tfstate bucketStep 3DynamoDB lock tableStep 4GitHub OIDC providerStep 5Environment IAM rolesStep 6
Primary responsibilityThis diagram isolates the work owned by this repository from the rest of the platform.
Input and outputThe left side shows what the repo receives; the right side shows what it hands to the next layer.
Operational boundaryThe README has exact commands; this page shows the mental model behind those commands.
Runtime sequence

How work moves through the repo

Runtime interaction OperatorTerraformS3 StateDynamoDBIAMGitHub Actions 1. Trigger2. Route work3. Process / generate4. Read or write data5. Return evidence6. Package response7. Operational result
TriggerA person, workflow, schedule, or frontend starts the sequence.
ProcessingThe repo performs its specialized job and returns evidence or artifacts.
HandoffThe output feeds another repository, platform layer, or stakeholder interface.
Core concept map

Key ideas to understand

Remote state

tfstate→S3→versioning

Terraform needs a durable receipt of what AWS resources it owns.

State locking

DynamoDB→lock→one apply

Locks prevent two applies from editing the same state at once.

OIDC trust

GitHub→short-lived AWS creds→role

CI/CD assumes AWS roles without storing long-lived access keys.

README navigation

Detailed sections in the markdown README

01 Why this has to come first
02 Why dev, staging, and prod are separate
03 Repository structure
04 Root-level files
05 The state-backend module
06 The github-oidc module

Use this page to understand the architecture visually; use the rendered README for exact setup and troubleshooting details.