Terraform Infrastructure Components Template

A template repository for creating reusable Terraform components that are consumed by Atmos stacks. Each component is a self Terraform root module that gets referenced from your stacks repo through source pinning with versioned tags.

Repository Structure

.
├── components/terraform/
│   └── <component-name>/
│       ├── main.tf          # Resource definitions and module calls
│       ├── variables.tf     # Input variable declarations
│       ├── outputs.tf       # Output value declarations
│       ├── versions.tf      # Terraform and provider version constraints
│       ├── provider.tf      # Provider configuration
│       └── data.tf          # Data source lookups
├── .github/workflows/
│   ├── terraform-validate.yaml   # Runs fmt check and validate on PR
│   ├── pr-title-check.yaml       # Enforces conventional commit PR titles
│   └── release-version.yaml      # Semantic versioning on merge to main
├── .gitignore
└── .releaserc.json

How It Works

1. Each component live under components/terraform/<component-name>/
2. Stacks repos reference components from this repo using source pinning:

   source:
     uri: github.com/<org>/<this-repo>.git//components/terraform/<component-name>
     version: v1.0.0

3. When changes are merged to main, semantic-release auto-creates a new version tag based on commit messages

Getting Started

1. Use this repo as a GitHub template
2. Remove the sample-component directory
3. Create your component under components/terraform/<your-component>/ with the standard files (main.tf, variables.tf, outputs.tf, versions.tf, provider.tf, data.tf)
4. Install and configure pre-commit hooks:

   # Install pre-commit (if not already installed)
   pip install pre-commit
   # or with homebrew: brew install pre-commit
   
   # Install the git hooks
   pre-commit install
   
   # (Optional) Run against all files
   pre-commit run --all-files

5. Open a PR with a commit title (e.g., feat: Add s3 component)
6. On merge, a version tag is automatically created

Adding a New Component

mkdir -p components/terraform/<component-name>
touch components/terraform/<component-name>/{main,variables,outputs,versions,provider,data}.tf

Every component should include these baseline variables:

Variable	Description
aws_region	AWS region for deployment
environment	Environment name (dev, staging, prod)
tags	Map of tags applied to all resources
stage	Atmos stage name for state management

Pre-commit Hooks

This repository includes pre-commit hooks to ensure code quality:

Hook	Description
check-merge-conflict	Prevents committing files with merge conflict markers
terraform_fmt	Automatically formats Terraform files to canonical format
terraform_validate	Validates Terraform configuration syntax

CI/CD

Workflow	Trigger	Description
pre-commit.yaml	PR to main	Runs pre-commit hooks (merge conflict check, terraform fmt, terraform validate)
terraform-validate.yaml	PR to main	Checks formatting and runs terraform validate on each component
pr-title-check.yaml	PR opened/edited	Validates PR title follows conventional commits (feat:, fix:, chore:, etc.)
release-preview.yaml	PR to main	Previews the next semantic version and release notes via dry-run
release-version.yaml	Push to main	Creates a semantic version tag via semantic-release

Components

• sample-component: A template to use as a reference when adding new components