Terraform Professional (002): Turning Requirements into Predictable, Secure Configuration

Translating a business requirement into infrastructure code means choosing the Terraform construct whose behaviour matches the requirement exactly — what it accepts, when it is evaluated, and what happens when it fails. Most requirements arrive as plain sentences ("only these three environments", "never print the key", "the database must survive a bad commit"), and each one maps to a specific mechanism. Picking the wrong one usually still "works" in the happy path but misses the timing, the failure mode or the storage behaviour the requirement asked for.

The rest of this lesson takes each row in turn. A useful habit when reading a requirement: underline the words that state timing ("before a plan", "after apply", "between runs"), failure mode ("must stop", "must not block", "warn") and persistence ("never in state", "not in the console"). Those words decide between near-identical options.

A module's input variables are its contract, so requirements about what callers must and may provide belong in the variable's type, default and nullable settings. Get these three right and many bad inputs are rejected before any custom rule runs.

Required versus optional inputs

A variable is required exactly when it has no default. Any default — including "" and null — makes the input optional, so a module that must refuse to run without a region simply declares the variable with no default.

nullable

Variables are nullable by default (nullable = true): a caller can pass an explicit null, and the module then sees null — the default is not used. Setting nullable = false changes two things: null is never the value inside the module, and when a caller passes null for a variable that has a default, Terraform uses the default instead. This is how a child module falls back cleanly when a root passes through its own unset input.

A validation such as var.environment != "" does not catch null: null != "" is true. Close the null gap with nullable = false, not with string checks.

Object types and optional attributes

For structured inputs, declare an object({...}) type. Attributes listed plainly are required; the type conversion fails if a caller omits them. Mark an attribute optional(type) to let callers omit it — it then becomes a typed null — or optional(type, default) to have Terraform insert a default. The default is substituted both when the attribute is omitted and when it is set to null, so an attribute with a non-null default is never null inside the module. Terraform has no "zero value" fallback: an optional number with no default is null, not 0.

variable "services" {
  type = map(object({
    port     = number                  # required
    public   = optional(bool, false)   # omitted or null -> false
    replicas = optional(number)        # omitted -> null
  }))
}

optional() is valid only on attributes inside an object type — never as a variable's top-level type. A map of strings (map(map(string))) cannot require a key, so it cannot enforce a mandatory field.

Variable defaults never merge

A variable's default is used only when the caller provides no value for the whole variable. If a caller passes a partial object, that value replaces the default entirely and is checked against the type; a missing required attribute is an error, not a gap filled from the default. Per-attribute defaults belong in optional(type, default) inside the type.

Conventions computed from inputs — a <org>-<env> name prefix, a standard tag map — belong in a locals block, because local values can be any expression over variables, other locals and resource attributes, and every resource in the module can reference them. That gives one place to change a convention.

Two alternatives look plausible and fail:

• Variable defaults must be literal values. A default cannot reference other variables, locals or resources, so default = "${var.org}-${var.env}" or default = local.prefix is rejected by terraform validate.
• Outputs pass values to the caller. Resources cannot reference their own module's outputs.

When callers may override a derived value, combine a null default with a local:

variable "name_prefix" {
  type    = string
  default = null   # optional override
}

locals {
  name_prefix = coalesce(var.name_prefix, "${var.org}-${var.env}")
  common_tags = {
    cost-center = var.cost_center
    environment = var.env
    owner       = var.owner
  }
}

A provider's default_tags block (for example in the AWS provider) can apply common tags to every resource it manages, but it cannot set names — the naming rule would still need a local.

A reusable module should not know which environment it runs in: each difference between environments should be an explicit input that the calling root module sets, such as single_nat_gateway, nat_gateway_per_az, instance_class or create_standby. HashiCorp's module guidance favours this because callers state what they need and the module stays independent of naming.

The common anti-patterns all embed the list of environments inside the module:

• Branching on terraform.workspace or on var.environment == "prod" couples the module to naming conventions that differ between teams.
• A lookup map keyed by environment name works today but needs a module edit for every new environment.
• A single "is_prod" switch bundles unrelated behaviours. When a new environment needs prod's availability but dev's sizing, the switch cannot express it; separate inputs per behaviour can.
• Copies of the module per environment drift apart and double maintenance.

When modelling, isolate exactly which dimension differs. If dev and prod span the same zones but differ in NAT redundancy, deriving NAT count from the zone list misses the requirement; a dedicated input does not.

Predictable configuration means a change to one item touches only that item. With count, instances are addressed by position ([0], [1]…), so removing an element from the middle of a list shifts every later index and Terraform plans changes or replacements for unrelated objects. With for_each, instances are addressed by key, so choose keys that are unique, stable business identifiers — a project code, a service name, a repository name.

• for_each accepts a map or a set of strings. A list of names becomes toset(var.names); a list of objects becomes a map with a for expression keyed by a unique attribute: { for b in var.buckets : b.name => b }.
• A map keyed by index ({ for i, b in list : i => b }) uses for_each but keeps positional identity — the same ripple problem as count. Sorting a list does not help either.
• Keys that change (list position, editable descriptions, generated values) make Terraform destroy and recreate the object under its new key. Non-unique keys fail with a duplicate-key error.

Keys must be known at plan time

Terraform must know how many instances exist and what they are called while planning. Attributes that only exist after apply — such as IDs of resources created in the same run — can be argument values but never keys; using them as keys fails with "Invalid for_each argument". Iterate over something whose keys come from configuration instead — for example, when security groups are created with for_each = var.tiers, their rules can use for_each = aws_security_group.tier with security_group_id = each.value.id: the keys are the tier names, the IDs are values. The rule is about where the unknown sits: any expression that puts an apply-time attribute into the keys fails the same way, and ordering hints such as depends_on never make a value known earlier. Tracing how such expressions resolve is covered in the lesson on variables, locals, outputs and for_each.

Per-run functions cause perpetual diffs

timestamp() and plantimestamp() return a new value on every run, so using them in tags or keys produces a change on every plan — and moving the call into a local changes nothing. A value that must be fixed at creation belongs in state: a time_static resource (hashicorp/time provider) records the time once and returns the same rfc3339 value on later plans. ignore_changes on the tag would also quiet the plan but hides real drift on that attribute.

Terraform has four custom-condition mechanisms, and the difference that matters most is the failure mode: validation, preconditions and postconditions raise errors that stop the operation, while check blocks only warn.

Validation rules

A validation block has a condition that must be true and an error_message. Allowed-value lists use contains(["dev", "staging", "prod"], var.environment); a string type cannot express an allowed list. Since Terraform 1.9, conditions may reference other variables and objects in the module, so cross-input rules such as var.max_size >= var.min_size are valid. To validate every element of a list, wrap a function that errors on bad input in can() and require every result to pass. Here every notification address must belong to the company domain:

validation {
  condition = alltrue([
    for e in var.alert_emails :
    can(regex("^[^@]+@example\\.com$", e))
  ])
  error_message = "Every address must be an @example.com address."
}

The general pattern is "per-element test, then all must hold" — alltrue over the results, or an empty list of failures. anytrue expresses "at least one", which is a different requirement. Where Terraform has a function that actually parses the value (for example cidrhost for network prefixes), testing it with can() is stronger than a loose textual check, which can pass values that are still invalid.

Postconditions never roll back

When a postcondition depends on values known only after apply (for example self.public_ip of a new instance), Terraform evaluates it after creating the object. A failure stops dependent resources, but the created object stays in place and is recorded in state — Terraform has no rollback. Fix the cause (here, the subnet's public-IP setting) and apply again.

Check blocks and scoped data sources

Check blocks are for verifying behaviour without blocking work — for example probing a load balancer's health endpoint. Put the probe inside the check as a scoped data source: errors from a data source nested in a check block are reported as warnings, while a top-level data source that fails (an unreachable URL) errors the whole plan, even though the assert itself would only have warned.

check "web_health" {
  data "http" "health" {
    url = "https://${aws_lb.web.dns_name}/health"
  }
  assert {
    condition     = data.http.health.status_code == 200
    error_message = "Health endpoint is not returning 200."
  }
}

Health assessments in HCP Terraform extend this between runs: enabled on a workspace, they run drift detection and continuous validation, re-evaluating check blocks and pre/postconditions on a schedule and notifying the team when one starts failing. They never stop a plan, and they are not on everywhere by default: they are a per-workspace (or organization-wide) setting, and which HCP Terraform plans include them is set by HashiCorp's current pricing. terraform validate, by contrast, checks syntax and internal consistency only — it reads no data sources and contacts no infrastructure — and terraform test runs separate test runs that do not guard a real plan or apply.

Put a condition where its meaning lives: a precondition states an assumption one consumer makes; a postcondition (or an output precondition) states a guarantee an object or module makes to everyone who uses it. The error message then names the right object and the rule fires only where it should.

• If only one instance type in the configuration requires an x86_64 image, put a precondition in that instance's lifecycle block. A postcondition on the shared image data source would claim the architecture for every consumer and break the resources that legitimately use ARM images.
• If a module promises callers that the subnet it returns is in the expected VPC, put a precondition inside the output block. It is evaluated before the value is exported, so the module enforces its own guarantee once instead of every downstream resource repeating it.
• If the rule is about an input alone, a validation block is the natural home; a validation that tests a data source attribute describes the input, not the resource that needs the setting.

resource "aws_instance" "legacy_app" {
  ami           = data.aws_ami.app.id
  instance_type = "m5.large"

  lifecycle {
    precondition {
      condition     = data.aws_ami.app.architecture == "x86_64"
      error_message = "The legacy app build needs an x86_64 AMI."
    }
  }
}

sensitive = true controls display: Terraform redacts the value in plan and apply output and carries the mark through every expression derived from it — string templates, locals, function results. It does not change storage: a sensitive value used in a resource argument is written to state in plain text, and saved plan files (terraform plan -out) contain it too. Terraform does not encrypt individual values; protecting state and plan artefacts at rest is the job of the backend (encryption, access control) and the pipeline.

Outputs must declare sensitivity

If an output's value derives from a sensitive value, the output must set sensitive = true; otherwise planning fails with an error that the output refers to sensitive values. Terraform does not quietly mark the output for you, and it never partially redacts a string. A sensitive root output is still stored in state and can be read on purpose with terraform output or terraform output -raw — which is exactly right when a later pipeline step needs the value but the apply summary must not print it.

Sensitive values and for_each

for_each keys become visible instance addresses, so Terraform rejects sensitive values as for_each arguments. Sensitivity propagates, so toset(keys(var.users)) on a sensitive map is still sensitive and fails the same way, and wrapping the whole map in nonsensitive() strips redaction from the secrets as well. The clean design separates identifiers from secrets: iterate over a non-sensitive map (names and roles) and read each password from a separate sensitive map with each.key. Reserve nonsensitive() for values you have confirmed are not secret.

When the requirement is that a secret must never be stored — not just hidden — use ephemeral values (Terraform 1.10+) and write-only arguments (Terraform 1.11+). Both exist during the run and are never written to state or plan files.

Ephemeral inputs, resources and outputs

• Ephemeral variables (ephemeral = true) are omitted from plan and state files, so a value used with a saved plan must be supplied again at apply. How a value is delivered (-var, TF_VAR_) does not change storage — only ephemeral does.
• Ephemeral resources (an ephemeral block, for example ephemeral "aws_secretsmanager_secret_version" or ephemeral "random_password") fetch or generate a value for the current run only. A data source reading the same secret stores the result in state, even when wrapped in sensitive(), and terraform_remote_state just copies a secret from one state file into another.
• Ephemeral outputs are allowed only in child modules, to pass ephemeral values up to the caller. Root module outputs are persisted in state for terraform output and remote-state readers, so ephemeral = true on a root output is an error.
• Ephemeral values may flow only into ephemeral contexts: provider configuration blocks, provisioner and connection blocks, locals, ephemeral variables and child outputs, other ephemeral resources, and write-only arguments. Ordinary resource arguments reject them, and so does a managed resource's for_each.

Write-only arguments and their version argument

A write-only argument, offered by providers that support it and conventionally suffixed _wo, accepts a value (ephemeral or not), passes it to the provider, then discards it. Because Terraform keeps no copy — not even a hash — it cannot show a diff when the value changes and cannot detect drift in it. Providers pair each one with a version argument (for example password_wo_version) that is stored; incrementing it is the signal to send the new value in place. Changing only the value produces "No changes", so the version bump is the rotation step; lifecycle settings that hide or force changes do not substitute for it.

ephemeral "random_password" "db" {
  length = 24
}

resource "aws_db_instance" "main" {
  # ...
  password_wo         = ephemeral.random_password.db.result
  password_wo_version = 1   # bump to rotate
}

Both halves matter: a managed random_password resource writes its result to state even if the database uses a write-only argument, and an ephemeral generator cannot feed an ordinary password argument. Secret rotation and secrets-manager integration are developed further in the security and governance domain.

Predictable configuration also means every engineer and pipeline installs the same dependencies and that dangerous plans fail loudly.

The dependency lock file

Version constraints in required_providers describe acceptable ranges; .terraform.lock.hcl records the exact provider versions and package checksums selected within them. Commit it, and terraform init on every machine reuses those selections until someone deliberately runs terraform init -upgrade. Do not commit the .terraform directory — it is a local, platform-specific cache.

Checksums are per platform. Installing from a network or filesystem mirror records checksums only for the platform that ran init, so a lock file created on darwin_arm64 may lack linux_amd64 entries, and a CI run with terraform init -lockfile=readonly (which forbids changes to the file) then fails verification. Pre-populate every platform the team uses and commit the result:

terraform providers lock \
  -platform=darwin_arm64 \
  -platform=linux_amd64

Exact = version constraints do not replace checksums; Terraform still verifies packages against the lock file.

required_version in shared modules

required_version constrains the Terraform CLI, and Terraform checks it in the root module and every child module. A shared module that uses a feature introduced in a given release should declare a lower bound such as required_version = ">= 1.9.0": older CLIs get a clear version error, newer ones keep working. The pessimistic form ~> 1.9.0 adds an upper bound (1.9.x only), and a floor set at the latest release excludes capable versions. The lock file records providers only — never the CLI version.

prevent_destroy versus provider deletion protection

lifecycle { prevent_destroy = true } makes Terraform reject any plan that would destroy the resource, including a replacement, so a reviewer must remove the guard deliberately. It lives in the resource block, though: if someone deletes the block, the guard goes with it and Terraform plans a normal destroy. A provider-side setting such as deletion_protection = true on aws_db_instance protects the real object — the API refuses the delete during apply — but does not fail the plan. Requirements that cover both failure modes need both.

A removed block with lifecycle { destroy = false } (Terraform 1.7+) is the deliberate way to stop managing a resource without destroying it — useful when someone chooses to remove it, but it does nothing when a block is simply deleted.