Terraform & OpenTofu Skill

When using this skill, every response generated for Terraform or OpenTofu tasks is guaranteed to follow a specific structure to ensure safety and clarity. You should expect the following components in every response:

1. Assumptions & version floor: Explicit declaration of the runtime (terraform or tofu), exact version, providers, state backend, execution path (local/CI/Cloud/Atlantis), and environment criticality.
2. Risk category addressed: Identification of risks such as identity churn, secret exposure, blast radius, CI drift, compliance gaps, state corruption, provider upgrade risk, or testing blind spots.
3. Chosen remediation & tradeoffs: An explanation of the chosen solution and what was traded off.
4. Validation plan: A set of exact commands (e.g., fmt -check, validate, plan -out, policy check) tailored to the specific runtime and risk level.
5. Rollback notes: Instructions on how to undo destructive or state-mutating changes and what evidence to retain.

Safety Warning: Never run a direct production apply without a reviewed plan artifact and approval. Never run terraform destroy without first running terraform plan -destroy and reviewing all resources (including implicit dependents) that will be deleted. Never use -auto-approve on a destroy command.

When a child module requires multiple provider configurations (e.g., for multi-region deployments), you must use configuration_aliases in the child module and explicitly map them in the caller's module block.

1. In the Child Module: Declare the aliases in versions.tf and bind them to resources using the provider argument.

2. In the Caller: Pass the specific provider instances into the module using the providers map.

Warning: If you omit the providers map in the module call, the plan will fail with: No configuration for provider <alias_name>.

Implementation Example

Child Module (versions.tf):

terraform {
  required_providers {
    aws = {
      source                = "hashicorp/aws"
      version               = "~> 5.0"
      configuration_aliases = [aws.primary, aws.replica]
    }
  }
}

Caller (main.tf):

module "bucket" {
  source      = "./modules/replicated-s3"
  bucket_name = "app-data"

  providers = {
    aws.primary = aws.us_east_1
    aws.replica = aws.eu_west_1
  }
}

terraform {
  required_providers {
    aws = {
      source                = "hashicorp/aws"
      version               = "~> 5.0"
      configuration_aliases = [aws.primary, aws.replica]
    }
  }
}

# in any resource:
provider = aws.primary

module "bucket" {
  source      = "./modules/replicated-s3"
  bucket_name = "app-data"

  providers = {
    aws.primary = aws.us_east_1
    aws.replica = aws.eu_west_1
  }
}

When removing a provider, you have three primary strategies depending on whether you want to destroy the actual cloud resources:

1. Two-phase removal (Safe/Default):
   • Phase 1: Delete the resource blocks from your code. Run terraform apply to destroy the real resources. Verify via terraform state list that no resources for that provider remain.
   • Phase 2: Remove the provider and required_providers blocks. Run terraform init to clean up.
2. removed block (Declarative/Unmanaged): Use the removed block (Terraform 1.7+, OpenTofu 1.7+) to remove a resource from state without destroying the real resource. The resource becomes unmanaged.
3. Manual state removal (Orphaned): Use terraform state rm <address>. This removes the resource from state but leaves the real resource running (orphaned). Use this only when intentionally abandoning a resource.

# Use the removed block to keep the real resource but stop managing it in Terraform
removed {
  from = vault_policy.ops

  lifecycle {
    destroy = false
  }
}

Provisioners (local-exec, remote-exec) should be avoided because they are non-idempotent, create-only (updates don't re-run), lack drift detection, and can leak sensitive data to CI logs.

Use these alternatives instead:

• Instance bootstrap: Use user_data + cloud-init via templatefile().
• Orchestration with explicit re-run (Terraform 1.4+): Use terraform_data with triggers_replace.
• Ongoing OS configuration: Use external tools like Ansible, SSM Run Command, or SSM State Manager.
• Last-resort one-shot: Use terraform_data + provisioner (1.4+) or null_resource (pre-1.4).

# ✅ DO — bootstrap via user_data + cloud-init
resource "aws_instance" "web" {
  ami           = data.aws_ami.al2023.id
  instance_type = "t3.small"
  user_data = templatefile("${path.module}/cloud-init.yaml", {
    app_version = var.app_version
  })
  user_data_replace_on_change = true
}

# ✅ DO — declarative orchestration on 1.4+
resource "terraform_data" "migration" {
  triggers_replace = [aws_rds_cluster.this.id, var.schema_version]

  provisioner "local-exec" {
    command = "./run-migration.sh"
  }
}

Terraform and OpenTofu are both used for infrastructure management, but they have diverged significantly since version 1.6.

Comparison Summary

When to choose which

• Choose Terraform if you require HCP Terraform / Terraform Cloud, HashiCorp enterprise support, or want first access to the latest HashiCorp features.
• Choose OpenTofu if you prioritize open-source governance, want to avoid BUSL-1.1 licensing, or want to avoid vendor lock-in.

The terraform_remote_state data source should be used sparingly, only when connecting separately-owned compositions that have different lifecycles or ownership (e.g., different teams).

When to use it:

• Consumer and producer are owned by different teams.
• The producer's state is already split for lifecycle reasons.
• You cannot pass values via module inputs.

When NOT to use it:

• You control both stacks (use module outputs instead).
• You can use a cloud data source (e.g., aws_vpc by tag).
• You are chaining many remote state reads (this indicates a need to reshape boundaries).

Best Practices:

• Document which outputs are consumed externally.
• Version your outputs to avoid breaking downstream consumers.
• Prefer cloud data sources over terraform_remote_state for provider-managed resources.

# environments/prod/compute/main.tf
data "terraform_remote_state" "networking" {
  backend = "s3"
  config = {
    bucket = "my-terraform-state"
    key    = "prod/networking/terraform.tfstate"
    region = "us-east-1"
  }
}

module "ec2" {
  source = "../../modules/ec2"

  vpc_id     = data.terraform_remote_state.networking.outputs.vpc_id
  subnet_ids = data.terraform_remote_state.networking.outputs.private_subnet_ids
}

For Terraform 1.3+, use the optional() function within object types to define attributes that have default values. This allows users to provide only the required fields while the rest fall back to predefined defaults.

Best Practices:

• Prefer simple types (string, number, list(), map()) over object() unless strict validation is required.
• Use any to disable validation at specific depths or to support multiple types.

# ✅ GOOD - Using optional() for object attributes
variable "database_config" {
  description = "Database configuration with optional parameters"
  type = object({
    name               = string
    engine             = string
    instance_class     = string
    backup_retention   = optional(number, 7)      # Default: 7
    monitoring_enabled = optional(bool, true)     # Default: true
    tags               = optional(map(string), {}) # Default: {}
  })
}

# Usage - only required fields needed
database_config = {
  name           = "mydb"
  engine         = "mysql"
  instance_class = "db.t3.micro"
  # Optional fields use defaults
}

When managing infrastructure for multiple teams or environments, use one of these three organizational patterns to manage the blast radius and ownership of your state files:

1. State Per Environment: Separate state files by environment (e.g., dev/, staging/, prod/). This provides clear separation and different IAM roles per environment but can lead to code duplication.
2. State Per Team/Component: Separate state files by team or functional component (e.g., networking-team/, platform-team/). This clarifies ownership and allows independent release cycles but makes cross-team dependencies more complex.
3. Hybrid (Environment + Component): The recommended pattern for most teams. It combines environment boundaries with component isolation within each environment (e.g., prod/01-networking/, prod/02-platform/). Using numbered prefixes helps visualize dependencies.

Decision Matrix for Splitting State: