Skip to main content
In this guide you’ll learn how to create and apply Terraform Cloud (HCP Terraform) variable sets for three common scopes: organization-wide, project-level, and workspace-level. Variable sets let you centrally manage shared Terraform and environment variables and apply them to many workspaces without duplicating configuration. When used correctly they promote consistency across teams; when used poorly they can expose secrets—so follow best practices for sensitive values.
Use variable sets to centralize shared configuration such as logging endpoints, feature flags, or common Terraform variable defaults. Avoid relying on variable sets for long-lived credentials; prefer short-lived credentials or an external secrets manager and inject secrets at runtime where possible.

​
Why use variable sets?

  • Reduce duplication by sharing common values across multiple workspaces.
  • Enforce consistent configuration across projects and teams.
  • Apply updates centrally and have them propagate to all attached workspaces.
  • Control override behavior using the variable set priority setting.
For more details, see the Terraform Cloud docs: Terraform Cloud — Variable sets.

​
Create an organization-level variable set

Organization-level variable sets can be applied to all projects and workspaces, or scoped to selected projects and workspaces. When applied to a project, all current and future workspaces in that project inherit the set. Steps:
  1. In Terraform Cloud, open Settings from the left sidebar and select Variable Sets.
  2. Click to create a new Organization variable set.
  3. Enter a descriptive name (for example, AWS Production) and an optional description (for example, production credentials).
  4. Choose the scope:
    • Apply to all projects and workspaces (organization-wide), or
    • Apply to specific projects and/or specific workspaces.
When adding variables:
  • Choose the variable type: Terraform variable or Environment variable.
  • Enter the key and value (for example AWS_SECRET_ACCESS_KEY).
  • Mark secrets as Sensitive so values are masked in the UI after saving.
A screenshot of a Terraform Cloud web UI showing an "Add variable" dialog with "Environment variable" selected and the Key field filled with "AWS_SECRET_ACCESS_KEY". The Value field is empty and options for marking the variable as sensitive and adding a description are visible.
Example workflow:
  • Click Add variable.
  • Select the variable type (Terraform or Environment).
  • Enter the key (AWS_SECRET_ACCESS_KEY) and the value.
  • Mark the variable as Sensitive if it is a secret, then click Add.
  • Add additional variables as needed (e.g., AWS_ACCESS_KEY_ID) and click Create variable set to finish.
Note: Enable the variable set priority checkbox to have this set’s variables override less-specific variables (for example, workspace variables). Use this carefully when you want organization or project defaults to take precedence over workspace-specific values.
Avoid storing long-lived cloud credentials directly in Terraform Cloud. Sensitive variables are masked in the UI but can still be consumed by runs that have access. Prefer short-lived credentials or an external secrets manager and restrict access to variable set management.

​
Create a project-level variable set

Project-level variable sets apply only to a single project and its workspaces. These are ideal when several workspaces within the same project share configuration but you do not want those variables available organization-wide. Steps:
  1. Open the target project (for example, HCP demo) and go to Settings → Variable Sets.
  2. Click to create a new Project variable set.
  3. Provide a name and description (for example, project-variable-set).
  4. Choose the scope: apply to the entire project or to specific workspaces within that project.
  5. Add variables following the same process described above and click Create variable set.
Project-level sets will affect every workspace in that project (current and future) unless you specifically scope them to selected workspaces.

​
Inspect applied variable sets at the workspace level

To view which variable sets affect a workspace:
  1. Open the workspace (for example networking-prod).
  2. Click Variables in the workspace navigation.
  3. Scroll to the section that lists Variable Sets applied to this workspace.
This section shows any project-level sets and any applicable organization-level sets. Sensitive variable values will be masked in the UI.
Screenshot of the Terraform Cloud workspace "networking-prod" Variables page showing a "project-variable-set" (no variables) and an "aws-production" variable set containing a sensitive AWS_SECRET_ACCESS_KEY entry. The left sidebar shows workspace navigation (Overview, Runs, States, Variables) and an "Apply variable set" button is visible.

​
Scope and precedence summary

Key precedence rules:
  • Workspace variables normally take precedence over variable set values.
  • If a variable set has priority enabled, its variables can override workspace-defined values.
  • Sensitive variables are masked, but runs with appropriate access can still read them.

​
Best practices

  • Use organization-level sets for company-wide defaults and environment-level configuration that should be consistent across projects.
  • Use project-level sets for values shared by workspaces within the same project (e.g., network CIDR prefixes, project IDs).
  • Keep secrets out of long-lived variable sets where feasible; prefer short-lived credentials or an external secrets manager (e.g., HashiCorp Vault, AWS Secrets Manager).
  • Use the variable set priority option intentionally and document when and why a set has priority to avoid confusing overrides.
  • Audit who can manage variable sets and limit permissions to reduce risk of accidental secret exposure.
Further reading: That covers creating, scoping, and inspecting variable sets in Terraform Cloud.

Watch Video