--- name: terraform-opentofu-module-architecture description: Master production-grade Terraform and OpenTofu module architecture, state management, dependency injection, testing, and multi-environment orchestration. --- # Terraform & OpenTofu Module Architecture Skill Guide This skill provides comprehensive standards, production patterns, anti-patterns, and actionable code guidelines for designing, building, testing, and maintaining modular Infrastructure as Code (IaC) using Terraform and OpenTofu. --- ## 1. Core Principles & Architecture Guidelines 1. **Strict Separation of Concerns**: - **Root Modules (Live/Environments)**: Instantiate reusable modules with environment-specific input values. Never contain resource declarations directly when reusable modules can be authored. - **Child Modules (Reusable Component)**: Abstract infrastructure resources into logical units (e.g., VPC, EKS/GKE, RDS/Cloud SQL). Must be environment-agnostic, parameter-driven, and highly composable. 2. **Standard Module Directory Structure**: ```text terraform-provider-name-modulename/ ├── main.tf # Primary resource definitions & orchestrations ├── variables.tf # Typed input variables with defaults & validation rules ├── outputs.tf # Explicit outputs with meaningful descriptions & types ├── versions.tf # Required terraform/opentofu version & provider constraints ├── dependencies.tf # Remote state data sources, provider bindings, or internal locals ├── README.md # Auto-generated documentation (terraform-docs) ├── examples/ # Runnable implementations │ ├── complete/ # Fully featured environment setup │ └── minimal/ # Basic getting-started configuration └── tests/ # Automated unit/integration tests (Native / Terratest) ├── unit_test.tftest.hcl └── integration_test.tftest.hcl ``` 3. **Immutability & State Management**: - Remote backend with explicit state locking (DynamoDB / S3, GCS, Cloudflare R2, or OpenTofu S3/HTTP backends). - Never share state files across separate environments or environments with different lifecycles; isolate by directory or repository (prefer directory-based layout over workspace-based layout for separate clouds/environments). --- ## 2. Production Code Standards & Examples ### A. Defensive Variable Definition & Validations (`variables.tf`) Always define explicit types, descriptions, and custom validation blocks. ```hcl variable "environment" { type = string description = "Deployment environment name (e.g., dev, staging, prod)." validation { condition = contains(["dev", "staging", "prod"], var.environment) error_message = "Allowed values for environment are 'dev', 'staging', or 'prod'." } } variable "vpc_cidr" { type = string description = "IPv4 CIDR block for the VPC network." default = "10.0.0.0/16" validation { condition = can(cidrnetmask(var.vpc_cidr)) error_message = "Must be a valid IPv4 CIDR notation (e.g., 10.0.0.0/16)." } } variable "subnet_configuration" { type = map(object({ cidr_block = string availability_zone = string public = bool tags = optional(map(string), {}) })) description = "Map of subnets to create within the network module." validation { condition = alltrue([ for sub in values(var.subnet_configuration) : can(cidrnetmask(sub.cidr_block)) ]) error_message = "All subnets must specify a valid IPv4 CIDR block." } } ``` ### B. Clean Resource Declarations & Local Conventions (`main.tf`) Use `locals` to compute tag sets, naming conventions, and conditional configurations centrally. ```hcl locals { name_prefix = "${var.project_name}-${var.environment}" default_tags = merge( var.tags, { Environment = var.environment ManagedBy = "Terraform/OpenTofu" Project = var.project_name } ) } resource "aws_s3_bucket" "this" { bucket = "${local.name_prefix}-data-store" force_destroy = var.environment == "dev" ? true : false tags = local.default_tags } resource "aws_s3_bucket_versioning" "this" { bucket = aws_s3_bucket.this.id versioning_configuration { status = var.enable_versioning ? "Enabled" : "Suspended" } } resource "aws_s3_bucket_server_side_encryption_configuration" "this" { bucket = aws_s3_bucket.this.id rule { apply_server_side_encryption_by_default { kms_master_key_id = var.kms_key_arn sse_algorithm = var.kms_key_arn != null ? "aws:kms" : "AES256" } } } ``` ### C. Explicit Outputs (`outputs.tf`) Always return full object references or specific attributes with explicit descriptions. Never leak unencrypted secrets unless explicitly intended (mark `sensitive = true`). ```hcl output "bucket_id" { value = aws_s3_bucket.this.id description = "The name/ID of the created S3 bucket." } output "bucket_arn" { value = aws_s3_bucket.this.arn description = "The Amazon Resource Name (ARN) of the S3 bucket." } output "database_connection_string" { value = "postgres://${aws_db_instance.this.username}:${aws_db_instance.this.password}@${aws_db_instance.this.endpoint}/${aws_db_instance.this.db_name}" description = "Full PostgreSQL connection string." sensitive = true } ``` --- ## 3. Native OpenTofu & Terraform Testing Framework (`tests/`) Use native `.tftest.hcl` test suites to validate logic without third-party dependencies. ```hcl # tests/unit_test.tftest.hcl run "verify_bucket_naming_and_tags" { command = plan variables { project_name = "myproject" environment = "dev" enable_versioning = true tags = { CostCenter = "12345" } } assert { condition = aws_s3_bucket.this.bucket == "myproject-dev-data-store" error_message = "S3 bucket name generated does not match expected convention." } assert { condition = aws_s3_bucket.this.tags["ManagedBy"] == "Terraform/OpenTofu" error_message = "ManagedBy tag was not injected correctly." } } run "verify_production_encryption" { command = plan variables { project_name = "myproject" environment = "prod" kms_key_arn = "arn:aws:kms:us-east-1:123456789012:key/abc-123" enable_versioning = true } assert { condition = aws_s3_bucket_server_side_encryption_configuration.this.rule[0].apply_server_side_encryption_by_default[0].sse_algorithm == "aws:kms" error_message = "KMS encryption must be applied when kms_key_arn is provided." } } ``` --- ## 4. Anti-Patterns & Pitfalls | Anti-Pattern | Why it Fails | Production Solution | | :--- | :--- | :--- | | **Hardcoding Provider Blocks in Child Modules** | Prevents module users from configuring custom regions, multi-region aliases, or authentication credentials. | Define `required_providers` in child modules; let root module pass providers via `providers = { aws = aws.eu_west_1 }`. | | **Monolithic State Files** | Increases blast radius of `terraform destroy` or state corruptions; slows `terraform plan` execution down. | Break infrastructure into isolated layers (e.g., `0-network/`, `1-database/`, `2-apps/`). | | **Overusing `count` for Complex Maps** | Modifying items in an array indexed by `count` causes full re-creation of subsequent resources. | Use `for_each` with maps or set expressions. | | **Unset or Weak Variable Constraints** | Fails late during `apply` phase rather than early during validation/plan. | Use custom `validation` blocks and explicit types (`object`, `map`, `list`). | | **Dynamic Provisioners (`local-exec` / `remote-exec`)** | Impairs drift detection, idempotency, and portability across OS execution hosts. | Use cloud-native user-data scripts, cloud-init, Ansible, or Kubernetes controllers instead. | --- ## 5. Automated CI/CD & Drift Detection Workflow ```mermaid graph TD A[Git Push / PR] --> B[terraform fmt -check] B --> C[tflint / opentofu fmt] C --> D[trivy / tfsec Security Scan] D --> E[tftest / Terratest Validation] E --> F[terraform plan / tofu plan] F --> G{PR Merged?} G -- Yes --> H[terraform apply / tofu apply] G -- No --> I[End PR Feedback Loop] ``` ### Essential CLI Operations Matrix - **Validate Code Formatting**: `tofu fmt -recursive -check` - **Lint Code**: `tflint --recursive` - **Run Native Tests**: `tofu test` - **Plan targeted changes**: `tofu plan -out=tfplan -target=module.vpc` - **State Operations**: `tofu state mv ` / `tofu state rm `