Makefile

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

Setup Commands

make setup

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

What it does:

1. Checks prerequisites (AWS CLI, Terraform, Git)
2. Verifies AWS credentials
3. Creates S3 backend with native state locking
4. Provisions environment directories and workflows
5. 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:

make install-tools

Install required and optional development tools for the starter kit.

Tools Installed:

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.

Validation Steps:

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.

Parameters:

Usage:

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

make lint

Run TFLint checks across all Terraform files.

Requirements:

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

Usage:

make lint

make security-scan

Run Checkov security scan on Terraform code.

Requirements:

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

Usage:

make security-scan

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.

Parameters:

Common Arguments:

Usage:

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

make plan

Create a Terraform execution plan for an environment.

Parameters:

Common Arguments:

Usage:

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

make apply

Apply Terraform changes to an environment.

Parameters:

Common Arguments:

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

Usage:

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

make destroy

Destroy Terraform-managed infrastructure in an environment.

Parameters:

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

Usage:

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

Utility Commands

make cleanup

Run the interactive cleanup script to remove resources and files.

Cleanup Options:

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

Usage:

make cleanup

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

Common Workflows

Initial Setup

# 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

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

1. Always validate before deploying:

   make validate-full
   

2. Review plans before applying:

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

3. Use saved plans for production:

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

Tool Management

1. Keep tools updated:

   make install-tools  # Detects and updates existing tools
   

2. Verify installations regularly:

   make check
   

Security

1. Run security scans before deployments:

   make security-scan
   

2. Never commit plans with sensitive data:

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

3. Use -auto-approve sparingly:

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

Troubleshooting

State Lock Issues

If Terraform state is locked, you can force unlock it:

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

Note: With S3 native locking (Terraform 1.10+), lock files are stored in S3 alongside state files as .tflock files.

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 Workflows automation
• Understand Project Structure
• Explore Local Development best practices
• Review OIDC Provider module details