Andrew Mercer
on this page

What's new, by version

A quick map of recent language features, so you know what your required_version allows:

Version Feature
1.5 import blocks, -generate-config-out, check blocks, plantimestamp()
1.6 terraform test
1.7 removed blocks, import with for_each, mock providers in tests
1.8 Provider-defined functions, issensitive()
1.9 Cross-object variable validation, templatestring()
1.10 Ephemeral resources, ephemeral variables/outputs, S3-native locking (GA in 1.11)
1.11 Write-only arguments, terraform test -junit-xml GA
1.12 &&/\|\| short-circuit, import by identity, parallel test runs, OCI backend
1.13 terraform stacks CLI for HCP Stacks
1.14 Actions, list resources + terraform query
1.15 Variables in module source/version, deprecated on variables/outputs, convert(), typed outputs, validate checks backend blocks
1.16 import in child modules, destroy-time actions + on_failure, lifecycle { destroy = false }, terraform_data store, graph -format=mermaid, state show -json, console -scope

OpenTofu's equivalents and divergences are on the OpenTofu page.

Multiple provider configurations

Aliases

provider "azurerm" {
  features {}
  subscription_id = var.subscription_id               # default configuration
}

provider "azurerm" {
  alias           = "dr"
  features {}
  subscription_id = var.subscription_id
}

provider "azurerm" {
  alias           = "connectivity"
  features {}
  subscription_id = var.connectivity_subscription_id   # hub/shared services
}

resource "azurerm_private_dns_zone_virtual_network_link" "spoke" {
  provider              = azurerm.connectivity          # zone lives in the hub subscription
  name                  = "link-${var.workload}-${var.env}"
  resource_group_name   = "rg-dns-private"
  private_dns_zone_name = "privatelink.vaultcore.azure.net"
  virtual_network_id    = azurerm_virtual_network.spoke.id
}

AWS multi-region is the same idea with region:

provider "aws" { region = "ca-central-1" }
provider "aws" {
  alias  = "use1"
  region = "us-east-1"          # e.g. ACM certificates for CloudFront
}

Passing aliases into modules

The child declares the names it expects with configuration_aliases, and the caller maps its configurations to them (meta-arguments):

module "replicated_storage" {
  source = "../modules/geo-storage"
  providers = {
    azurerm.primary   = azurerm
    azurerm.secondary = azurerm.dr
  }
}

Dynamic provider configurations

Terraform requires one provider block per configuration, written out. You can't for_each over providers, which makes "one provider per region in a list" impossible without code generation.

OpenTofu 1.9+ allows for_each on provider blocks and dynamic provider references:

# OpenTofu only
provider "aws" {
  alias    = "by_region"
  for_each = toset(var.regions)
  region   = each.key
}

module "regional" {
  source   = "./regional"
  for_each = toset(var.regions)
  providers = {
    aws = aws.by_region[each.key]
  }
}

In Terraform, the options are: generate the provider blocks (Terragrunt generate, templating), one root module per region, or HCP Terraform Stacks, whose deployments handle per-region provider configuration natively.

Providers configured from resources

A provider configured from attributes of a resource in the same configuration (a Kubernetes provider pointed at an AKS cluster being created) works on the first apply only when those values are known at plan time. In practice:

provider "kubernetes" {
  host                   = azurerm_kubernetes_cluster.this.kube_config[0].host
  cluster_ca_certificate = base64decode(azurerm_kubernetes_cluster.this.kube_config[0].cluster_ca_certificate)
  # ...
}

…breaks when the cluster is being replaced, and plans become unreliable. Put cluster creation and in-cluster resources in separate states: one stack builds the cluster, another (or GitOps with Argo CD/Flux) configures what runs in it.

Ephemeral values and write-only arguments

Covered from the security angle in security. The language rules in full:

Ephemeral resources (ephemeral blocks, Terraform 1.10+, OpenTofu 1.11+) are opened during plan and apply and closed at the end, and are never persisted. Typical: secrets from Key Vault/Vault/Secrets Manager, short-lived tokens, generated passwords.

ephemeral "azurerm_key_vault_secret" "api_key" {
  name         = "partner-api-key"
  key_vault_id = data.azurerm_key_vault.platform.id
}

Ephemeral variables and outputs:

variable "bootstrap_token" {
  type      = string
  sensitive = true
  ephemeral = true        # can be set per run, never stored in plan or state
}

# In a child module, pass an ephemeral value up to the caller
output "token" {
  value     = ephemeral.vault_kv_secret.token.data["value"]
  ephemeral = true
}

Where ephemeral values may go: write-only arguments, provider configuration blocks, other ephemeral resources, locals (which become ephemeral), ephemeral outputs (child modules), provisioner and connection blocks. Anywhere else is an error: Terraform won't let an ephemeral value reach a normal resource argument, which is the guarantee you want.

Write-only arguments (Terraform 1.11+): resource arguments ending in _wo, accepted by the provider and never stored. They come with a _wo_version companion because Terraform can't detect changes to a value it never kept: bump the version to push a new value.

Helpers:

  • terraform.applying is true during apply, false during plan. Useful for an ephemeral resource that should only fetch a long-lived token at apply time.
  • ephemeralasnull(value) strips ephemeral parts of a complex value so the rest can go to a normal argument.

terraform_data

The built-in terraform_data resource (1.4+) replaces null_resource with no provider needed:

resource "terraform_data" "schema_version" {
  input            = var.schema_version          # stored; exposed as .output
  triggers_replace = [var.schema_version]        # replace when this changes

  provisioner "local-exec" {
    command = "./scripts/migrate.sh ${self.output}"
  }
}

Uses:

  • Replacement triggers for other resources via replace_triggered_by, which needs a resource to reference.
  • Glue with local-exec when there's no provider for something (prefer actions where available).
  • A precondition anchor for guards that aren't about any one resource (see the environment guard).

Terraform 1.16 adds a store block to terraform_data for carrying values, including ephemeral and sensitive ones, from plan to apply. Check the 1.16 docs for its syntax and exactly what's persisted, and treat anything it holds as you would state.

Actions

Terraform 1.14 added actions: provider-defined operations that don't fit create/read/update/delete. Invoking a function, running an automation job, invalidating a CDN cache, sending a notification. Before actions, these were local-exec provisioners calling a CLI.

action "aws_lambda_invoke" "warm_cache" {
  config {
    function_name = aws_lambda_function.api.function_name
    payload       = jsonencode({ action = "warm" })
  }
}

resource "aws_lambda_function" "api" {
  # ...
  lifecycle {
    action_trigger {
      events  = [after_create, after_update]
      actions = [action.aws_lambda_invoke.warm_cache]
    }
  }
}
# Run an action on demand, outside a resource lifecycle
terraform apply -invoke=action.aws_lambda_invoke.warm_cache
  • Events: before_create, after_create, before_update, after_update; Terraform 1.16 adds before_destroy and after_destroy (CMDB clean-up, IP release, final backups).
  • on_failure (1.16): halt (default; stop dependent processing), taint (mark the triggering resource for replacement), continue (warn and carry on).
  • Which actions exist is up to providers. Check the registry page of each provider for an "Actions" section. Coverage is growing; it isn't universal yet.
  • Actions show in the plan, which is the big improvement over provisioners: reviewers see that an apply will also invoke something.

List resources and terraform query

Terraform 1.14 also added list resources for discovering existing infrastructure, and terraform query to run them. Covered in state refactoring, because its main use is generating import blocks for unmanaged resources.

Unknown values and deferred changes

The rule that count/for_each keys must be known at plan time (expressions) bites hardest in "create a cluster, then create things in it" configurations.

Patterns that avoid it:

  • Key collections by configuration values, not computed IDs (loops).
  • Split into layers so the second stack plans against values that already exist.
  • -target once to bootstrap the first layer, then plan normally (emergency use only).

Terraform has an experimental deferred changes mode (terraform plan -allow-deferral, alpha builds only) where unresolvable parts are deferred to a follow-up plan instead of failing. HCP Terraform Stacks use deferral natively. Don't design around it in plain Terraform until it's stable.

Override files

Files named override.tf or *_override.tf are loaded last, and their blocks are merged into existing blocks with the same address instead of being added:

# main.tf
resource "azurerm_storage_account" "this" {
  name                     = "stapp001"
  account_replication_type = "ZRS"
  # ...
}

# local_override.tf (git-ignored)
resource "azurerm_storage_account" "this" {
  account_replication_type = "LRS"     # cheaper for my sandbox
}

Legitimate uses: Terragrunt's generated versions_override.tf to patch a third-party module's terraform {} block; a git-ignored local override for personal sandboxes. Avoid them in committed code: readers of main.tf can't see the real configuration.

Generating configuration

When a program needs to produce Terraform:

  • Emit .tf.json rather than templating HCL text. JSON is trivially generated from any language (serde in Rust), and Terraform reads it natively (HCL: JSON syntax).
  • provider::terraform::encode_tfvars / encode_expr go the other way, from Terraform values to HCL text (functions).
  • -generate-config-out and terraform query -generate-config-out draft resource blocks from real infrastructure.
  • Terragrunt generate blocks and Terramate code generation produce HCL from templates per stack.

Targeting and replacing

terraform plan -target='module.app'                         # partial plan
terraform apply -replace='azurerm_linux_virtual_machine.web'  # force replacement
terraform plan -refresh-only                                 # detect drift only
terraform plan -refresh=false                                # skip refresh (fast, blind)

-target is for recovery and bootstrapping. Routine use means your state boundaries are wrong. See state: how big should a state be.

Sensitive value propagation

  • Anything derived from a sensitive value is sensitive ("${var.password}-x", length(var.password) until wrapped in nonsensitive()).
  • A resource attribute the provider marks sensitive makes the whole expression that reads it sensitive.
  • for_each can't use sensitive values as keys (the keys would be shown in addresses). Use nonsensitive() on the keys only when you're sure the keys themselves aren't secret.
  • Root outputs that contain sensitive values must be marked sensitive = true.

HCP Terraform Stacks

Stacks are HCP Terraform's answer to multi-component, multi-environment orchestration (the problem Terragrunt solves in open source):

  • *.tfcomponent.hcl declares components (module instances) and how outputs wire into inputs.
  • *.tfdeploy.hcl declares deployments: the environments/regions/accounts, each with its own inputs and identity.
  • One plan covers all components of a deployment, in dependency order, with deferral for unknown values.
  • terraform stacks (1.13+) is the CLI.

Stacks run only on HCP Terraform / Terraform Enterprise. Open-source alternatives: Terragrunt explicit stacks, Terramate, Atmos.