OpenTofu Coder

⚠️ SIMPLICITY FIRST - Default to Flat Files

ALWAYS start with the simplest approach. Only add complexity when explicitly requested.

Simple (DEFAULT) vs Overengineered

Aspect

✅ Simple (Default)

❌ Overengineered

Structure

Flat .tf files in one directory

Nested modules/ + environments/ directories

Modules

None or only remote registry modules

Custom local modules for simple resources

Environments

Workspaces OR single tfvars

Duplicate directory per environment

Variables

Inline defaults, minimal tfvars

Complex variable hierarchies

File count

3-5 .tf files total

15+ files across nested directories

When to Use Simple Approach (90% of cases)

Managing 1-5 resources of each type

Single provider, single region

Small team or solo developer

Standard infrastructure patterns

When Complexity is Justified (10% of cases)

Enterprise multi-region, multi-account

Reusable modules shared across teams

Complex dependency chains

User explicitly requests modular structure

Rule: If you can define everything in 5 flat .tf files, DO IT.

Simple Project Structure (DEFAULT)

infra/

├── main.tf # All resources

├── variables.tf # Input variables

├── outputs.tf # Outputs

├── versions.tf # Provider versions

└── terraform.tfvars # Variable values (gitignored)

Overview

OpenTofu is a community-driven, open-source fork of Terraform under MPL-2.0 license, maintained by the Linux Foundation. It uses HashiCorp Configuration Language (HCL) for declarative infrastructure management across cloud providers.

Core Philosophy

Prioritize:

Declarative over imperative

Describe desired state, not steps

Idempotency

Apply safely multiple times with same result

Modularity

Compose infrastructure from reusable modules

State as truth

State file is the source of truth for managed resources

Immutable infrastructure

Replace resources rather than mutate in place HCL Syntax Essentials Resource Blocks resource "aws_instance" "web" { ami = var.ami_id instance_type = var.instance_type tags = { Name = " $ { var . project } -web" Environment = var.environment } } Data Sources data "aws_ami" "ubuntu" { most_recent = true filter { name = "name" values = [ "ubuntu/images/hvm-ssd/ubuntu-jammy-22.04-amd64-server-*" ] } owners = [ "099720109477" ]

Canonical

} Variables variable "environment" { description = "Deployment environment (dev, staging, prod)" type = string default = "dev" validation { condition = contains( [ "dev" , "staging" , "prod" ] , var.environment) error_message = "Environment must be dev, staging, or prod." } } variable "instance_types" { description = "Map of environment to instance type" type = map(string) default = { dev = "t3.micro" staging = "t3.small" prod = "t3.medium" } } Outputs output "instance_ip" { description = "Public IP of the web instance" value = aws_instance.web.public_ip sensitive = false } output "database_password" { description = "Generated database password" value = random_password.db.result sensitive = true } Locals locals { common_tags = { Project = var.project Environment = var.environment ManagedBy = "OpenTofu" } name_prefix = " $ { var . project } - $ { var . environment } " } Meta-Arguments count - Create Multiple Instances resource "aws_instance" "server" { count = var.server_count ami = var.ami_id instance_type = var.instance_type tags = { Name = " $ { local . name_prefix } -server- $ { count . index } " } } for_each - Create from Map/Set resource "aws_iam_user" "users" { for_each = toset(var.user_names) name = each.value path = "/users/" } resource "aws_security_group_rule" "ingress" { for_each = var.ingress_rules type = "ingress" from_port = each.value.port to_port = each.value.port protocol = each.value.protocol cidr_blocks = each.value.cidr_blocks security_group_id = aws_security_group.main.id } depends_on - Explicit Dependencies resource "aws_instance" "app" { ami = var.ami_id instance_type = var.instance_type depends_on = [ aws_db_instance.database, aws_elasticache_cluster.cache ] } lifecycle - Control Resource Behavior resource "aws_instance" "critical" { ami = var.ami_id instance_type = var.instance_type lifecycle { prevent_destroy = true create_before_destroy = true ignore_changes = [ tags [ "LastUpdated" ] , user_data ] } }

Replace when AMI changes

resource "aws_instance" "immutable" { ami = var.ami_id instance_type = var.instance_type lifecycle { replace_triggered_by = [ null_resource.ami_trigger ] } } Module Design Module Structure modules/ └── vpc/ ├── main.tf # Primary resources ├── variables.tf # Input variables ├── outputs.tf # Output values ├── versions.tf # Required providers └── README.md # Documentation Calling Modules module "vpc" { source = "./modules/vpc" cidr_block = "10.0.0.0/16" environment = var.environment azs = [ "us-east-1a" , "us-east-1b" ] private_subnets = [ "10.0.1.0/24" , "10.0.2.0/24" ] public_subnets = [ "10.0.101.0/24" , "10.0.102.0/24" ] }

Remote module with version

module "eks" { source = "terraform-aws-modules/eks/aws" version = "~> 20.0" cluster_name = local.cluster_name cluster_version = "1.29" vpc_id = module.vpc.vpc_id subnet_ids = module.vpc.private_subnet_ids } Module Best Practices Expose minimal, clear interface of variables Use sensible defaults where possible Document all variables and outputs Avoid over-generic "god" modules Prefer composition over configuration flags Version pin remote modules State Management Remote Backend (S3) terraform { backend "s3" { bucket = "my-terraform-state" key = "prod/network/terraform.tfstate" region = "us-east-1" encrypt = true dynamodb_table = "terraform-locks" } } OpenTofu State Encryption (Unique Feature) terraform { encryption { key_provider "pbkdf2" "main" { passphrase = var.state_encryption_passphrase } method "aes_gcm" "encrypt" { keys = key_provider.pbkdf2.main } state { method = method.aes_gcm.encrypt enforced = true } plan { method = method.aes_gcm.encrypt enforced = true } } } State Commands

List resources in state

tofu state list

Show specific resource

tofu state show aws_instance.web

Move resource (refactoring)

tofu state mv aws_instance.old aws_instance.new

Remove from state (without destroying)

tofu state rm aws_instance.imported

Import existing resource

tofu import aws_instance.web i-1234567890abcdef0 See Provider Configuration for AWS provider setup, authentication methods, and multi-provider patterns. See Environment Strategies for workspaces and directory-based environment management. CLI Workflow

Initialize working directory

tofu init

Validate configuration

tofu validate

Format code

tofu fmt -recursive

Preview changes

tofu plan -out = plan.tfplan

Apply changes

tofu apply plan.tfplan

Destroy infrastructure

tofu destroy

Show current state

tofu show

Refresh state from actual infrastructure

tofu refresh Best Practices Checklist When writing OpenTofu/Terraform code: Use remote backend with locking for team use Enable state encryption (OpenTofu feature) Never commit .tfstate or .tfvars with secrets to VCS Pin provider and module versions Use tofu plan before every apply Use lifecycle.prevent_destroy for critical resources Document all variables and outputs Use locals for computed values and tags Prefer for_each over count for named resources Use validation blocks for variable constraints Store secrets in secret managers, not in code Common Patterns Conditional Resources resource "aws_eip" "static" { count = var.create_elastic_ip ? 1 : 0 instance = aws_instance.web.id } Dynamic Blocks resource "aws_security_group" "main" { name = " $ { local . name_prefix } -sg" dynamic "ingress" { for_each = var.ingress_rules content { from_port = ingress.value.port to_port = ingress.value.port protocol = ingress.value.protocol cidr_blocks = ingress.value.cidr_blocks } } } References For detailed patterns and examples: references/hcl-patterns.md - Advanced HCL patterns references/project-scaffolding.md - Directory structure, .gitignore, next_steps output, security-first variables references/post-provisioning.md - bin/setup-server scripts for post-infra, pre-deployment setup references/state-management.md - State operations and encryption references/provider-examples.md - Multi-cloud provider configs references/makefile-automation.md - Makefile workflows for plan/apply/destroy