Variable Input Precedence

Production applies do not run with a single source of values. A region might come from a .tfvars file in Git, an instance count might come from a CI -var flag, and a backup retention period might come from an environment variable. Terraform resolves all of them in a defined order. The operator who does not know the order is the operator who is surprised when the wrong value lands in production.

A real production incident: the team kept environment variables in .envrc for local dev. One engineer ran terraform plan with TF_VAR_region=us-east-1 still exported. The plan produced resources in us-east-1 instead of eu-west-2, was approved, and the apply created 80 resources in the wrong region. The fix was $ unset TF_VAR_region and a CI check that fails the build when TF_VAR_* is set.

The precedence order

Terraform consults variable sources in a fixed order. The first source that supplies a value wins; later sources are ignored for that variable.

Highest  -var CLI flag (and -var-file)
              |
          *.auto.tfvars (alphabetical: a- < b- < c-)
              |
          terraform.tfvars (a specific filename)
              |
          TF_VAR_<name> environment variable
              |
Lowest   default in the variable block

# CONFIGURATION

# variables.tf
variable "region" {
  type        = string
  description = "AWS region for all resources in this configuration."
  default     = "eu-west-2"
}

variable "instance_count" {
  type        = number
  description = "Number of application instances."
  default     = 2
}

Demonstration across three sources

Same region variable, three invocation patterns, three resolved values:

# READ-ONLY — auto-loaded *.auto.tfvars provides region
# Files on disk: production.auto.tfvars with region = "eu-west-2"
terraform plan
# Resolves: region = eu-west-2, instance_count = 2 (from default)

# CONFIGURATION — environment variable overrides auto-loaded
TF_VAR_region="us-east-1" terraform plan
# Resolves: region = us-east-1, instance_count = 2

# CONFIGURATION — CLI flag wins over both
terraform plan -var="region=ap-southeast-2" -var="instance_count=4"
# Resolves: region = ap-southeast-2, instance_count = 4

The -var-file flag is at the same precedence as -var, not above it. Two -var-file flags are merged, with the later one winning for overlapping keys.

Auto-loaded tfvars files

Terraform loads two filename patterns automatically:

• terraform.tfvars (a single specific filename)
• Any file matching *.auto.tfvars or *.auto.tfvars.json

The auto-loaded files are read in alphabetical order. If two files set the same variable, the file sorted later wins. The order is not the modification time — it is the filename, lexicographically.

Loading order (alphabetical):
  alpha.auto.tfvars     -> sets region = "eu-west-1"
  beta.auto.tfvars      -> sets region = "us-east-1"
  production.auto.tfvars -> sets region = "eu-west-2"  (winner)

  terraform.tfvars      -> sets instance_count = 6

A subtle production trap: production.auto.tfvars is alphabetically before staging.auto.tfvars, but the operator expects production to win because it is production. The filename is the source of truth, not the environment name. If two files both define region, the alphabetically-later one wins.

WhyThisMatters

WhyThisMatters CI pipelines fail closed when the precedence is right. A pipeline that runs terraform plan against main with no -var-file flag is silently reading whatever *.auto.tfvars files the checkout happens to contain. The plan looks correct. The apply lands in the wrong account. The fix is explicit: every CI invocation passes -var-file=environments/production.tfvars and the file is fetched from a secrets manager.

Failure modes

1. Local checkout has prod.auto.tfvars; CI does not. Engineer A’s terraform plan shows resources in eu-west-2. The same plan in CI fails because the file is in .gitignore. Precedence is unchanged; the source is missing in CI.

2. TF_VAR_* leaked into shell from a previous session. Engineer B opens a new terminal, runs terraform plan, and the env var from a different project overrides the -var-file. The plan succeeds with values from the wrong source.

3. Two *.auto.tfvars files set the same variable. Engineer C expects production.auto.tfvars to win; staging.auto.tfvars does win because it sorts later. The apply lands in staging.

4. -var-file and -var both set the same variable. Engineer D passes -var-file=prod.tfvars and -var=region=eu-west-2. The CLI -var wins. The engineer assumed the file wins because it is “the production config.”

5. Sensitive value committed in *.auto.tfvars. The file lands in Git; the secret leaks to every contributor and the Git history.

6. CI logs the -var-file content. The file is mounted from a secret, the CI step dumps the working directory, and the secret appears in the build log.

Recovery

When the wrong value lands in a plan, the recovery is the same in every case: identify the source, override it, and re-plan.

# READ-ONLY — inspect the resolved value
echo "region=${var.region}"

# READ-ONLY — list every source that could set the value
terraform plan -var-file=production.tfvars | grep -i "var.region"

If a TF_VAR_* is set unexpectedly:

# READ-ONLY
env | grep ^TF_VAR_

# RESET
unset TF_VAR_region

If the issue is a stray *.auto.tfvars:

# READ-ONLY
ls -1 *.auto.tfvars terraform.tfvars

Production guidance

• One source per environment. A single -var-file=environments/prod.tfvars in CI; no CLI overrides except documented emergencies.
• Stable filenames. If you use auto-loaded files, the filename must not change between environments.
• Explicit TF_VAR_* policy. CI runs unset TF_VAR_* before the apply to neutralise leakage.
• Audit .tfvars for secrets. Use git-secrets or a pre-commit hook to block commits that contain credential-shaped strings.
• Never commit *.auto.tfvars.json with sensitive values. Use data sources for secrets, not tfvars.

What comes next

The next lesson is Sensitive Values and the Production Interface — what sensitive = true actually hides, what it does not, and the audit discipline that turns the flag into a real control.

Verification

1. You declare default = "eu-west-2" and pass -var-file=prod.tfvars which sets region = "us-east-1". What does Terraform use?
2. Two files exist: alpha.auto.tfvars and beta.auto.tfvars. Both set region. Which wins, and why?
3. CI runs terraform plan with no flags. Your local checkout has prod.auto.tfvars but the CI checkout does not. What is the difference in resolved values, and what is the production risk?
4. TF_VAR_db_password is exported in your shell but not in CI. What is the most likely production outcome and how do you prevent it?