Input variable precedence order in Terraform - Deep Dive

Overview - Input variable precedence order

What is it?

Input variable precedence order in Terraform is the rule that decides which value Terraform uses when the same input variable is set in multiple places. Terraform allows you to set variables in different ways, like in files, environment variables, or command line. The precedence order tells Terraform which value wins when there are conflicts. This helps ensure your infrastructure configuration is predictable and easy to manage.

Why it matters

Without a clear precedence order, Terraform might use unexpected values for variables, causing your infrastructure to behave differently than you planned. This can lead to errors, downtime, or security issues. Knowing the precedence order helps you control your infrastructure reliably and avoid surprises when deploying or updating resources.

Where it fits

Before learning variable precedence, you should understand what Terraform variables are and how to define them. After this, you can learn about Terraform workspaces and modules, which also affect how variables are used and overridden.

Mental Model

Core Idea

Terraform chooses variable values by checking sources in a fixed order, using the first value it finds and ignoring lower-priority ones.

Think of it like...

It's like packing for a trip with multiple suitcases labeled by priority: you always take the item from the highest priority suitcase first, ignoring duplicates in lower priority ones.

┌─────────────────────────────┐
│ Terraform Variable Sources   │
├─────────────────────────────┤
│ 1. Command Line Flags        │
│ 2. Environment Variables     │
│ 3. .tfvars Files             │
│ 4. Default Variable Values   │
└─────────────────────────────┘

Terraform checks from top to bottom and uses the first value it finds.

Build-Up - 7 Steps

1

Foundation

What Are Terraform Input Variables

Concept: Introduce the idea of input variables as placeholders for values in Terraform configurations.

Terraform input variables let you customize your infrastructure by using placeholders instead of hard-coded values. You define variables in your configuration files, and then provide values when you run Terraform. This makes your code reusable and flexible.

Result

You can write one Terraform configuration and deploy different environments by changing variable values.

Understanding variables is key to making Terraform configurations adaptable and reusable.

2

Foundation

Ways to Set Variable Values

Concept: Explain the different methods to provide values for variables in Terraform.

You can set variable values in several ways: directly in the Terraform configuration with defaults, in separate files called .tfvars, through environment variables, or by passing them as command line flags when running Terraform commands.

Result

Terraform accepts variable values from multiple sources, giving you flexibility in how you configure your infrastructure.

Knowing all the ways to set variables helps you choose the best method for your workflow.

3

Intermediate

Understanding Precedence Order

🤔Before reading on: do you think Terraform uses the last variable value it finds or the first one? Commit to your answer.

Concept: Introduce the concept that Terraform checks variable sources in a specific order and uses the first value it finds.

Terraform looks for variable values in this order: command line flags, environment variables, .tfvars files, then default values in the configuration. It stops at the first place it finds a value and ignores the rest. This order is called the precedence order.

Result

When multiple values are set for the same variable, Terraform uses the one from the highest priority source.

Understanding this order prevents confusion and unexpected behavior when variables are set in multiple places.

4

Intermediate

Command Line Flags Override Everything

🤔Before reading on: do you think environment variables can override command line flags? Commit to your answer.

Concept: Explain that command line flags have the highest priority and always override other variable sources.

When you run Terraform commands, you can pass variables directly using -var or -var-file flags. These values have the highest precedence and will override environment variables, .tfvars files, and defaults.

Result

Values passed on the command line always take effect, no matter what else is set.

Knowing this helps you quickly test or change variables without modifying files or environment settings.

5

Intermediate

Environment Variables and .tfvars Files

🤔Before reading on: which do you think has higher priority: environment variables or .tfvars files? Commit to your answer.

Concept: Clarify the order between environment variables and .tfvars files in the precedence chain.

Environment variables that start with TF_VAR_ have higher priority than .tfvars files. If a variable is set in both, Terraform uses the environment variable value. .tfvars files are useful for grouping variable values for different environments.

Result

Environment variables override .tfvars files, which override default values.

This knowledge helps you organize variable values effectively and avoid conflicts.

6

Advanced

Default Values and Missing Variables

🤔Before reading on: if no value is set anywhere, what does Terraform do? Commit to your answer.

Concept: Explain how Terraform handles variables without any provided value and the role of default values.

If a variable has a default value in the configuration, Terraform uses it when no other value is set. If there is no default and no value is provided, Terraform will prompt you to enter a value or fail if running non-interactively.

Result

Default values provide a fallback, ensuring Terraform can run without all variables explicitly set.

Understanding defaults prevents deployment failures and helps design user-friendly configurations.

7

Expert

Variable Precedence in Modules and Workspaces

🤔Before reading on: do you think variable precedence rules change inside modules or workspaces? Commit to your answer.

Concept: Explore how variable precedence applies when using modules and workspaces in Terraform.

Inside modules, variables are passed explicitly from the calling configuration, so precedence applies at the root level. Workspaces do not change variable precedence but can affect variable values if you use workspace-specific .tfvars files. Understanding this helps manage complex infrastructure setups.

Result

Variable precedence remains consistent, but modules and workspaces add layers where variables are set or overridden.

Knowing how precedence works with modules and workspaces helps avoid subtle bugs in large Terraform projects.

Under the Hood

Terraform reads variable values in a fixed sequence during the plan phase. It first checks command line flags passed to the terraform command, then environment variables prefixed with TF_VAR_, then any .tfvars files loaded automatically or specified, and finally the default values defined in the configuration. This sequence is hardcoded in Terraform's core logic to ensure predictable behavior. When a value is found at a higher precedence level, Terraform stops searching lower levels for that variable.

Why designed this way?

This design balances flexibility and clarity. Command line flags allow quick overrides for testing or automation. Environment variables support integration with CI/CD pipelines and secrets management. .tfvars files enable grouping of variables for different environments. Defaults provide sensible fallbacks. Alternatives like merging all values would cause confusion and unpredictable results, so a clear precedence order was chosen.

┌───────────────────────────────┐
│ Terraform Variable Resolution  │
├───────────────────────────────┤
│ 1. Command Line Flags          │
│          ↓                    │
│ 2. Environment Variables (TF_VAR_) │
│          ↓                    │
│ 3. .tfvars Files               │
│          ↓                    │
│ 4. Default Values             │
└───────────────────────────────┘

Terraform uses the first value found and ignores the rest.

Myth Busters - 4 Common Misconceptions

Quick: Do environment variables override command line flags? Commit to yes or no.

Common Belief: Environment variables always override command line flags because they are set at the system level.

Reality: Command line flags have higher precedence and override environment variables.

Why it matters: Believing otherwise can cause confusion when command line changes seem ignored, leading to deployment errors.

Quick: If a variable is set in multiple .tfvars files, does Terraform merge them or pick one? Commit to your answer.

Common Belief: Terraform merges all .tfvars files and combines their variable values.

Reality: Terraform loads .tfvars files in order and later files override earlier ones for the same variable.

Why it matters: Assuming merging can cause unexpected variable values and hard-to-find bugs.

Quick: Does Terraform use default variable values if a variable is set in a .tfvars file? Commit to yes or no.

Common Belief: Default values always override .tfvars file values.

Reality: .tfvars file values override default values; defaults are only used if no other value is set.

Why it matters: Misunderstanding this can cause you to think changing defaults will affect deployments when .tfvars files are actually controlling values.

Quick: Do variable precedence rules change inside modules? Commit to yes or no.

Common Belief: Modules have their own separate variable precedence rules independent of the root configuration.

Reality: Modules receive variables from the root configuration, so precedence applies at the root level; modules do not override precedence rules.

Why it matters: Thinking modules handle precedence differently can lead to incorrect assumptions about variable values and module behavior.

Expert Zone

1

Terraform does not merge variable values from different sources; it uses the first value found in precedence order, which means partial overrides require careful variable design.

2

Environment variables must be prefixed with TF_VAR_ exactly to be recognized as variable values, which is a subtle but critical detail.

3

When using workspaces, you can load workspace-specific .tfvars files automatically by naming them with the workspace name, adding complexity to variable resolution.

When NOT to use

Input variable precedence order is fixed and cannot be changed. If you need dynamic or conditional variable resolution, consider using Terraform locals, data sources, or external scripts instead. For secret management, use dedicated secret managers rather than environment variables to avoid security risks.

Production Patterns

In production, teams often use .tfvars files per environment (like dev.tfvars, prod.tfvars) combined with environment variables for secrets. Command line flags are used for quick overrides during automation. Modules receive variables explicitly to maintain clear boundaries. Workspace-specific .tfvars files help manage multiple environments with the same codebase.

Connections

Configuration Management

Both use precedence rules to decide which configuration value applies when multiple sources exist.

Understanding Terraform's variable precedence helps grasp how tools like Ansible or Chef resolve conflicting settings.

Operating System Environment Variables

Terraform environment variables follow OS environment variable conventions but add a prefix to distinguish variable values.

Knowing OS environment variable behavior clarifies how Terraform picks up and prioritizes its variables.

Priority Queues (Computer Science)

Terraform's variable precedence order acts like a priority queue where higher priority sources are checked first.

Recognizing this pattern helps understand other systems that resolve conflicts by priority.

Common Pitfalls

#1 Setting a variable in both environment variable and .tfvars file but expecting the .tfvars value to be used.

Wrong approach:

export TF_VAR_region="us-west-1"
# Also have region = "us-east-1" in terraform.tfvars
terraform apply

Correct approach:

# Remove or change environment variable to let .tfvars take effect
unset TF_VAR_region
terraform apply

Root cause:

Misunderstanding that environment variables have higher precedence than .tfvars files.

#2 Passing variable values on the command line but also setting them in .tfvars files and expecting .tfvars to override.

Wrong approach:

terraform apply -var='instance_type=t2.micro'
# instance_type = "t2.large" in production.tfvars

Correct approach:

# Remove -var flag or update it to desired value
terraform apply -var='instance_type=t2.large'

Root cause:

Not knowing command line flags override all other variable sources.

#3 Defining a variable without a default and not providing a value anywhere, expecting Terraform to use an empty string.

Wrong approach:

variable "project_name" {}
terraform apply

Correct approach:

variable "project_name" {
default = "default-project"
}
terraform apply

Root cause:

Assuming variables without defaults have implicit empty values, but Terraform requires explicit values or defaults.

Key Takeaways

Terraform uses a fixed order to decide which variable value to use, starting from command line flags down to default values.

Command line flags have the highest priority, followed by environment variables, then .tfvars files, and finally default values.

Understanding this order helps avoid unexpected behavior and makes your infrastructure code predictable and manageable.

Modules and workspaces do not change the precedence order but add layers where variables are set or overridden.

Misunderstanding precedence can cause subtle bugs, so always know where your variable values come from.