Install

Set up the AWS Terraform Starter Kit, configure your environments, bootstrap your backend, and deploy your first infrastructure.

Prerequisites

  • AWS CLI configured with credentials (SSO or IAM user)
  • Git
  • Optional: Terraform, TFLint, Checkov (can be installed via make install-tools)
  • Optional: Granted for easier multi-account AWS access

1) Copy the starter kit

  1. Click the green "Use this template" button to create a new repository based on this starter kit.
  2. Clone your new repository:
git clone https://github.com/YOUR-USERNAME/YOUR-REPO-NAME
cd YOUR-REPO-NAME

2) Install tools (optional)

Install Terraform and other tools if not already installed:

make install-tools

This installs Terraform, AWS CLI, TFLint, Checkov, and Granted.

Check installed versions:

make check

For details on all available commands, see the Makefile reference.

3) Configure AWS credentials

Authenticate to your AWS account:

# With AWS SSO
aws sso login --profile my-profile

# Or with Granted
assume my-profile

For AWS CLI setup with SSO, see setting up the AWS CLI with AWS SSO.

4) Run the setup wizard

Run the setup wizard to bootstrap everything:

make setup

The wizard guides you through four steps:

Step 1: Prerequisites verification

  • Checks for required tools (AWS CLI, Terraform, Git)
  • Validates AWS credentials and captures your account ID

Step 2: Backend bootstrap

Creates the Terraform state backend:

  • S3 bucket with versioning and encryption
  • DynamoDB table for state locking
  • Saves configuration to .terraform-backend.conf

Step 3: Environment provisioning

  • Auto-detects your GitHub repository from git remote
  • Prompts for environment name (e.g., staging, production)
  • Generates environment files:
    • environments/<env>/backend.tf
    • environments/<env>/main.tf
    • environments/<env>/variables.tf
    • environments/<env>/outputs.tf
    • .github/workflows/terraform-deploy-<env>.yml

Step 4: OIDC deployment

  • Initializes Terraform in the environment directory
  • Checks for existing OIDC provider (reuses if found)
  • Creates GitHub Actions IAM role
  • Applies changes with confirmation
  • Displays role ARN for GitHub Actions

Multi-account setup: Run the wizard multiple times with different AWS profiles to deploy environments to separate accounts.

5) Verify deployment

Check that resources were created:

# View S3 state bucket
aws s3 ls | grep terraform-state

# View DynamoDB lock table
aws dynamodb list-tables | grep terraform-state-lock

# View Terraform outputs
cd environments/staging
terraform output

6) Start building

Add your infrastructure to the environment:

  1. Edit environments/staging/main.tf to add resources
  2. Run commands:
make plan ENV=staging   # Preview changes
make apply ENV=staging  # Deploy infrastructure

See the Makefile reference for all available commands.

7) Enable CI/CD

Push your changes to GitHub:

git add .
git commit -m "Initial setup"
git push origin main

The generated GitHub Actions workflows will automatically run on pull requests and pushes to main.

See CI/CD Workflow for details.

Advanced options

Non-interactive setup

Use flags for automation:

make setup -e AUTO_APPROVE=true              # Skip confirmations
make setup -e SKIP_BOOTSTRAP=true            # Skip backend creation
make setup -e SKIP_DEPLOY=true               # Skip OIDC deployment

Multi-account deployment

Deploy environments to separate AWS accounts:

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

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

Each account gets its own backend and OIDC provider.

Next steps

← OverviewConfiguration →