AWS bootstrap

Run this once per new project, with administrator AWS credentials. Output is everything a new repo’s backend.tf needs.

The bootstrap is plain Terraform. The first apply runs with local state. Once the bucket exists, uncomment the backend "s3" block at the top of the file. Then terraform init -migrate-state lifts the state into the bucket the bootstrap itself just created. The bucket then hosts both its own bootstrap state (_bootstrap/terraform.tfstate) and the consuming repo’s state (<project>/terraform.tfstate).

Prerequisites

Administrator AWS credentials in the shell. aws sts get-caller-identity returns an administrator ARN.
Terraform ≥ 1.10 or OpenTofu ≥ 1.10 on PATH.
The new GitHub repo (<github-org>/<github-repo>) already exists.

The GitHub Actions OIDC provider exists in the AWS account. Check with:

aws iam list-open-id-connect-providers \
  --query 'OpenIDConnectProviderList[?contains(Arn, `token.actions.githubusercontent.com`)]'

If the result is empty, create it once per account (one-time, account-wide):

aws iam create-open-id-connect-provider \
  --url https://token.actions.githubusercontent.com \
  --client-id-list sts.amazonaws.com

AWS verifies the GitHub Actions issuer’s certificate chain automatically. It needs no manual thumbprint.

Each human operator has an IAM user with MFA enabled, and a policy granting only sts:AssumeRole on arn:aws:iam::<account-id>:role/tf-* (no direct resource permissions). Operator IAM user creation is a per-operator one-time step, separate from per-project bootstrap.

Where this lives

The recommended layout is one directory per project inside a single administrator-owned repo (suggested name: terraform-aws-foundation):

terraform-aws-foundation/
├── bootstrap/
│   ├── proxmox/
│   │   ├── main.tf          # this file
│   │   └── terraform.tfvars # per-project values
│   ├── unifi/
│   │   ├── main.tf
│   │   └── terraform.tfvars
│   └── ...
└── README.md

Each per-project directory is independent: its own state object lives in its own bucket, so projects cannot affect each other even by accident.

The bootstrap module

The Terraform code lives in dryvist/tofu-aws-templates (Apache-2.0, public). Each per-project bootstrap directory is a small root module that wires the published module to the project’s values:

terraform {
  required_version = ">= 1.10"

  required_providers {
    aws = {
      source  = "hashicorp/aws"
      version = "~> 5.0"
    }
  }

  # First `terraform apply` runs with local state. Once the bucket exists,
  # uncomment this block (substitute the bucket name the apply emits) and
  # run `terraform init -migrate-state` to lift state into the bucket.
  #
  # backend "s3" {
  #   bucket       = "tfstate-<project>-<account-id>"
  #   key          = "_bootstrap/terraform.tfstate"
  #   region       = "us-east-1"
  #   use_lockfile = true
  #   encrypt      = true
  # }
}

provider "aws" {
  region = "us-east-1"
}

module "state_backend" {
  source = "git::https://github.com/dryvist/tofu-aws-templates.git?ref=v0.1.0"

  project        = "proxmox"
  github_org     = "<github-org>"
  github_repo    = "tofu-proxmox"
  branch_pattern = "main"

  operator_user_arns = [
    "arn:aws:iam::<account-id>:user/<operator>",
  ]
}

output "backend_config"   { value = module.state_backend.backend_config }
output "tf_role_arn"      { value = module.state_backend.tf_role_arn }
output "state_bucket"     { value = module.state_backend.state_bucket }
output "state_key_prefix" { value = module.state_backend.state_key_prefix }

Full input / output reference and the list of underlying AWS resources live in the module repo’s README. The module pins to a tagged release (v0.1.0, shown in the preceding block). Breaking changes ship as new majors, so existing bootstraps stay valid until you re-pin. The S3-native lock object (<project>/terraform.tfstate.tflock) is just another S3 object under the same prefix as state. It needs no separate IAM permission and no DynamoDB table.

Bootstrap the chicken-and-egg

Apply locally

With the preceding module block pointing at your project’s values:

terraform init      # local state — no backend block yet
terraform apply

Confirm the apply. terraform output backend_config emits the ready-to-paste backend "s3" {} block for the consuming repo (terraform output -raw backend_config > /tmp/backend.tf to ship it straight to a file).

Uncomment the backend block

In main.tf, uncomment the backend "s3" block at the top of the terraform {} block and substitute the outputs the apply just produced:

backend "s3" {
  bucket       = "tfstate-proxmox-<account-id>"
  key          = "_bootstrap/terraform.tfstate"
  region       = "us-east-1"
  use_lockfile = true
  encrypt      = true
}

encrypt = true instructs the client to send the SSE header on every PutObject. The preceding module already configures the bucket’s default SSE-S3 encryption. kms_key_id is not needed, because there is no KMS key.

Migrate state into the bucket

terraform init -migrate-state

Terraform prompts to copy the local state file into the bucket. Confirm. Then delete the local artefacts:

rm terraform.tfstate terraform.tfstate.backup

The bootstrap is now self-hosting in the bucket it created. Subsequent terraform plan / terraform apply runs against the bootstrap (for example to widen branch_pattern or add another operator) work like any other Terraform module.

Verify

# State bucket exists and contains the bootstrap state.
aws s3 ls s3://tfstate-<project>-<account-id>/_bootstrap/

# Role exists with the expected name.
aws iam get-role --role-name tf-<project>

# Outputs — feed these into the consuming repo's backend.tf.
terraform output -json

If all three succeed, the consuming repo can immediately set up its backend.tf and run its first terraform plan.

Where to go next

OpenTofu check placement

Where every Terraform / OpenTofu command runs — pre-commit vs CI.

Infrastructure

Observability

Automation

Prerequisites

Where this lives

The bootstrap module

Bootstrap the chicken-and-egg

Verify

Where to go next

OpenTofu check placement

​Prerequisites

​Where this lives

​The bootstrap module

​Bootstrap the chicken-and-egg

​Verify

​Where to go next

OpenTofu check placement

Prerequisites

Where this lives

The bootstrap module

Bootstrap the chicken-and-egg

Verify

Where to go next