Project Structure

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

Overview

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

Note: Most files (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
│       ├── terraform.tfvars               # Variable values for OIDC
│       └── 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:

FilePurpose
backend.tfS3 backend configuration with unique state key
main.tfAWS provider and OIDC module instantiation
variables.tfInput variable definitions with defaults
outputs.tfOutputs from the OIDC module (role ARN, OIDC provider ARN)
terraform.tfvarsVariable values for OIDC configuration

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 OIDC Provider for details.

scripts/

Automation scripts:

ScriptPurpose
setup.shSetup wizard for backend bootstrap, environment provisioning, OIDC deployment
cleanup.shCleanup utility for removing environments, backend infrastructure, local files

Both scripts support interactive prompts and command-line flags.

.github/workflows/

CI/CD workflows:

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

See CI/CD Workflows for details.

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 commands. See the Makefile reference for complete documentation.

.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

← ConfigurationEnvironments →