Install

Set up the AWS Terraform Starter Kit with automated backend bootstrap, OIDC configuration, and first deployment.

Overview

Get from zero to deployed infrastructure in under 15 minutes. The setup wizard handles backend creation, OIDC configuration, and environment provisioning.

Prerequisites

RequirementDescription
AWS CLIConfigured with credentials (SSO or IAM user)
GitFor cloning and version control
TerraformOptional (can install via make install-tools)
TFLint/CheckovOptional (can install via make install-tools)
GrantedOptional, for easier multi-account access

1. Copy the starter kit

Click the green "Use this template" button to create your repository, then clone it:

git clone https://github.com/YOUR-USERNAME/YOUR-REPO-NAME
cd YOUR-REPO-NAME

2. Install tools (optional)

Install Terraform and related tools if not already installed:

make install-tools

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

Verify installations:

make check

See the Makefile reference for all available commands.

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 interactive setup wizard:

make setup

The wizard walks 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 for state storage
  • Native locking using S3's built-in locking (Terraform 1.10+)
  • Saves configuration to .terraform-backend.conf

Step 3: Environment provisioning

  • Auto-detects your GitHub repository from git remote
  • Prompts for environment name (test, staging, or production)
  • Generates environment files:
FilePurpose
environments/<env>/backend.tfState backend configuration
environments/<env>/main.tfRoot module for resources
environments/<env>/variables.tfEnvironment variables
environments/<env>/outputs.tfOutput definitions
environments/<env>/terraform.tfvarsVariable values for OIDC
.github/workflows/terraform-deploy-<env>.ymlCI/CD workflow

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

Note: 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 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. Preview and deploy:
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 workflows automatically run on pull requests and pushes to main.

See CI/CD Workflows for details.

Advanced options

Non-interactive setup

Use flags for automation by calling the setup script directly:

./scripts/setup.sh -a              # Skip confirmations (auto-approve)
./scripts/setup.sh -s              # Skip backend creation
./scripts/setup.sh -d              # Skip OIDC deployment
./scripts/setup.sh -e test -a      # Auto-approve for test environment

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 →