Makefile

Overview

The Makefile provides a unified interface for managing the Terraform Starter Kit lifecycle, from initial setup to daily operations. It wraps Terraform commands with validation, error handling, and environment management.

Quick reference

Command	Description
`make help`	Display all available commands
`make setup`	Complete setup wizard
`make install-tools`	Install required development tools
`make check`	Check installed tool versions
`make validate-full`	Run all validation checks
`make validate-env ENV=x`	Validate specific environment
`make format`	Format Terraform files
`make lint`	Run TFLint checks
`make security-scan`	Run Checkov security scan
`make init ENV=<env>`	Initialize Terraform for an environment
`make plan ENV=<env>`	Create Terraform plan
`make apply ENV=<env>`	Apply Terraform changes
`make destroy ENV=<env>`	Destroy Terraform resources
`make cleanup`	Interactive cleanup script

Setup commands

make setup

Run the complete setup wizard that bootstraps infrastructure, provisions environments, and deploys OIDC configuration.

What it does:

Checks prerequisites (AWS CLI, Terraform, Git)
Verifies AWS credentials
Creates S3 backend with native state locking
Provisions environment directories and workflows
Deploys OIDC provider and IAM roles

Usage:

make setup                              # Interactive setup
./scripts/setup.sh -e test,staging -a   # Auto-approve
./scripts/setup.sh --skip-bootstrap     # Use existing backend

Script options:

Option	Description
`-e, --environments ENV1,ENV2`	Comma-separated list of environments
`-p, --profile PROFILE`	AWS profile to use
`-a, --auto-approve`	Skip interactive confirmations
`-s, --skip-bootstrap`	Skip bootstrap step
`-d, --skip-deploy`	Skip OIDC deployment

make install-tools

Install required and optional development tools.

Tool	Status	Purpose
Terraform	Required	Infrastructure as code
AWS CLI	Required	AWS command-line interface
TFLint	Optional	Terraform linter
Checkov	Optional	Security scanner
Granted	Optional	AWS profile manager

make install-tools

Validation commands

make validate-full

Run comprehensive validation across all environments.

Step	Description
Formatting	Verifies Terraform file formatting
Validation	Validates Terraform syntax
TFLint	Runs linting checks
Checkov	Performs security analysis

make validate-full

make validate-env

Validate Terraform configuration for a specific environment.

make validate-env ENV=staging
make validate-env ENV=staging ARGS="-json"

make lint

Run TFLint checks across all Terraform files.

make lint

make security-scan

Run Checkov security scan on Terraform code.

make security-scan

make format

Format all Terraform files recursively.

make format

Deployment commands

All deployment commands require the ENV parameter.

make init

Initialize Terraform backend for an environment.

make init ENV=staging
make init ENV=staging ARGS="-upgrade"
make init ENV=staging ARGS="-reconfigure"

make plan

Create a Terraform execution plan.

make plan ENV=staging
make plan ENV=staging ARGS="-out=tfplan"
make plan ENV=staging ARGS="-target=module.oidc_provider"

make apply

Apply Terraform changes.

make apply ENV=staging
make apply ENV=staging ARGS="-auto-approve"
make apply ENV=staging ARGS="tfplan"

Warning: Use -auto-approve carefully in production.

make destroy

Destroy Terraform-managed infrastructure.

make destroy ENV=test
make destroy ENV=staging ARGS="-auto-approve"
make destroy ENV=staging ARGS="-target=module.oidc_provider"

Utility commands

make cleanup

Interactive cleanup script with options:

Option	Description
Destroy environment resources	Removes OIDC providers, IAM roles
Destroy bootstrap resources	Removes S3 bucket
Clean local files	Removes `.terraform/`, lock files
Remove source files	Deletes environment directories
Full cleanup	All of the above

make cleanup

make check

Check versions of all required and optional tools.

make check

Environment variables

Variable	Description	Example
`ENV`	Target environment	`ENV=staging`
`ARGS`	Additional Terraform arguments	`ARGS="-auto-approve"`
`AWS_PROFILE`	AWS profile to use	`AWS_PROFILE=staging`
`AWS_REGION`	AWS region	`AWS_REGION=us-east-1`

Common workflows

Initial setup

make install-tools
make setup
make check

Development workflow

make validate-full
make format
make init ENV=staging
make plan ENV=staging
make apply ENV=staging

Multi-environment deployment

# Test
make plan ENV=test && make apply ENV=test

# Staging
make plan ENV=staging && make apply ENV=staging

# Production (with saved plan)
make plan ENV=production ARGS="-out=tfplan"
make apply ENV=production ARGS="tfplan"

Error handling

Missing ENV parameter

$ make plan
❌ Error: ENV variable is required
Usage: make plan ENV=staging

Invalid environment

$ make plan ENV=nonexistent
❌ Error: Environment 'nonexistent' does not exist

Missing tools

$ make lint
TFLint not installed. Run 'make install-tools' to install.

Troubleshooting

State lock issues

cd environments/staging
terraform force-unlock <LOCK_ID>

Backend configuration issues

cat .terraform-backend.conf
aws s3 ls s3://terraform-state-ACCOUNT-REGION
make init ENV=staging ARGS="-reconfigure"

Permission errors

aws sts get-caller-identity
assume staging-account

Next steps

CI/CD Workflows - Deployment automation
Local Development - Day-to-day workflows
OIDC Provider - Module reference