HCP Terraform (Terraform Cloud) — Complete Guide to Variables, Scope & Precedence

Updated: October 2026 | Based on current HashiCorp documentation

HCP Terraform provides several ways to pass values to Terraform code. These include variable defaults, .tfvars files, environment variables, workspace variables, project/organization variable sets, and run-specific CLI arguments.

The three most important things to understand are:

1. Type: Is it a Terraform input variable or an environment variable?
2. Scope: Does the value apply to one run, one workspace, a project, or the entire organization?
3. Precedence: When the same variable is defined in multiple places, which value wins?

One particularly important rule: Workspace variables normally override variable sets, but Priority Variable Sets can override even workspace variables and command-line values.

1. Two types of variables in HCP Terraform

Example A: Terraform input variable

In variables.tf:

variable "instance_type" {
  description = "EC2 instance type"
  type        = string
  default     = "t3.micro"
}Code language: JavaScript (javascript)

In HCP Terraform, configure:

Category: Terraform variable
Key:      instance_type
Value:    t3.mediumCode language: HTTP (http)

And access it in code:

resource "aws_instance" "example" {
  ami           = var.ami_id
  instance_type = var.instance_type
}Code language: JavaScript (javascript)

Terraform uses t3.medium, overriding the default t3.micro.

Example B: Environment variable

In HCP Terraform:

Category: Environment variable
Key:      AWS_REGION
Value:    ap-northeast-1Code language: HTTP (http)

Terraform’s AWS provider can consume the environment variable:

provider "aws" {
  # Region may be supplied by AWS_REGION
}Code language: PHP (php)

Important: AWS_REGION does not automatically become var.aws_region. If you want var.aws_region, declare an input variable and provide its value through a Terraform variable or TF_VAR_aws_region.

For AWS authentication, prefer OIDC-based dynamic provider credentials over permanent access keys.

2. All ways to set and pass variable values

You can also create and update workspace variables and variable sets programmatically using the HCP Terraform API or the Terraform tfe provider. These are management methods, not additional precedence levels.

3. Variable scope mapping

Who owns a variable set vs where it applies?

These are separate concepts in modern HCP Terraform.

A project does not have a separate ordinary variable-value layer. Project-wide values are provided through variable sets.

Similarly, Teams and Users manage access permissions; they are not variable scopes.

4. Complete HCP Terraform variable precedence

This is the most important reference table.

Highest priority at the top. The first applicable source with a matching variable type and key wins.

This is the precedence order published in HashiCorp’s current HCP Terraform documentation. It also explains why ownership and Priority status can matter more than the apparent specificity of the scope.

The table focuses on HCP Terraform’s published tiers. Terraform also supports the JSON variants *.auto.tfvars.json and terraform.tfvars.json; their ordering follows Terraform’s normal variable-file rules.

Five rules worth memorizing

• A workspace variable overrides normal, non-priority variable sets.
• Run-specific CLI values override workspace variables, unless a matching Priority Variable Set takes precedence.
• A Priority Global Variable Set has the highest precedence.
• Within otherwise equal variable sets, the set whose name sorts first lexically wins. For example, A-settings wins over B-settings.
• Two global variable sets cannot define conflicting variables of the same key and type.

Unlike the normal non-priority case, an organization-owned priority set can outrank a project-owned priority set, as shown in the ranking.

5. Interactive precedence example

Suppose node_count is defined at several levels for the same workspace.

The CLI override represents a CLI-driven run. The priority example uses the documented HCP Terraform precedence order.

Example: What happens when values conflict?

The effective value is 6, because the workspace variable overrides the lower-ranked sources.

If you now run:

terraform plan -var="node_count=7"Code language: JavaScript (javascript)

The effective value becomes 7 in a CLI-driven remote run.

But if a Priority Global Variable Set defines node_count = 8, then the effective value becomes 8, even when the CLI specifies 7.

6. Practical examples for each method

Method A — Values in .tfvars files

terraform.tfvars:

node_count = 2
environment = "development"Code language: JavaScript (javascript)

production.auto.tfvars:

node_count = 3
environment = "production"Code language: JavaScript (javascript)

Terraform automatically reads these files when they are included in the configuration. The *.auto.tfvars values have precedence over terraform.tfvars.

A custom file such as production.tfvars must be explicitly supplied using -var-file rather than relying on automatic loading.

Method B — TF_VAR_* in your terminal

export TF_VAR_node_count=4
export TF_VAR_environment="staging"

terraform planCode language: JavaScript (javascript)

With a CLI-driven HCP Terraform remote run, these inputs can override workspace variables and normal variable sets. They do not replace the provider credentials and other execution-environment settings required in HCP Terraform.

HashiCorp Developer

Method C — Complex values through Workspace Variables

Terraform code:

variable "subnet_ids" {
  type = list(string)
}Code language: PHP (php)

HCP Terraform UI:

Category: Terraform
Key: subnet_ids

Value:
["subnet-abc123", "subnet-def456"]

HCL: EnabledCode language: CSS (css)

For lists, maps and objects, enable the HCL checkbox when entering HCL expressions in the HCP Terraform UI.

HashiCorp Developer

Method D — Set variables through the HCP Terraform Runs API

The Runs API also supports run-specific values. For example, a run creation payload may include:

{
  "data": {
    "type": "runs",
    "attributes": {
      "variables": [
        {
          "key": "node_count",
          "value": "5"
        }
      ]
    },
    "relationships": {
      "workspace": {
        "data": {
          "type": "workspaces",
          "id": "ws-EXAMPLE"
        }
      }
    }
  }
}Code language: JSON / JSON with Comments (json)

These are supplied to a particular run, rather than permanently updating the workspace. Values must be valid HCL literals. This is useful for CI/CD orchestration and automation.

HashiCorp Developer

Method E — Manage HCP Terraform variables using Terraform

You can manage the platform’s variable configuration through the official hashicorp/tfe provider:

resource "tfe_variable" "example" {
  workspace_id = tfe_workspace.example.id

  key      = "instance_type"
  value    = "t3.medium"
  category = "terraform"
}Code language: JavaScript (javascript)

This creates a workspace Terraform variable with the normal workspace-variable precedence. The tfe_variable_set, tfe_project_variable_set, and tfe_workspace_variable_set resources support reusable sets and their assignments.

Terraform Registry

+1

7. Critical difference: Execution mode and workflow

The HCP Terraform execution model affects which sources are available.

HashiCorp Developer

+2

The Local execution mode exception is especially important. Even though Terraform state is stored in HCP Terraform, HCP Terraform does not evaluate its workspace variables or variable sets for local execution.

Likewise, in CLI-driven remote runs, shell variables on your laptop such as AWS_ACCESS_KEY_ID are not automatically forwarded as remote provider credentials. Configure the execution environment in HCP Terraform or use dynamic authentication.

8. Recommended variable design for AWS infrastructure

For a real infrastructure project, I recommend separating shared configuration, environment-specific settings and authentication.

For AWS dynamic credentials, configure the HCP Terraform OIDC integration and required environment variables such as:

TFC_AWS_PROVIDER_AUTH = true

TFC_AWS_RUN_ROLE_ARN =
arn:aws:iam::123456789012:role/terraform-roleCode language: JavaScript (javascript)

These values configure HCP Terraform authentication rather than declaring application-level input variables.

HashiCorp Developer

9. Other ways values reach Terraform code

Not every value used by Terraform comes from input variables.

Child-module inputs are passed explicitly from the root module:

module "vpc" {
  source = "./modules/vpc"

  cidr = var.vpc_cidr
}Code language: JavaScript (javascript)

Workspace outputs can provide values to another workspace through provider data sources or tfe_outputs:

data "tfe_outputs" "network" {
  organization = "my-org"
  workspace    = "network-prod"
}

output "vpc_id_from_network" {
  value = data.tfe_outputs.network.nonsensitive_values.vpc_id
}Code language: JavaScript (javascript)

These fetched values are resolved through data sources and do not participate in the input-variable precedence table.

Terraform Registry

+1

For Terraform Stacks, variable sets work differently: Stacks reference selected sets explicitly through store blocks, rather than using the workspace precedence hierarchy.

HashiCorp Developer

10. Best practices and common pitfalls

• Prefer variable sets for shared values and workspace variables for environment-specific values.
• Avoid duplicate keys across multiple non-priority sets unless overriding them is intentional.
• Use Priority Variable Sets selectively, because they can prevent workspace teams from overriding values.
• Do not place secrets in committed .tfvars files.
• Mark sensitive HCP Terraform values appropriately, while remembering that Sensitive does not guarantee secrets stay out of Terraform state.
• Use dynamic provider credentials rather than persistent AWS access keys.
• Check the workspace Variables page for OVERWRITTEN markers when debugging conflicts.
• Treat changing a widely shared variable set as a potentially multi-workspace infrastructure change.

HashiCorp Developer

+1

Final reference: Which source should I use?

The overall rule is that scope determines where a variable applies, while precedence determines which value wins. Ownership and Priority settings are the two HCP Terraform-specific details that make this different from ordinary local Terraform.

Official documentation: HCP Terraform Variables & Precedence, Manage Variables and Variable Sets, and Terraform Input Variable Precedence.

Rajesh Kumar

I’m Rajesh Kumar, a DevOps, SRE, DevSecOps, Cloud, and Platform Engineering expert passionate about sharing practical knowledge, real-world experiences, and industry best practices. I have worked at Cotocus and regularly write about technology, travel, investing, health, product reviews, and digital marketing through my various platforms.

I publish technical articles at DevOps School, travel stories at Holiday Landmark, stock market insights at Stocks Mantra, health and fitness guidance at My Medic Plus, product reviews at TrueReviewNow, and SEO and digital marketing strategies at Wizbrand.