Skip to main content
Variable repetition across many workspaces is a common operational headache. Variable sets provide a centralized, reusable way to manage variables so you don’t have to duplicate the same values across multiple workspaces. Imagine six production workspaces — networking, web, customer-data, app1, cache, and processing — each deployed to Google Cloud Platform and each requiring the same GCP credential (for example, an environment variable containing credentials). Setting that credential separately for each workspace is time-consuming and error-prone: when credentials rotate or are revoked, you would need to update every workspace individually.
A presentation slide titled "Variable Repetition" showing six Google Cloud icons across the top. Each icon is linked by an arrow to a purple box naming a production service (networking-prod, web-prod, customer-data-prod, app1-prod, cache-prod, processing-prod) with labels indicating they use an ENV_GOOGLE_CREDENTIALS variable marked "sensitive."
What variable sets solve
  • Variable sets let you define a named collection of variables once and apply them to one or more workspaces or projects.
  • They reduce duplication, simplify credential rotation, and centralize configuration for shared settings (e.g., cloud credentials, database defaults, instance sizes, audit settings).
Example groupings for variable sets:
  • Production cloud: AWS credentials (secret id, secret access key, region).
  • Database settings: read/write capacity defaults.
  • VM sizing: instance types for QA, Test, and Prod.
  • Audit configs: logging path and rotation settings applied org-wide.
Notice the pattern: each variable set targets a specific concern rather than grouping unrelated variables into one giant set. Apply sets at whatever scope matches your workflow: specific workspaces, projects, or organization-wide.
A presentation slide titled "What Are Variable Sets?" that explains reusable variable sets for Terraform/workspaces with bullet points. The right side shows a purple diagram illustrating variable sets applied to different project workspaces.
Example variables (env-style)
Store sensitive credentials using the platform’s sensitive/secret variable options. Avoid putting plaintext secrets in VCS or documentation.
Scopes: where variable sets apply Variable sets map directly to the organization hierarchy. Choose the scope that best fits the purpose of the variables: Use narrower scopes for team- or workload-specific settings, and global scope only for truly organization-wide defaults.
A purple infographic slide titled "Variable Set Scopes" showing stacked blocks labeled Organization, Project, and Workspace alongside three scope types — Global, Project‑Scoped, and Workspace‑Scoped — with short descriptions of which workspaces each applies to.
Variable precedence: which value wins When the same variable key exists in multiple places, HCP Terraform follows a clear precedence model. The most important principle to remember:
  • Workspace-specific variables override values from variable sets applied to that workspace.
Example scenario:
  • Variable set defines:
    • db_write_capacity = 1
    • db_read_capacity = 1
  • The set is applied to three workspaces; all three inherit both values.
  • For one workspace (e.g., a reporting app) you set a workspace-specific variable:
    • db_read_capacity = 10
Result: the reporting workspace uses db_read_capacity = 10, while the other two workspaces continue to use db_read_capacity = 1.
Workspace-specific variables always take precedence over values from variable sets applied to that workspace.
Additional precedence rules
  • Priority variable sets: You can mark a variable set as a priority set. Priority sets override values even in more specific scopes (including workspace-specific variables). Use this sparingly for admin-enforced values (e.g., security or compliance defaults). Note: runtime inputs usually override priority sets.
  • CLI and environment overrides: Values passed at runtime via CLI flags (-var, -var-file) or environment variables prefixed with TF_VAR_ override workspace and variable set values. These runtime inputs generally have the highest precedence for a run.
  • Conflicts between variable sets at the same scope: If multiple variable sets at the same scope define the same key, HCP Terraform resolves the conflict by lexical (alphabetical) order of the variable set names — the alphabetically first set wins.
A purple-themed slide titled "Variable Precedence" that lists Terraform variable precedence rules. It shows three boxed points explaining priority variable sets, CLI flags/TF_VAR overrides, and lexical (alphabetical) ordering when variable sets conflict.
Best practices and recap
  • Centralize shared credentials and settings in variable sets to reduce duplication and simplify rotation.
  • Choose scope deliberately: use Global sparingly, Project for team-wide defaults, Workspace for targeted overrides.
  • Use priority sets only when you need admin-enforced, non-overridable values.
  • Expect runtime CLI and TF_VAR_ environment values to take precedence when running Terraform.
  • When conflicts arise between sets at the same scope, alphabetical ordering determines which set wins.
Further reading and references A hands-on HCP Terraform walkthrough (creating variable sets, applying scopes, and testing overrides) will make these rules concrete and help you see how changes propagate to workspaces.

Watch Video