Terraform Professional: Tracing Variables, Locals, Outputs and for_each

A root module variable takes the value from the last source Terraform loads; the default is used only when no source assigns one. Terraform loads, in order: TF_VAR_ environment variables, terraform.tfvars, terraform.tfvars.json, every *.auto.tfvars / *.auto.tfvars.json file in lexical order of filename, and finally -var and -var-file options in the order they appear on the command line. Several sources assigning one variable is normal, not an error — the later one simply wins.

The right-hand column is a tracing tool. A misspelt name in a .tfvars file produces a warning and the real variable quietly keeps its default — so a production run that "ignored" a value usually has that warning in its log. A misspelt TF_VAR_ name leaves no trace at all, which makes it the hardest loss to spot. Files warn rather than fail because one shared .tfvars file often feeds several configurations.

All of these sources set root module variables only. A child module's variable can never be set from a .tfvars file, TF_VAR_ or -var (there is no module.x.name=... syntax): the root must declare its own variable and pass it down in the module block. Precedence across environments and .tfvars overrides as a release practice are covered with workspace and pipeline operations; here the skill is reading the result.

Before a module sees a value, Terraform converts it to the declared type, and that conversion can change it without any error. For an object(...) type, attributes the type does not declare are discarded, and attributes marked optional(type, default) receive their default when the caller omits them or sets them to null. optional(type) with no default yields null when omitted.

variable "settings" {
  type = object({
    name     = string
    replicas = optional(number, 2)
  })
}

# Caller passes: settings = { name = "api", replica = 5 }
# Module sees:   { name = "api", replicas = 2 }

The misspelt replica vanishes during conversion, so replicas counts as omitted and falls back to 2 — a typo in a module argument silently becomes a default. Primitive conversions also apply: the string "false" converts to the bool false and "5" to the number 5. When a value is "wrong but no error", compare the caller's attribute names with the type declaration before anything else. Note that optional() is an attribute modifier inside an object type; it is not a type you can give a whole variable.

An input variable is nullable by default, so a caller that explicitly passes null overrides the variable's default with null. Setting nullable = false forbids null inside the module: a null argument then takes the default, or fails the plan if the variable has no default.

This matters whenever a root passes one of its own variables straight through (instance_type = var.override_type) and that root variable defaults to null: with a nullable module variable, the null wins and the resource receives no value. The fix that protects every caller is nullable = false on the module's variable, not a default in one caller. A validation block that rejects null turns the case into an error instead of defaulting it. Keep the two levels apart: a null attribute inside an object takes the optional() default, while a null for the whole variable replaces the variable's default (for example {}) and then any attribute access on it fails.

A validation block checks a variable's final value during plan; a false condition is an error that stops the plan and prints the block's error_message, which points straight at the variable that carries the bad value. Since Terraform 1.9 the condition may refer to other input variables (and other objects in the module), so rules such as "prod needs at least three instances" can live on the variable instead of in a resource precondition.

variable "instance_count" {
  type = number
  validation {
    condition     = var.environment != "prod" || var.instance_count >= 3
    error_message = "prod needs at least 3 instances."
  }
}

When a rule fails to catch something, evaluate the condition by hand with the caller's exact values. Terraform string comparison is case-sensitive: if a caller passes "Prod", then var.environment != "prod" is true, the whole || is true and the rule passes. Normalising with lower() in the condition, or validating the allowed values of environment itself, closes that gap. Validation never downgrades to a warning and does not wait for apply when the values are known at plan.

Local values are declared in locals { } blocks and referenced with the singular prefix local.<name>. They are scoped to the module: every .tf file in the directory shares one namespace, so a local defined in locals.tf is usable in main.tf with no import, and the same name defined in two blocks — even in different files — is a duplicate-definition error. File order never makes one definition win and Terraform never merges them; combine maps under different names with merge() in one place.

Locals do not cross module boundaries in either direction. A child module that writes local.name_prefix refers to its own local; if the prefix lives in the root, the child must declare an input variable and the root must pass name_prefix = local.name_prefix. Copying the locals block into the child works but leaves two definitions to drift. Names in different namespaces are different objects: var.env and local.env can hold different values in the same module, which is a classic tracing trap.

Values travel down through module block arguments into the child's declared variables, and up through the child's outputs as module.<name>.<output>. Nothing is inherited: a child never sees the root's variables or locals, and an output cannot send a value into a child. To find the source of a wrong value, follow the references hop by hop rather than matching names:

1. The resource argument in the child (for example bucket = "billing-${var.env}").
2. The child's variable or local it reads.
3. The argument the caller sets in its module block — arguments are matched by name, so their order is irrelevant, but swapped right-hand sides (project = var.environment) are a common bug.
4. The root variable, local or resource that feeds that argument, and finally where that root value comes from (see the precedence table).

If one caller of a shared module is wrong while others are right, the module is fine and the call site is the suspect. Check outputs too: an output that echoes its input (value = var.name) reports what was requested, not what was created — when the resource appends a random suffix, consumers get a name that does not exist. Outputs should expose resource attributes (aws_s3_bucket.this.bucket), which also gives consumers an implicit dependency; depends_on changes ordering, never a value.

terraform output (with or without -json) shows root module outputs only. A child's output reaches the CLI, or a terraform_remote_state consumer, only when the root re-exports it with its own output block; terraform refresh does not change that.

Inspecting values with terraform console

terraform console loads the configuration and current state and evaluates any expression — var.x, local.x, functions, resource attributes — without planning or applying. Values that depend on resources not yet created show as known after apply; -plan builds a plan first so results reflect it. By default it evaluates in the root module, where a child's locals are invisible (a parent can read only module.app["stage"].<output>). The -scope option moves evaluation into a module instance with its real arguments, e.g. terraform console -scope='module.app["stage"]' (an index for count, a key for for_each). Running the console inside the module's own directory instead treats it as a root and loses the caller's inputs. terraform show displays state or a saved plan, which do not store locals, and terraform validate prints no values.

A sensitive mark belongs to the value, and every value derived from it stays sensitive: interpolating it into a local, or passing it through sha256(), length(), substr(), tostring() or keys(), keeps the mark. Any output, in the root module or a child module, that carries a sensitive value fails the plan unless the output declares sensitive = true; writing sensitive = false does not unmark anything.

Marks also cross module boundaries. When a child output declared sensitive = true is passed into another module, the receiving variable carries the mark even if it does not declare sensitive itself. So a "sensitive value" error deep in one module can originate in a different module's output — trace the value back to where it was first marked.

for_each accepts exactly two kinds of value: a map (of any element type) or a set of strings. Lists, tuples, and sets of objects are rejected with an Invalid for_each argument error; Terraform never converts them implicitly, because position and duplicates mean nothing as instance keys.

Instances are addressed by key, never by number (numeric indexes belong to count), and never by value. On a module block, for_each indexes the module instance: a resource inside without its own for_each is module.network["prod"].aws_vpc.main, not module.network.aws_vpc.main["prod"]. These are the addresses that terraform state show and plan output use.

Keys must be known, and must not be sensitive

Terraform must know every instance address while planning, so map keys and set members must be known at plan time; map values may be unknown. Keying a map by a provider-computed attribute (an ARN, an ID, random_id.x.hex) or by an impure function like uuid() fails in a new workspace with an error that keys cannot be determined until apply. Key by values you wrote — usually the upstream map key: { for k, f in aws_lambda_function.fn : k => f.role }. depends_on cannot make an unknown key known.

Sensitive values are also rejected as for_each arguments, because keys appear in plan output and state addresses. Unmark only the keys: toset(nonsensitive(keys(var.db_users))) — keys() keeps the mark and returns a list, so both wrappers are needed — while arguments such as password = var.db_users[each.key] still read the sensitive map and stay redacted. Never key instances by the secret values themselves.

In expressions, a resource or module that uses for_each is a map of instance objects keyed like its for_each. Splat expressions ([*] or the legacy .*) do not iterate a map, and tolist() cannot convert one, so convert first:

# list of every instance's attribute
values(aws_instance.app)[*].private_ip
[for m in module.queue : m.arn]          # one symbol = the values
{ for k, m in module.queue : k => m.arn } # two symbols: k is the key string

One map can drive another: for_each = aws_vpc.this gives the dependent resource one instance per VPC with the same keys, and inside it each.value is the whole upstream object, so vpc_id = each.value.id (or aws_vpc.this[each.key].id). When the two maps have different keys, index with a value that matches the other map's keys — a subnet keyed prod-a that carries vpc = "prod" uses aws_vpc.this[each.value.vpc].id; indexing with its own each.key fails with Invalid index. Passing each.value where a string is expected, or reading an attribute from the key string, are the usual mistakes.

Terraform matches configuration to state by address, so an instance's identity is its key (for for_each) or its position (for count).

So for_each keys should come from stable content, never from list indexes ({ for i, g in local.grants : tostring(i) => g } has the same shifting problem as count). When building a map with a for expression, each key must be unique or the plan fails with Duplicate object key. Two responses, for two different requirements:

• One instance per unique combination: build a composite key, e.g. "${g.user}-${g.db}" => g, so each pair gets its own stable address. distinct() only removes identical objects and does not fix colliding keys.
• One entry per key, collecting the rest: add ... after the value (grouping mode): { for u in local.users : u.team => u.name... } gives data = ["ana", "li"]. Each value is then a list, so each.value.attr no longer works. merge() of single-key maps silently keeps the last value for a repeated key.

Moving state addresses with moved blocks and state commands is covered with state operations; for tracing, recognise that a key change is a destroy-and-create in the plan.