Terraform .tfvars Files: A Practical Playbook for Managing Variables

Mastering .tfvars files is essential for writing safe, reproducible, and scalable Terraform code. This playbook provides actionable steps, checklists, and best practices to manage your infrastructure-as-code variables effectively.

Key Takeaways

• Separation of Concerns: Keep your main .tf files clean by defining variables once and managing their values in separate .tfvars files.
• Default Behavior: If you run terraform apply without a specific flag, Terraform automatically loads terraform.tfvars and terraform.auto.tfvars. All other .tfvars files must be explicitly specified using the -var-file flag.
• Precedence Matters: Command-line flags (-var) override variable files. Variable files override defaults defined in variable blocks.
• Security First: Never commit sensitive secrets (API keys, passwords) to version control. Use encrypted sources or Terraform Cloud for sensitive data.

File Naming Conventions and Precedence

Understanding which files Terraform loads, and in what order, prevents unexpected overwrites. The order of precedence from lowest to highest is as follows:

1. Lowest Precedence: terraform.tfvars and terraform.auto.tfvars (loaded automatically).
2. Medium Precedence: Any file passed explicitly via the -var-file flag.
3. Highest Precedence: Values passed via the -var flag on the command line.

Comparison Table: Variable Source Types

Source	File Name	Auto-Loaded?	Use Case
Default	terraform.tfvars	Yes	Project-wide defaults, non-sensitive config.
Default (Hidden)	terraform.auto.tfvars	Yes	Values that should not be checked into VCS (ignored by git by default in some conventions).
Environment Specific	dev.tfvars, prod.tfvars	No	Environment-specific configurations loaded via -var-file.
CI/CD Specific	ci.tfvars	No	Pipeline-specific variables, often generated dynamically.

Actionable Checklist: Implementing .tfvars Best Practices

• Define Variables in Code: Ensure every variable used in your .tf files is declared in a variable block with a description and, ideally, a default value.
• Create a Base File: Create terraform.tfvars for shared, non-sensitive values (e.g., instance types, region).
• Split by Environment: Create dev.tfvars and prod.tfvars for values that change per environment (e.g., instance sizes, tags).
• Use Explicit Flags: When applying, always specify the environment file: terraform apply -var-file="prod.tfvars".
• Handle Secrets Separately: Do not put secrets in .tfvars files that are committed to Git. Use terraform.auto.tfvars (if ignoring it in Git) or an external secret manager.
• Validate Syntax: Run terraform validate after updating .tfvars files to catch syntax errors early.

Common Pitfalls and How to Avoid Them

Accidentally Overwriting Critical Values

If you have a sensitive value in terraform.tfvars and pass a less secure value via -var-file=dev.tfvars, you might think the dev file wins. Remember: terraform.tfvars is loaded first. If a variable is defined in both, the later file in the load sequence (or command-line flag) overrides the earlier one. To avoid confusion, keep terraform.tfvars minimal.

Forgetting the -var-file Flag

Running terraform apply in a prod environment directory but forgetting -var-file=prod.tfvars will use the defaults from terraform.tfvars. This can deploy incorrect infrastructure. Mitigate this by using terraform workspace or separate directories per environment.

FAQs

Q1: Can I use .tfvars files for secrets?

No. Standard .tfvars files are plain text and often committed to version control. For secrets, use terraform.auto.tfvars (and add it to .gitignore), or better yet, use Terraform Cloud/Enterprise, HashiCorp Vault, or AWS Secrets Manager. Never commit secrets to your repository.

Q2: What is the difference between terraform.tfvars and variables.tf?

variables.tf is where you declare variables, their types, descriptions, and default values. terraform.tfvars is where you assign actual values to those declared variables. You need both: the declaration defines the contract, and the .tfvars file provides the implementation data.

Q3: How do I load multiple .tfvars files at once?

You can specify multiple -var-file flags in a single command. For example: terraform apply -var-file=base.tfvars -var-file=dev.tfvars. The files are loaded in the order specified. If a variable is defined in both base.tfvars and dev.tfvars, the value from dev.tfvars will take precedence because it is listed last.