Variable Precedence

## The ordered list Terraform collects a value for every root-module input variable from these sources, applying them in order so that a later source overrides an earlier one: 1. The `default` in the `variable` block — the fallback if nothing else supplies a value. 2. `TF_VAR_<name>` environment variables. 3. The `terraform.tfvars` file, if present. 4. The `terraform.tfvars.json` file, if present. 5. Any `*.auto.tfvars` or `*.auto.tfvars.json` files, in lexical order of their filenames. 6. Any `-var` and `-var-file` options on the command line, in the order they are given. If several `-var`/`-var-file` options touch the same variable, the rightmost one wins, because they are simply processed left to right. Variables set in an HCP Terraform (formerly Terraform Cloud) workspace arrive at that same top tier. ## The default is a fallback, not really a tier It helps to think of the `default` as what the variable is worth when no source assigned it, rather than as the first coat of paint. A variable declared without a default is not "empty": if nothing supplies a value, Terraform has no value at all and either prompts for one or fails. That distinction is what makes a defaultless variable a good way to force an environment to be named explicitly. ## The environment-variable surprise The single most-missed fact is that `TF_VAR_` sits at the **bottom** of the real sources. It is described in the documentation as a fallback for the other ways of defining variables. Intuition says the opposite — everywhere else in Unix tooling an environment variable is an override — and that intuition is what produces the classic incident: a pipeline exports `TF_VAR_app_version` from its release metadata, someone commits a `dev.auto.tfvars` that also pins `app_version`, and the pipeline's value stops taking effect with no error anywhere. ```bash export TF_VAR_region=eu-west-1 # loses... cat region.auto.tfvars # ...to this # region = "us-east-1" ``` Terraform converts the string in the environment variable to the variable's declared type, so a list can be supplied as `TF_VAR_zones='["eu-west-1a","eu-west-1b"]'`. Names are case-sensitive and match the declared variable name exactly. ## Command-line options are ordered among themselves ```bash terraform plan \ -var-file=common.tfvars \ -var-file=prod.tfvars \ -var='instance_count=6' ``` This is a deliberate layering idiom: shared values first, environment values next, one-off overrides last. It also means an operator can always win an argument with the repository, which is convenient in an incident and dangerous as a habit — nothing about a `-var` override is reviewable afterwards unless the job log records the command. ## No merging for complex types Since Terraform 0.12, a map or object variable behaves like any other: the highest-precedence source replaces the entire value. Setting `tags = { team = "payments" }` in `terraform.tfvars` and `tags = { env = "prod" }` via `-var-file` gives you `{ env = "prod" }`, not the union. If you want merging, do it in the configuration — a `locals` expression that merges a common map with a per-environment map — rather than expecting the loader to do it. ## Working out which value actually won There is no built-in "explain this variable" command, so you bisect the list in order: - `env | grep TF_VAR_` in the exact shell or job that runs Terraform. - List the directory for `terraform.tfvars*` and `*.auto.tfvars*` — remembering that `-chdir` changes which directory that is. - Read the full Terraform command line from the CI job log, including options injected by a wrapper script. A temporary `output` echoing the value, or `terraform console` in the same directory, confirms what the configuration actually resolved. Note that a value assigned to a variable the root module does not declare produces a warning about a value for an undeclared variable and is then ignored — so a misspelled name in a tfvars file looks exactly like a precedence problem. ## Why interviewers ask this Because it is the mechanism behind "it works on my laptop but not in CI", and its inverse. A candidate who can recite the order and then say *why* the environment tier being low matters has shown they have debugged a real pipeline, not just read the documentation page.