Terraform Design Skill
When to activate
When designing new Terraform projects, refactoring module structure, establishing variable taxonomy, planning remote state configuration, or architecting multi-environment infrastructure with Terraform.
When NOT to use
For one-off infrastructure scripts or temporary testing environments that don't require modularity, versioning, or team collaboration.
Instructions
Design Phase
Start with infrastructure requirements and decompose into modules:
Identify module boundaries: Groups of resources that are logically cohesive, reusable, and independently managed
- Core infrastructure: VPC, subnets, route tables, NAT gateways
- Compute: ECS clusters, Kubernetes worker nodes, Lambda layers
- Databases: RDS instances, DynamoDB tables, Elasticache clusters
- Security: IAM roles, policies, KMS keys, security groups
- Observability: CloudWatch, Prometheus, ELK stack
Design variable taxonomy:
- Required inputs: CIDR blocks, instance types, database sizes
- Optional inputs with sensible defaults: environment tags, replica counts
- Use
type constraints: string, number, list(string), object({...})
- Add
validation blocks for non-obvious constraints
- Document with
description and sensitive flags
Design outputs:
- Export only what consumers need: VPC ID, security group IDs, database endpoints
- Use descriptive names:
vpc_id, private_subnet_ids, rds_endpoint
- Add
description to every output
Plan state management:
- Local state only for dev/local testing
- Remote state for all production infrastructure:
- Backend: S3 + DynamoDB for AWS, Cloud Storage + Firestore for GCP, Storage Account for Azure
- Encryption at rest and in transit
- State locking to prevent concurrent modifications
- Separate state files per environment: dev, staging, prod
- Never commit state files; use
.gitignore
Design directory structure:
terraform/
├── modules/ # Reusable modules
│ ├── vpc/
│ ├── rds/
│ ├── security_group/
│ └── iam/
├── environments/ # Environment-specific configs
│ ├── dev/
│ │ ├── main.tf
│ │ ├── variables.tfvars
│ │ └── backend.tf
│ ├── staging/
│ └── prod/
├── global/ # Shared infrastructure
│ ├── main.tf
│ └── variables.tf
├── main.tf # Root module
├── variables.tf
├── outputs.tf
├── versions.tf
├── terraform.tfvars # Shared variables (non-sensitive)
└── README.md
Module Implementation
# modules/vpc/main.tf
terraform {
required_version = ">= 1.5"
required_providers {
aws = {
source = "hashicorp/aws"
version = "~> 5.0"
}
}
}
variable "project_name" {
type = string
description = "Project name for resource naming"
}
variable "vpc_cidr" {
type = string
description = "CIDR block for VPC"
validation {
condition = can(cidrhost(var.vpc_cidr, 0))
error_message = "vpc_cidr must be a valid CIDR block"
}
}
variable "enable_nat_gateway" {
type = bool
default = true
description = "Enable NAT Gateway for private subnet egress"
}
variable "tags" {
type = map(string)
default = {}
description = "Common tags for all resources"
}
resource "aws_vpc" "main" {
cidr_block = var.vpc_cidr
enable_dns_hostnames = true
enable_dns_support = true
tags = merge(
var.tags,
{
Name = "${var.project_name}-vpc"
}
)
}
resource "aws_subnet" "private" {
count = 3
vpc_id = aws_vpc.main.id
cidr_block = cidrsubnet(var.vpc_cidr, 2, count.index)
availability_zone = data.aws_availability_zones.available.names[count.index]
tags = merge(
var.tags,
{
Name = "${var.project_name}-private-subnet-${count.index + 1}"
Tier = "Private"
}
)
}
output "vpc_id" {
value = aws_vpc.main.id
description = "VPC ID"
}
output "vpc_cidr_block" {
value = aws_vpc.main.cidr_block
description = "VPC CIDR block"
}
output "private_subnet_ids" {
value = aws_subnet.private[*].id
description = "Private subnet IDs"
}
Remote State Configuration
# backend.tf
terraform {
backend "s3" {
bucket = "my-terraform-state"
key = "prod/terraform.tfstate"
region = "us-east-1"
encrypt = true
dynamodb_table = "terraform-locks"
}
}
Environment Variables
# environments/prod/variables.tfvars
project_name = "myapp"
vpc_cidr = "10.0.0.0/16"
enable_nat_gateway = true
tags = {
environment = "prod"
owner = "platform-team"
cost_center = "engineering"
}
Example
Scenario: Design Terraform for a microservices platform with VPC, EKS cluster, RDS database, and observability stack.
Solution:
Module structure:
modules/vpc/ — VPC, subnets, NAT, route tables
modules/eks/ — EKS cluster, worker nodes, node groups
modules/rds/ — RDS instance, subnet group, parameter group
modules/kms/ — Encryption keys
modules/monitoring/ — CloudWatch, application logs
Variables taxonomy:
- Required:
environment, vpc_cidr, cluster_version, db_instance_class
- Optional:
enable_nat_gateway=true, enable_monitoring=true, replica_count=3
- All inputs validated: CIDR format, EKS version compatibility, instance type whitelist
Outputs:
eks_cluster_name — For kubectl config
rds_endpoint — For application config
kms_key_arn — For encryption policies
nat_gateway_ips — For firewall rules
State strategy:
- Prod state in S3 with encryption, versioning, locking
- Separate state files:
prod/kubernetes.tfstate, prod/databases.tfstate
- State locked during terraform apply
Directory layout:
terraform/
├── modules/
│ ├── vpc/
│ ├── eks/
│ ├── rds/
│ ├── kms/
│ └── monitoring/
├── environments/prod/
│ ├── main.tf # Root module composition
│ ├── variables.tfvars
│ ├── backend.tf
│ └── outputs.tf
└── versions.tf # Provider versions (shared)
This design ensures:
- Modules are reusable across environments
- Variables parameterize all infrastructure
- State is safe and versioned
- Directory structure scales to 100+ resources
- New team members understand the layout
1---2name: terraform-design3description: Terraform Design Skill4metadata:5 source: https://skillmd.com/skills/uitbreidenos/terraform-design6---7# Terraform Design Skill89## When to activate1011When designing new Terraform projects, refactoring module structure, establishing variable taxonomy, planning remote state configuration, or architecting multi-environment infrastructure with Terraform.1213## When NOT to use1415For one-off infrastructure scripts or temporary testing environments that don't require modularity, versioning, or team collaboration.1617## Instructions1819### Design Phase2021Start with infrastructure requirements and decompose into modules:22231. **Identify module boundaries:** Groups of resources that are logically cohesive, reusable, and independently managed24 - Core infrastructure: VPC, subnets, route tables, NAT gateways25 - Compute: ECS clusters, Kubernetes worker nodes, Lambda layers26 - Databases: RDS instances, DynamoDB tables, Elasticache clusters27 - Security: IAM roles, policies, KMS keys, security groups28 - Observability: CloudWatch, Prometheus, ELK stack29302. **Design variable taxonomy:**31 - Required inputs: CIDR blocks, instance types, database sizes32 - Optional inputs with sensible defaults: environment tags, replica counts33 - Use `type` constraints: `string`, `number`, `list(string)`, `object({...})`34 - Add `validation` blocks for non-obvious constraints35 - Document with `description` and `sensitive` flags36373. **Design outputs:**38 - Export only what consumers need: VPC ID, security group IDs, database endpoints39 - Use descriptive names: `vpc_id`, `private_subnet_ids`, `rds_endpoint`40 - Add `description` to every output41424. **Plan state management:**43 - Local state only for dev/local testing44 - Remote state for all production infrastructure:45 - Backend: S3 + DynamoDB for AWS, Cloud Storage + Firestore for GCP, Storage Account for Azure46 - Encryption at rest and in transit47 - State locking to prevent concurrent modifications48 - Separate state files per environment: dev, staging, prod49 - Never commit state files; use `.gitignore`50515. **Design directory structure:**52 ```53 terraform/54 ├── modules/ # Reusable modules55 │ ├── vpc/56 │ ├── rds/57 │ ├── security_group/58 │ └── iam/59 ├── environments/ # Environment-specific configs60 │ ├── dev/61 │ │ ├── main.tf62 │ │ ├── variables.tfvars63 │ │ └── backend.tf64 │ ├── staging/65 │ └── prod/66 ├── global/ # Shared infrastructure67 │ ├── main.tf68 │ └── variables.tf69 ├── main.tf # Root module70 ├── variables.tf71 ├── outputs.tf72 ├── versions.tf73 ├── terraform.tfvars # Shared variables (non-sensitive)74 └── README.md75 ```7677### Module Implementation7879```hcl80# modules/vpc/main.tf81terraform {82 required_version = ">= 1.5"83 required_providers {84 aws = {85 source = "hashicorp/aws"86 version = "~> 5.0"87 }88 }89}9091variable "project_name" {92 type = string93 description = "Project name for resource naming"94}9596variable "vpc_cidr" {97 type = string98 description = "CIDR block for VPC"99 validation {100 condition = can(cidrhost(var.vpc_cidr, 0))101 error_message = "vpc_cidr must be a valid CIDR block"102 }103}104105variable "enable_nat_gateway" {106 type = bool107 default = true108 description = "Enable NAT Gateway for private subnet egress"109}110111variable "tags" {112 type = map(string)113 default = {}114 description = "Common tags for all resources"115}116117resource "aws_vpc" "main" {118 cidr_block = var.vpc_cidr119 enable_dns_hostnames = true120 enable_dns_support = true121122 tags = merge(123 var.tags,124 {125 Name = "${var.project_name}-vpc"126 }127 )128}129130resource "aws_subnet" "private" {131 count = 3132 vpc_id = aws_vpc.main.id133 cidr_block = cidrsubnet(var.vpc_cidr, 2, count.index)134 availability_zone = data.aws_availability_zones.available.names[count.index]135136 tags = merge(137 var.tags,138 {139 Name = "${var.project_name}-private-subnet-${count.index + 1}"140 Tier = "Private"141 }142 )143}144145output "vpc_id" {146 value = aws_vpc.main.id147 description = "VPC ID"148}149150output "vpc_cidr_block" {151 value = aws_vpc.main.cidr_block152 description = "VPC CIDR block"153}154155output "private_subnet_ids" {156 value = aws_subnet.private[*].id157 description = "Private subnet IDs"158}159```160161### Remote State Configuration162163```hcl164# backend.tf165terraform {166 backend "s3" {167 bucket = "my-terraform-state"168 key = "prod/terraform.tfstate"169 region = "us-east-1"170 encrypt = true171 dynamodb_table = "terraform-locks"172 }173}174```175176### Environment Variables177178```hcl179# environments/prod/variables.tfvars180project_name = "myapp"181vpc_cidr = "10.0.0.0/16"182enable_nat_gateway = true183tags = {184 environment = "prod"185 owner = "platform-team"186 cost_center = "engineering"187}188```189190## Example191192**Scenario:** Design Terraform for a microservices platform with VPC, EKS cluster, RDS database, and observability stack.193194**Solution:**1951961. **Module structure:**197 - `modules/vpc/` — VPC, subnets, NAT, route tables198 - `modules/eks/` — EKS cluster, worker nodes, node groups199 - `modules/rds/` — RDS instance, subnet group, parameter group200 - `modules/kms/` — Encryption keys201 - `modules/monitoring/` — CloudWatch, application logs2022032. **Variables taxonomy:**204 - Required: `environment`, `vpc_cidr`, `cluster_version`, `db_instance_class`205 - Optional: `enable_nat_gateway=true`, `enable_monitoring=true`, `replica_count=3`206 - All inputs validated: CIDR format, EKS version compatibility, instance type whitelist2072083. **Outputs:**209 - `eks_cluster_name` — For kubectl config210 - `rds_endpoint` — For application config211 - `kms_key_arn` — For encryption policies212 - `nat_gateway_ips` — For firewall rules2132144. **State strategy:**215 - Prod state in S3 with encryption, versioning, locking216 - Separate state files: `prod/kubernetes.tfstate`, `prod/databases.tfstate`217 - State locked during terraform apply2182195. **Directory layout:**220 ```221 terraform/222 ├── modules/223 │ ├── vpc/224 │ ├── eks/225 │ ├── rds/226 │ ├── kms/227 │ └── monitoring/228 ├── environments/prod/229 │ ├── main.tf # Root module composition230 │ ├── variables.tfvars231 │ ├── backend.tf232 │ └── outputs.tf233 └── versions.tf # Provider versions (shared)234 ```235236This design ensures:237- Modules are reusable across environments238- Variables parameterize all infrastructure239- State is safe and versioned240- Directory structure scales to 100+ resources241- New team members understand the layout