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+)
  • Generates environment-specific Terraform configurations
  • Provisions OIDC provider for secure keyless authentication
  • 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 to catch issues before you deploy to AWS

📋 Prerequisites

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

That's it! All other tools (Terraform, AWS CLI, 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 (3 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. ✅ Provisions environment (test/staging/production)
4. ✅ Deploys OIDC provider + IAM role so you can deploy securely via GitHub
5. ✅ Generates GitHub workflow files

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. Repository Variables (Optional)

All values are embedded as defaults - only set if you want to override:

• AWS_ACCOUNT_ID (already hardcoded)
• AWS_REGION
• TF_STATE_BUCKET

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 ✅ 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