{"id":79385,"date":"2026-10-15T09:29:28","date_gmt":"2026-10-15T09:29:28","guid":{"rendered":"https:\/\/www.devopsschool.com\/blog\/?p=79385"},"modified":"2026-10-15T10:19:01","modified_gmt":"2026-10-15T10:19:01","slug":"hcp-terraform-terraform-cloud-complete-guide-to-variables-scope-precedence","status":"publish","type":"post","link":"https:\/\/www.devopsschool.com\/blog\/hcp-terraform-terraform-cloud-complete-guide-to-variables-scope-precedence\/","title":{"rendered":"HCP Terraform (Terraform Cloud) \u2014 Complete Guide to Variables, Scope & Precedence"},"content":{"rendered":"\n
\"\"<\/a><\/figure>\n\n\n\n

Updated: October 2026 | Based on current HashiCorp documentation<\/p>\n\n\n\n

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

The three most important things to understand are:<\/p>\n\n\n\n

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

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

    1. Two types of variables in HCP Terraform<\/h2>\n\n\n\n
    Feature<\/th>Terraform variable<\/th>Environment variable<\/th><\/tr>
    Purpose<\/td>Configure Terraform resources and modules<\/td>Configure providers, authentication and Terraform execution<\/td><\/tr>
    Example<\/td>instance_type<\/code><\/td>AWS_REGION<\/code><\/td><\/tr>
    Access in .tf<\/code> code<\/td>var.instance_type<\/code><\/td>Usually through provider or Terraform process behavior<\/td><\/tr>
    Workspace UI category<\/td>Terraform Variable<\/td>Environment Variable<\/td><\/tr>
    Supports HCL checkbox<\/td>Yes<\/td>No<\/td><\/tr>
    Supports Sensitive flag<\/td>Yes<\/td>Yes<\/td><\/tr>
    Can be in variable sets<\/td>Yes<\/td>Yes<\/td><\/tr><\/tbody><\/table><\/figure>\n\n\n\n

    Example A: Terraform input variable<\/h3>\n\n\n\n

    In variables.tf<\/code>:<\/p>\n\n\n

    variable \"instance_type\"<\/span> {\n  description = \"EC2 instance type\"<\/span>\n  type        = string\n  default<\/span>     = \"t3.micro\"<\/span>\n}<\/code><\/span>Code language:<\/span> JavaScript<\/span> (<\/span>javascript<\/span>)<\/span><\/small><\/pre>\n\n\n
    In HCP Terraform, configure:<\/p>\n\n\n
    Category<\/span>: Terraform variable\nKey<\/span>:      instance_type\nValue<\/span>:    t3.medium<\/code><\/span>Code language:<\/span> HTTP<\/span> (<\/span>http<\/span>)<\/span><\/small><\/pre>\n\n\n
    And access it in code:<\/p>\n\n\n
    resource \"aws_instance\"<\/span> \"example\"<\/span> {\n  ami           = var<\/span>.ami_id\n  instance_type = var<\/span>.instance_type\n}<\/code><\/span>Code language:<\/span> JavaScript<\/span> (<\/span>javascript<\/span>)<\/span><\/small><\/pre>\n\n\n
    Terraform uses t3.medium<\/code>, overriding the default t3.micro<\/code>.<\/p>\n\n\n\n
    Example B: Environment variable<\/h3>\n\n\n\n
    In HCP Terraform:<\/p>\n\n\n
    Category<\/span>: Environment variable\nKey<\/span>:      AWS_REGION\nValue<\/span>:    ap-northeast-1<\/code><\/span>Code language:<\/span> HTTP<\/span> (<\/span>http<\/span>)<\/span><\/small><\/pre>\n\n\n
    Terraform’s AWS provider can consume the environment variable:<\/p>\n\n\n
    provider \"aws\"<\/span> {\n  # Region may be supplied by AWS_REGION<\/span>\n}<\/code><\/span>Code language:<\/span> PHP<\/span> (<\/span>php<\/span>)<\/span><\/small><\/pre>\n\n\n
    Important: AWS_REGION<\/code> does not automatically become var.aws_region<\/code>. If you want var.aws_region<\/code>, declare an input variable and provide its value through a Terraform variable or TF_VAR_aws_region<\/code>.<\/p>\n\n\n\n
    For AWS authentication, prefer OIDC-based dynamic provider credentials over permanent access keys.<\/p>\n\n\n\n
    2. All ways to set and pass variable values<\/h2>\n\n\n\n
    Method<\/th>Where defined<\/th>Scope<\/th>Example<\/th><\/tr>
    Default value<\/td>variables.tf<\/code><\/td>Terraform configuration<\/td>default = \"t3.micro\"<\/code><\/td><\/tr>
    terraform.tfvars<\/code><\/td>Repository \/ configuration directory<\/td>Configuration<\/td>instance_type = \"t3.small\"<\/code><\/td><\/tr>
    *.auto.tfvars<\/code><\/td>Repository \/ configuration directory<\/td>Configuration<\/td>instance_type = \"t3.medium\"<\/code><\/td><\/tr>
    *.tfvars.json<\/code><\/td>Repository \/ configuration directory<\/td>Configuration<\/td>JSON-formatted inputs<\/td><\/tr>
    TF_VAR_*<\/code><\/td>Shell environment<\/td>Current process \/ run<\/td>TF_VAR_instance_type<\/code><\/td><\/tr>
    CLI -var<\/code><\/td>Terraform command<\/td>Single run<\/td>-var=\"instance_type=t3.large\"<\/code><\/td><\/tr>
    CLI -var-file<\/code><\/td>Terraform command<\/td>Single run<\/td>-var-file=prod.tfvars<\/code><\/td><\/tr>
    Workspace variable<\/td>HCP Terraform UI\/API<\/td>One workspace<\/td>instance_type = t3.xlarge<\/code><\/td><\/tr>
    Workspace-scoped variable set<\/td>HCP Terraform<\/td>Selected workspaces<\/td>Shared configuration<\/td><\/tr>
    Project-scoped variable set<\/td>HCP Terraform<\/td>All workspaces in project<\/td>Shared project settings<\/td><\/tr>
    Global variable set<\/td>HCP Terraform<\/td>All organization workspaces<\/td>Organization defaults<\/td><\/tr>
    Priority variable set<\/td>HCP Terraform<\/td>Selected scope, enforced precedence<\/td>Protected configuration<\/td><\/tr><\/tbody><\/table><\/figure>\n\n\n\n
    You can also create and update workspace variables and variable sets programmatically using the HCP Terraform API or the Terraform tfe<\/code> provider. These are management methods, not additional precedence levels.<\/p>\n\n\n\n
    3. Variable scope mapping<\/h2>\n\n\n\n
    \"\"<\/figure>\n\n\n\n
    Who owns a variable set vs where it applies?<\/h3>\n\n\n\n
    These are separate concepts in modern HCP Terraform.<\/p>\n\n\n\n
    Ownership<\/th>Assignment scope<\/th>Effect<\/th><\/tr>
    Organization-owned<\/td>Global<\/td>Every workspace in the organization<\/td><\/tr>
    Organization-owned<\/td>Specific projects<\/td>All workspaces in selected projects<\/td><\/tr>
    Organization-owned<\/td>Specific workspaces<\/td>Only selected workspaces<\/td><\/tr>
    Project-owned<\/td>Entire project<\/td>All workspaces in that project<\/td><\/tr>
    Project-owned<\/td>Specific workspaces<\/td>Only selected workspaces within that project<\/td><\/tr><\/tbody><\/table><\/figure>\n\n\n\n
    A project does not have a separate ordinary variable-value layer. Project-wide values are provided through variable sets.<\/p>\n\n\n\n
    Similarly, Teams and Users manage access permissions; they are not variable scopes.<\/p>\n\n\n\n
    4. Complete HCP Terraform variable precedence<\/h2>\n\n\n\n
    This is the most important reference table.<\/p>\n\n\n\n
    Highest priority at the top. The first applicable source with a matching variable type and key wins.<\/p>\n\n\n\n
    Rank<\/th>Variable source<\/th>Priority enabled<\/th><\/tr>
    1<\/td>Global variable set<\/td>Yes<\/td><\/tr>
    2<\/td>Organization-owned, project-scoped variable set<\/td>Yes<\/td><\/tr>
    3<\/td>Organization-owned, workspace-scoped variable set<\/td>Yes<\/td><\/tr>
    4<\/td>Project-owned, project-scoped variable set<\/td>Yes<\/td><\/tr>
    5<\/td>Project-owned, workspace-scoped variable set<\/td>Yes<\/td><\/tr>
    6<\/td>CLI -var<\/code> \/ -var-file<\/code><\/td>N\/A<\/td><\/tr>
    7<\/td>Local TF_VAR_*<\/code> for CLI-driven remote runs<\/td>N\/A<\/td><\/tr>
    8<\/td>Workspace-specific variable<\/td>N\/A<\/td><\/tr>
    9<\/td>Project-owned, workspace-scoped variable set<\/td>No<\/td><\/tr>
    10<\/td>Project-owned, project-scoped variable set<\/td>No<\/td><\/tr>
    11<\/td>Organization-owned, workspace-scoped variable set<\/td>No<\/td><\/tr>
    12<\/td>Organization-owned, project-scoped variable set<\/td>No<\/td><\/tr>
    13<\/td>Global variable set<\/td>No<\/td><\/tr>
    14<\/td>*.auto.tfvars<\/code> files<\/td>N\/A<\/td><\/tr>
    15<\/td>terraform.tfvars<\/code><\/td>N\/A<\/td><\/tr>
    \u2014<\/td>Terraform input variable default<\/code><\/td>Lowest fallback<\/td><\/tr><\/tbody><\/table><\/figure>\n\n\n\n
    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.<\/p>\n\n\n\n
    The table focuses on HCP Terraform’s published tiers. Terraform also supports the JSON variants *.auto.tfvars.json<\/code> and terraform.tfvars.json<\/code>; their ordering follows Terraform’s normal variable-file rules.<\/p>\n\n\n\n
    Five rules worth memorizing<\/h3>\n\n\n\n
      \n
    • A workspace variable overrides normal, non-priority variable sets.<\/li>\n\n\n\n
    • Run-specific CLI values override workspace variables, unless a matching Priority Variable Set takes precedence.<\/li>\n\n\n\n
    • A Priority Global Variable Set has the highest precedence.<\/li>\n\n\n\n
    • Within otherwise equal variable sets, the set whose name sorts first lexically wins. For example, A-settings<\/code> wins over B-settings<\/code>.<\/li>\n\n\n\n
    • Two global variable sets cannot define conflicting variables of the same key and type.<\/li>\n<\/ul>\n\n\n\n
      Unlike the normal non-priority case, an organization-owned priority set can outrank a project-owned priority set, as shown in the ranking.<\/p>\n\n\n\n
      5. Interactive precedence example<\/h2>\n\n\n\n
      Suppose node_count<\/code> is defined at several levels for the same workspace.<\/p>\n\n\n\n
      \"\"<\/figure>\n\n\n\n
      The CLI override represents a CLI-driven run. The priority example uses the documented HCP Terraform precedence order.<\/p>\n\n\n\n
      Example: What happens when values conflict?<\/h3>\n\n\n\n
      Source<\/th>node_count<\/code><\/th><\/tr>
      variables.tf<\/code> default<\/td>1<\/td><\/tr>
      terraform.tfvars<\/code><\/td>2<\/td><\/tr>
      dev.auto.tfvars<\/code><\/td>3<\/td><\/tr>
      Normal project variable set<\/td>5<\/td><\/tr>
      Workspace variable<\/td>6<\/td><\/tr><\/tbody><\/table><\/figure>\n\n\n\n
      The effective value is 6, because the workspace variable overrides the lower-ranked sources.<\/p>\n\n\n\n
      If you now run:<\/p>\n\n\n
      terraform plan -var<\/span>=\"node_count=7\"<\/span><\/code><\/span>Code language:<\/span> JavaScript<\/span> (<\/span>javascript<\/span>)<\/span><\/small><\/pre>\n\n\n
      The effective value becomes 7 in a CLI-driven remote run.<\/p>\n\n\n\n
      But if a Priority Global Variable Set defines node_count = 8<\/code>, then the effective value becomes 8, even when the CLI specifies 7.<\/p>\n\n\n\n
      6. Practical examples for each method<\/h2>\n\n\n\n
      Method A \u2014 Values in .tfvars<\/code> files<\/h3>\n\n\n\n
      terraform.tfvars<\/code>:<\/p>\n\n\n
      node_count = 2<\/span>\nenvironment = \"development\"<\/span><\/code><\/span>Code language:<\/span> JavaScript<\/span> (<\/span>javascript<\/span>)<\/span><\/small><\/pre>\n\n\n
      production.auto.tfvars<\/code>:<\/p>\n\n\n
      node_count = 3<\/span>\nenvironment = \"production\"<\/span><\/code><\/span>Code language:<\/span> JavaScript<\/span> (<\/span>javascript<\/span>)<\/span><\/small><\/pre>\n\n\n
      Terraform automatically reads these files when they are included in the configuration. The *.auto.tfvars<\/code> values have precedence over terraform.tfvars<\/code>.<\/p>\n\n\n\n
      A custom file such as production.tfvars<\/code> must be explicitly supplied using -var-file<\/code> rather than relying on automatic loading.<\/p>\n\n\n\n
      Method B \u2014 TF_VAR_*<\/code> in your terminal<\/h3>\n\n\n
      export<\/span> TF_VAR_node_count=4<\/span>\nexport<\/span> TF_VAR_environment=\"staging\"<\/span>\n\nterraform plan<\/code><\/span>Code language:<\/span> JavaScript<\/span> (<\/span>javascript<\/span>)<\/span><\/small><\/pre>\n\n\n
      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.<\/p>\n\n\n\n
      \"\"\/<\/figure>\n\n\n\n
      HashiCorp Developer<\/p>\n\n\n\n
      Method C \u2014 Complex values through Workspace Variables<\/h3>\n\n\n\n
      Terraform code:<\/p>\n\n\n
      variable \"subnet_ids\"<\/span> {\n  type = list<\/span>(string)\n}<\/code><\/span>Code language:<\/span> PHP<\/span> (<\/span>php<\/span>)<\/span><\/small><\/pre>\n\n\n
      HCP Terraform UI:<\/p>\n\n\n
      Category<\/span>: Terraform<\/span>\nKey<\/span>: subnet_ids<\/span>\n\nValue<\/span>:\n[\"subnet-abc123\"<\/span>, \"subnet-def456\"<\/span>]<\/span>\n\nHCL<\/span>: Enabled<\/span><\/code><\/span>Code language:<\/span> CSS<\/span> (<\/span>css<\/span>)<\/span><\/small><\/pre>\n\n\n
      For lists, maps and objects, enable the HCL checkbox when entering HCL expressions in the HCP Terraform UI.<\/p>\n\n\n\n
      \"\"\/<\/figure>\n\n\n\n
      HashiCorp Developer<\/p>\n\n\n\n
      Method D \u2014 Set variables through the HCP Terraform Runs API<\/h3>\n\n\n\n
      The Runs API also supports run-specific values. For example, a run creation payload may include:<\/p>\n\n\n
      {\n  \"data\"<\/span>: {\n    \"type\"<\/span>: \"runs\"<\/span>,\n    \"attributes\"<\/span>: {\n      \"variables\"<\/span>: [\n        {\n          \"key\"<\/span>: \"node_count\"<\/span>,\n          \"value\"<\/span>: \"5\"<\/span>\n        }\n      ]\n    },\n    \"relationships\"<\/span>: {\n      \"workspace\"<\/span>: {\n        \"data\"<\/span>: {\n          \"type\"<\/span>: \"workspaces\"<\/span>,\n          \"id\"<\/span>: \"ws-EXAMPLE\"<\/span>\n        }\n      }\n    }\n  }\n}<\/code><\/span>Code language:<\/span> JSON \/ JSON with Comments<\/span> (<\/span>json<\/span>)<\/span><\/small><\/pre>\n\n\n
      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.<\/p>\n\n\n\n
      \"\"\/<\/figure>\n\n\n\n
      HashiCorp Developer<\/p>\n\n\n\n
      Method E \u2014 Manage HCP Terraform variables using Terraform<\/h3>\n\n\n\n
      You can manage the platform’s variable configuration through the official hashicorp\/tfe<\/code> provider:<\/p>\n\n\n
      resource \"tfe_variable\"<\/span> \"example\"<\/span> {\n  workspace_id = tfe_workspace.example.id\n\n  key      = \"instance_type\"<\/span>\n  value    = \"t3.medium\"<\/span>\n  category = \"terraform\"<\/span>\n}<\/code><\/span>Code language:<\/span> JavaScript<\/span> (<\/span>javascript<\/span>)<\/span><\/small><\/pre>\n\n\n
      This creates a workspace Terraform variable with the normal workspace-variable precedence. The tfe_variable_set<\/code>, tfe_project_variable_set<\/code>, and tfe_workspace_variable_set<\/code> resources support reusable sets and their assignments.<\/p>\n\n\n\n
      \"\"\/<\/figure>\n\n\n\n
      Terraform Registry<\/p>\n\n\n\n
      +1<\/p>\n\n\n\n
      7. Critical difference: Execution mode and workflow<\/h2>\n\n\n\n
      The HCP Terraform execution model affects which sources are available.<\/p>\n\n\n\n
      Execution \/ workflow<\/th>Workspace variables<\/th>Variable sets<\/th>Local CLI overrides<\/th><\/tr>
      VCS-driven remote<\/td>Yes<\/td>Yes<\/td>Not supplied by VCS runs<\/td><\/tr>
      UI-triggered remote<\/td>Yes<\/td>Yes<\/td>Not from user’s local shell<\/td><\/tr>
      CLI-driven remote<\/td>Yes<\/td>Yes<\/td>Yes<\/td><\/tr>
      API-driven remote<\/td>Yes<\/td>Yes<\/td>Run-specific API values<\/td><\/tr>
      Agent execution<\/td>Yes<\/td>Yes<\/td>When CLI-driven<\/td><\/tr>
      Local execution mode<\/td>No<\/td>No<\/td>Standard local Terraform precedence<\/td><\/tr><\/tbody><\/table><\/figure>\n\n\n\n
      \"\"\/<\/figure>\n\n\n\n
      HashiCorp Developer<\/p>\n\n\n\n
      +2<\/p>\n\n\n\n
      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.<\/p>\n\n\n\n
      Likewise, in CLI-driven remote runs, shell variables on your laptop such as AWS_ACCESS_KEY_ID<\/code> are not automatically forwarded as remote provider credentials. Configure the execution environment in HCP Terraform or use dynamic authentication.<\/p>\n\n\n\n
      8. Recommended variable design for AWS infrastructure<\/h2>\n\n\n\n
      For a real infrastructure project, I recommend separating shared configuration, environment-specific settings and authentication.<\/p>\n\n\n\n
      Variable<\/th>Type<\/th>Recommended scope<\/th><\/tr>
      default_tags<\/code><\/td>Terraform<\/td>Organization-owned variable set or project set<\/td><\/tr>
      environment<\/code><\/td>Terraform<\/td>Workspace<\/td><\/tr>
      aws_region<\/code><\/td>Terraform<\/td>Project set or workspace<\/td><\/tr>
      vpc_cidr<\/code><\/td>Terraform<\/td>Workspace<\/td><\/tr>
      eks_cluster_name<\/code><\/td>Terraform<\/td>Workspace<\/td><\/tr>
      node_count<\/code><\/td>Terraform<\/td>Workspace<\/td><\/tr>
      TF_LOG<\/code><\/td>Environment<\/td>Workspace, only for debugging<\/td><\/tr>
      TFC_AWS_PROVIDER_AUTH<\/code><\/td>Environment<\/td>Workspace or relevant variable set<\/td><\/tr>
      TFC_AWS_RUN_ROLE_ARN<\/code><\/td>Environment<\/td>Workspace or relevant variable set<\/td><\/tr>
      Database password<\/td>Sensitive Terraform or provider environment variable<\/td>Workspace or restricted variable set<\/td><\/tr><\/tbody><\/table><\/figure>\n\n\n\n
      For AWS dynamic credentials, configure the HCP Terraform OIDC integration and required environment variables such as:<\/p>\n\n\n
      TFC_AWS_PROVIDER_AUTH = true<\/span>\n\nTFC_AWS_RUN_ROLE_ARN =\narn:aws:iam::123456789012<\/span>:role\/terraform-role<\/code><\/span>Code language:<\/span> JavaScript<\/span> (<\/span>javascript<\/span>)<\/span><\/small><\/pre>\n\n\n
      These values configure HCP Terraform authentication rather than declaring application-level input variables.<\/p>\n\n\n\n
      \"\"\/<\/figure>\n\n\n\n
      HashiCorp Developer<\/p>\n\n\n\n
      9. Other ways values reach Terraform code<\/h2>\n\n\n\n
      Not every value used by Terraform comes from input variables.<\/p>\n\n\n\n
      Child-module inputs are passed explicitly from the root module:<\/p>\n\n\n
      module<\/span> \"vpc\"<\/span> {\n  source = \".\/modules\/vpc\"<\/span>\n\n  cidr = var<\/span>.vpc_cidr\n}<\/code><\/span>Code language:<\/span> JavaScript<\/span> (<\/span>javascript<\/span>)<\/span><\/small><\/pre>\n\n\n
      Workspace outputs can provide values to another workspace through provider data sources or tfe_outputs<\/code>:<\/p>\n\n\n
      data \"tfe_outputs\"<\/span> \"network\"<\/span> {\n  organization = \"my-org\"<\/span>\n  workspace    = \"network-prod\"<\/span>\n}\n\noutput \"vpc_id_from_network\"<\/span> {\n  value = data.tfe_outputs.network.nonsensitive_values.vpc_id\n}<\/code><\/span>Code language:<\/span> JavaScript<\/span> (<\/span>javascript<\/span>)<\/span><\/small><\/pre>\n\n\n
      These fetched values are resolved through data sources and do not participate in the input-variable precedence table.<\/p>\n\n\n\n
      \"\"\/<\/figure>\n\n\n\n
      Terraform Registry<\/p>\n\n\n\n
      +1<\/p>\n\n\n\n
      For Terraform Stacks, variable sets work differently: Stacks reference selected sets explicitly through store<\/code> blocks, rather than using the workspace precedence hierarchy.<\/p>\n\n\n\n
      \"\"\/<\/figure>\n\n\n\n
      HashiCorp Developer<\/p>\n\n\n\n
      10. Best practices and common pitfalls<\/h2>\n\n\n\n