Terraform Cloud Variable Sets are a powerful feature for managing and sharing sensitive or common configuration values across multiple Terraform workspaces, but their most surprising utility lies in their ability to enforce consistent configurations and reduce drift, not just convenience.
Let’s see this in action. Imagine you have a set of common tags that every resource in your infrastructure should inherit, like environment: production and owner: devops-team. Instead of manually adding these to every resource block in every Terraform module, you can define them once in a Variable Set.
# In your Terraform Cloud Variable Set:
variable "common_tags" {
type = map(string)
description = "Common tags to apply to all resources."
default = {
environment = "production"
owner = "devops-team"
}
}
Then, in your Terraform workspace’s configuration, you can reference these variables.
# In your Terraform workspace's main.tf:
resource "aws_instance" "app_server" {
ami = "ami-0abcdef1234567890"
instance_type = "t2.micro"
tags = merge(
{
Name = "my-app-server"
},
var.common_tags # This is where the magic happens!
)
}
When you run terraform plan in this workspace, Terraform Cloud will automatically inject the common_tags from the associated Variable Set into the workspace’s execution environment. The aws_instance resource will then be provisioned with the Name tag, plus the environment and owner tags from the Variable Set.
The core problem Variable Sets solve is the DRY (Don’t Repeat Yourself) principle applied to infrastructure configuration. Without them, you’d find yourself copy-pasting common variables, sensitive credentials, or environment-specific settings across dozens, if not hundreds, of Terraform files and workspaces. This leads to:
- Inconsistency: Different workspaces might have slightly different tag values, or outdated versions of sensitive data.
- Error Prone: Manual updates are a recipe for typos and missed changes.
- Maintenance Burden: Updating a common value requires modifying every single place it’s used.
Variable Sets provide a centralized source of truth. When you update a variable in a Variable Set, that change is immediately reflected in all workspaces assigned to that set. This drastically simplifies management and ensures uniformity across your infrastructure.
Internally, Terraform Cloud treats variables from Variable Sets as if they were declared directly in the workspace’s variables.tf file, but with a higher precedence. This means if you define a variable with the same name both in a local variables.tf and in a Variable Set, the value from the Variable Set will win. The exact levers you control are:
- Variable Set Assignment: You choose which workspaces are associated with a given Variable Set. A workspace can be linked to multiple Variable Sets, with variables from later sets in the order overriding earlier ones.
- Variable Types and Defaults: You define the data type (string, number, bool, list, map, object) and can provide default values, though these are often overridden by workspace-specific values if needed.
- Sensitive Variables: You can mark variables as sensitive, ensuring their values are masked in Terraform Cloud UI and logs.
The mechanism by which Terraform Cloud injects these variables is crucial. When a Terraform run is initiated, Terraform Cloud aggregates all variables from the workspace’s own configuration, any associated Terraform Cloud Terraform Variables (which have the highest precedence), and all linked Variable Sets (ordered by their assignment order). This combined set of variables is then provided to the Terraform CLI process running the plan or apply. This means you don’t need to explicitly terraform import or terraform apply anything; the variables are simply available in the execution environment.
One aspect often overlooked is how Variable Sets interact with different environments. You might have a "Global Defaults" Variable Set for common tags and then a "Production Environment" Variable Set that overrides specific values like database endpoints or instance sizes for production workspaces. This layering allows for granular control. A workspace can inherit variables from multiple Variable Sets, and the order in which they are assigned to the workspace dictates precedence, with later Variable Sets overriding earlier ones if variable names conflict.
The next logical step after mastering Variable Sets is exploring how to programmatically manage them using the Terraform Cloud API, enabling automated creation and assignment based on your organizational structure.