Project Structure

Understand how the AWS Terraform Starter Kit organizes modules, environments, configuration, and automation.

Overview

The starter kit is organized for multi-environment Terraform deployments with reusable modules and automated workflows.

Note: Most files discussed here (environments, workflows) are automatically generated by the make setup command. See the Install guide.

Directory structure

.
├── .github/
│   ├── workflows/
│   │   ├── checkov-scan.yml              # Reusable security scan
│   │   ├── terraform-deploy-staging.yml  # Generated per environment
│   │   ├── terraform-plan-pr-comment.yml # Reusable plan commenter
│   │   └── tflint-scan.yml               # Reusable linting
│   └── pull_request_template.md
├── .vscode/
│   └── extensions.json                    # Recommended VS Code extensions
├── environments/                          # Generated by setup wizard
│   └── staging/
│       ├── backend.tf                     # S3 backend config
│       ├── main.tf                        # Provider and OIDC module
│       ├── outputs.tf                     # Module outputs
│       └── variables.tf                   # Input variables
├── modules/
│   └── oidc-provider/                     # GitHub Actions OIDC module
│       ├── main.tf
│       ├── outputs.tf
│       ├── variables.tf
│       └── versions.tf
├── scripts/
│   ├── cleanup.sh                         # Resource cleanup utility
│   └── setup.sh                           # Setup wizard
├── .checkov.yml                           # Checkov security config
├── .gitignore
├── .tflint.hcl                           # TFLint configuration
├── LICENSE
├── Makefile                              # Command shortcuts
└── README.md

Key directories

environments/

Generated by make setup. Each environment directory contains:

  • backend.tf — S3 backend configuration with unique state key
  • main.tf — AWS provider and OIDC module instantiation
  • variables.tf — Input variable definitions with defaults
  • outputs.tf — Outputs from the OIDC module (role ARN, OIDC provider ARN)

Each environment uses its own state file in S3 (e.g., environments/staging/terraform.tfstate) for complete isolation.

See Environments for details.

modules/

Reusable Terraform modules:

  • oidc-provider/ — Creates GitHub Actions OIDC provider and IAM role for CI/CD authentication

To add custom modules, create a new directory under modules/ with standard Terraform files (main.tf, variables.tf, outputs.tf, versions.tf).

See Modules for details.

scripts/

Automation scripts:

  • setup.sh — Setup wizard for backend bootstrap, environment provisioning, OIDC deployment, and workflow generation
  • cleanup.sh — Cleanup utility for removing environments, backend infrastructure, and local files

Both scripts support interactive prompts and command-line flags.

.github/workflows/

CI/CD workflows (see CI/CD Workflow):

Reusable workflows:

  • tflint-scan.yml — Terraform code linting
  • checkov-scan.yml — Security scanning
  • terraform-plan-pr-comment.yml — Posts plan to PR comments

Environment-specific workflows (generated by make setup):

  • terraform-deploy-staging.yml
  • terraform-deploy-production.yml
  • etc.

Key files

Makefile

Command shortcuts for common operations:

Setup and tools:

make setup              # Run setup wizard
make install-tools      # Install Terraform, AWS CLI, TFLint, Checkov
make check              # Check tool versions

Validation:

make validate-full      # Run format, validate, lint, and security scan
make lint               # Run TFLint
make security-scan      # Run Checkov

Environment operations:

make init ENV=staging   # Initialize Terraform
make plan ENV=staging   # Create deployment plan
make apply ENV=staging  # Apply changes

Run make help to see all available commands. For complete documentation, see the Makefile reference.

.tflint.hcl

TFLint configuration for code quality checks. Used by both local development (make lint) and CI/CD (tflint-scan.yml workflow).

.checkov.yml

Checkov security scanning configuration. Used by local development (make security-scan) and CI/CD (checkov-scan.yml workflow).

Next steps

  • Follow the Install guide to set up your first environment
  • Learn about Environments for multi-environment management
  • Explore the Modules reference
← ConfigurationEnvironments →