AWS Terraform Starter Kit

A production-ready AWS Terraform starter kit featuring secure OIDC authentication, automated CI/CD pipelines, multi-environment support, and comprehensive security scanning. Get your infrastructure up and running in minutes with best practices baked in.

🚀 Features

• ⚡ One-Command Bootstrap: Single command automatically sets up your entire infrastructure pipeline
  • Creates S3 bucket with native state locking (Terraform 1.10+)
  • Creates account bootstrap stack for shared OIDC resources (reuses existing provider if present)
  • Generates environment-specific Terraform configurations
  • Stores explicit environment-to-account mapping in config/environments.json
  • Provisions environment IAM roles that consume bootstrap OIDC
  • Auto-generates GitHub Actions workflows for CI/CD
• 💬 PR Plan Comments: Terraform plan outputs are automatically posted to your pull requests for easy infrastructure change reviews
• 🛡️ Built-in Security: TFLint and Checkov are integrated in the pipeline and configured fail-closed for deployments

Tip

Catch AWS waste before and after you deploy.

CloudBurn is a free, open-source CLI that checks your Terraform and CloudFormation for costly patterns before deploy, then finds the waste already running in your AWS account. Run it locally or in CI.

Want it managed across your AWS accounts? CloudBurn Platform runs it for you and keeps scan results in your own account. Join the waitlist for 30% off.

📋 Prerequisites

• AWS account with admin access
• GitHub account with repository admin access

That's it! All other tools (Terraform, AWS CLI, jq, TFLint, Checkov) can be installed automatically with make install-tools.

🔧 Quick Start

⚠️ Multi-Account Best Practice

Important: For production use, deploy each environment to a separate AWS account:

• Test → AWS Account A (e.g., 111111111111)
• Staging → AWS Account B (e.g., 222222222222)
• Production → AWS Account C (e.g., 333333333333)

Why?

• Security isolation between environments
• Blast radius containment
• Compliance requirements (SOC2, ISO 27001, etc.)
• Cost separation and tracking

Setup (4 Steps - 5 minutes)

1. Copy the starter kit

1. Click the green "Use this template" button to create a new repository based on this starter kit.

2. Install required tools

make install-tools  # Installs Terraform, AWS CLI, TFLint, Checkov, Granted

3. Configure AWS Credentials

# Option A: AWS CLI
aws configure

# Option B: Granted (for multiple accounts)
assume <profile-name>

# Verify you are connected to AWS in the CLI
aws sts get-caller-identity

4. Run Setup to provision your Terraform project

make setup
# Or: ./scripts/setup.sh

What happens:

1. ✅ Verifies prerequisites e.g. dev tools
2. ✅ Creates S3 backend with native state locking (no DynamoDB needed)
3. ✅ Creates account bootstrap stack (bootstrap/account) for shared OIDC provider lifecycle
4. ✅ Provisions environment stack (test/staging/production) with IAM role + Terraform config
5. ✅ Writes/updates explicit account mapping in config/environments.json
6. ✅ Generates GitHub workflow files with account guardrails

Multi-Account Setup:

# Test account
assume test-account
make setup  # Select: test

# Staging account
assume staging-account
make setup  # Select: staging

# Production account
assume prod-account
make setup  # Select: production

Configure GitHub (2 minutes)

A. Environment Mapping (Required)

Setup stores environment mappings in config/environments.json.
Commit this file so account/region/state/role mappings are explicit and reviewed.

Example:

{
  "environments": {
    "test": {
      "account_id": "111111111111",
      "region": "us-east-1",
      "state_bucket": "terraform-state-111111111111-us-east-1",
      "role_name": "GitHubActionsServiceRole-Terraform"
    }
  }
}

B. Environment Protection (Production)

1. Go to Settings → Environments → production
2. Add required reviewers
3. Set deployment branches to main only

Test It (1 minute)

git checkout -b test-deployment
# Make a small change to environments/test/main.tf
git add . && git commit -m "test: verify pipeline"
git push origin test-deployment

✅ GitHub Actions runs automatically ✅ TFLint + Checkov scan ✅ Security scans fail closed before deploy ✅ Terraform plan posted to PR ✅ Merge to deploy

📚 Full Documentation

For detailed information including project structure, common commands, troubleshooting, and best practices, visit the → official documentation.

Author

Danny Steenman