Makefile

Overview

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

Quick Reference

make help              # Display all available commands
make setup             # Complete setup wizard (bootstrap + provision + OIDC)
make install-tools     # Install required development tools
make validate-full     # Run all validation checks
make init ENV=test     # Initialize Terraform for an environment
make plan ENV=test     # Create Terraform plan
make apply ENV=test    # Apply Terraform changes
make cleanup           # Interactive cleanup script

Setup Commands

`make setup`

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

What it does:

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

Usage:

# Interactive setup (recommended for first time)
make setup

# Or run the script directly with options
./scripts/setup.sh -e test,staging -a
./scripts/setup.sh -p production-admin
./scripts/setup.sh --skip-bootstrap

Script options:

-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 (use existing backend)
-d, --skip-deploy — Skip OIDC deployment (only create files)
-h, --help — Display help message

`make install-tools`

Install required and optional development tools for the starter kit.

Tools installed:

Terraform — Infrastructure as code (required)
AWS CLI — AWS command-line interface (required)
TFLint — Terraform linter (optional, for validation)
Checkov — Security scanner (optional, for validation)
Granted — AWS profile manager (optional, for multi-account access)

Platform support:

macOS (via Homebrew)
Linux (via package managers and direct downloads)

Usage:

make install-tools

Validation Commands

`make validate-full`

Run comprehensive validation across all environments. This command executes four validation steps in sequence.

Validation steps:

Formatting check — Verifies Terraform file formatting
Configuration validation — Validates Terraform syntax for all environments
TFLint scan — Runs linting checks for best practices
Checkov scan — Performs security analysis

Usage:

make validate-full

Exit codes:

0 — All validations passed
1 — One or more validations failed

`make validate-env`

Validate Terraform configuration for a specific environment.

Usage:

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

Parameters:

ENV — Environment name (required)
ARGS — Additional terraform validate arguments (optional)

`make lint`

Run TFLint checks across all Terraform files.

Usage:

make lint

Requirements:

TFLint must be installed (run make install-tools)
.tflint.hcl configuration file (created during setup)

`make security-scan`

Run Checkov security scan on Terraform code.

Usage:

make security-scan

Requirements:

Checkov must be installed (run make install-tools)
.checkov.yml configuration file (optional)

`make format`

Format all Terraform files recursively.

Usage:

make format

Deployment Commands

All deployment commands require the ENV parameter to specify which environment to operate on.

`make init`

Initialize Terraform backend for an environment.

Usage:

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

Parameters:

ENV — Environment name (required)
ARGS — Additional terraform init arguments (optional)

Common arguments:

-upgrade — Upgrade provider plugins to latest version
-reconfigure — Reconfigure backend ignoring saved configuration

`make plan`

Create a Terraform execution plan for an environment.

Usage:

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

Parameters:

ENV — Environment name (required)
ARGS — Additional terraform plan arguments (optional)

Common arguments:

-out=tfplan — Save plan to file
-target=RESOURCE — Plan only specific resource
-var="key=value" — Override variable values

`make apply`

Apply Terraform changes to an environment.

Usage:

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

Parameters:

ENV — Environment name (required)
ARGS — Additional terraform apply arguments (optional)

Common arguments:

-auto-approve — Skip confirmation prompt
tfplan — Apply a saved plan file

Warning: Use -auto-approve carefully, especially in production environments.

`make destroy`

Destroy Terraform-managed infrastructure in an environment.

Usage:

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

Parameters:

ENV — Environment name (required)
ARGS — Additional terraform destroy arguments (optional)

Warning: This command permanently deletes resources. Always review the plan before confirming.

Utility Commands

`make cleanup`

Run the interactive cleanup script to remove resources and files.

Cleanup options:

Destroy all environment resources — Removes OIDC providers, IAM roles, etc.
Destroy bootstrap resources — Removes S3 bucket and DynamoDB table
Clean local files — Removes cached Terraform files (.terraform, lock files)
Remove source files — Deletes environment directories and workflow files
Full cleanup — Combines all cleanup operations

Usage:

make cleanup

Important notes:

Destroying bootstrap resources removes the Terraform state backend
Always destroy environment resources before destroying bootstrap
Removing source files deletes committed code (use with caution)
The script includes safety confirmations for destructive operations

`make check`

Check versions of all required and optional tools.

Usage:

make check

Output example:

Terraform: Terraform v1.9.8
AWS CLI: aws-cli/2.15.0 Python/3.11.6
TFLint: TFLint version 0.50.0
Checkov: 3.2.255
Granted: assume installed

Environment Variables

The Makefile respects the following environment variables:

Variable	Description	Example
`ENV`	Target environment for deployment commands	`ENV=production`
`ARGS`	Additional arguments for Terraform commands	`ARGS="-auto-approve"`
`AWS_PROFILE`	AWS profile to use	`AWS_PROFILE=production-admin`
`AWS_REGION`	AWS region for operations	`AWS_REGION=us-east-1`

Examples

Initial Setup Workflow

# 1. Install required tools
make install-tools

# 2. Run setup wizard
make setup

# 3. Verify installations
make check

Development Workflow

# 1. Validate all code
make validate-full

# 2. Format code
make format

# 3. Initialize environment
make init ENV=test

# 4. Plan changes
make plan ENV=test

# 5. Apply changes
make apply ENV=test

Multi-Environment Deployment

# Test environment
make init ENV=test
make plan ENV=test
make apply ENV=test

# Staging environment
make init ENV=staging
make plan ENV=staging
make apply ENV=staging

# Production environment (with review)
make init ENV=production
make plan ENV=production ARGS="-out=tfplan"
# Review plan carefully
make apply ENV=production ARGS="tfplan"

Upgrading Provider Versions

# Upgrade and reinitialize
make init ENV=production ARGS="-upgrade"

# Verify with plan
make plan ENV=production

Cleanup and Removal

# Remove test environment resources
make destroy ENV=test

# Full cleanup (interactive)
make cleanup

Error Handling

The Makefile includes error handling for common issues:

Missing ENV Parameter

$ make plan
❌ Error: ENV variable is required
Usage: make plan ENV=production
       make plan ENV=production ARGS="-out=tfplan"

Invalid Environment

$ make plan ENV=nonexistent
❌ Error: Environment 'nonexistent' does not exist
Available environments:
  test
  staging
  production

Missing Tools

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

Best Practices

Daily Operations

Always validate before deploying:
```
make validate-full
```

Review plans before applying:

make plan ENV=production
# Review output carefully
make apply ENV=production

Use saved plans for production:

make plan ENV=production ARGS="-out=tfplan"
make apply ENV=production ARGS="tfplan"

Tool Management

Keep tools updated:

make install-tools  # Detects and updates existing tools

Verify installations regularly:
```
make check
```

Security

Run security scans before deployments:
```
make security-scan
```

Never commit plans with sensitive data:

# Add to .gitignore
echo "*.tfplan" >> .gitignore

Use -auto-approve sparingly:

# Avoid in production
make apply ENV=production ARGS="-auto-approve"

Troubleshooting

State Lock Issues

If Terraform state is locked:

# Check DynamoDB for lock
aws dynamodb scan \
  --table-name terraform-state-lock \
  --region us-east-1

# Force unlock (use carefully)
cd environments/production
terraform force-unlock <LOCK_ID>

Backend Configuration Issues

If backend initialization fails:

# Verify backend configuration
cat .terraform-backend.conf

# Verify S3 bucket exists
aws s3 ls s3://terraform-state-ACCOUNT-REGION

# Reconfigure backend
make init ENV=production ARGS="-reconfigure"

Permission Errors

If AWS operations fail:

# Verify credentials
aws sts get-caller-identity

# Check assumed role
aws sts get-caller-identity --profile production-admin

# Use Granted to assume role
assume production-admin

Next Steps

Learn about CI/CD Workflow automation
Understand Project Structure
Explore Local Development best practices
Review OIDC Provider module details