HCP Terraform / Enterprise Operations · Topic 2 of 3

Multiple Environments and Version Upgrades

Terraform Professional (002): separate environments with workspaces and projects, resolve variable precedence, and upgrade Terraform across workspaces.

  • 5 min
  • Includes a diagram
In a nutshell
  • Priority sets beat everything, including -var.
  • Workspace-specific variables beat ordinary variable sets.
  • *.auto.tfvars beats terraform.tfvars, and both sit below variable sets.

What it is

In HCP Terraform, each workspace has one set of inputs and one state file, so a workspace per environment gives strict separation. Projects group those workspaces for permissions and shared settings, and variable sets supply values at the right level.

Each workspace also selects its own Terraform version, so upgrades happen one workspace at a time, in a safe order.

How it works

Laying out environments

ApproachHow it worksTrade-off
One branch, variables differAll workspaces track main; values differ per workspaceSimple; a merge reaches every environment
One branch per environmentEach workspace tracks a long-lived branchClear promotion; branches can drift apart
Separate configurations, shared modulesEach environment has its own directoryMost isolated; test new module versions in staging first

In a monorepo, set a working directory on each workspace, and add shared module directories to its automatic run triggering. A CLI-driven configuration can select workspaces by tags and project.

terraform {
  cloud {
    organization = "acme"
    workspaces {
      project = "payments"
      tags    = { layer = "app" }
    }
  }
}

Projects

Every workspace belongs to exactly one project, and new workspaces land in the Default Project unless you choose otherwise. A project gives a team scoped access, and a project-scoped variable set or policy set reaches all its current and future workspaces.

Workspaces do not share state automatically: grant access with remote state sharing, and only between workspaces that need it.

Use terraform_remote_state to read outputs, and a run trigger to queue a dependent workspace after a successful apply. Whether that run applies by itself follows the separate auto-apply setting for run triggers.

Variable precedence

For one variable, the highest source that sets it wins.

RankSource
1Priority variable sets: global, then organization-owned, then project-owned
2Command line -var or -var-file (CLI workflow)
3Local TF_VAR_ variables (CLI workflow)
4Workspace-specific variables
5Project-owned variable sets: workspace-scoped, then project-scoped
6Organization-owned variable sets: workspace-scoped, then project-scoped
7Global variable sets
8*.auto.tfvars files
9terraform.tfvars file

When sets share scope and ownership, the set whose name sorts first wins.

Trace this example for region in a CLI-driven run.

SourceValue
terraform.tfvarsus-east-1
Global setus-east-2
Project-scoped setus-west-1
Workspace variableeu-west-1
-var flageu-central-1
  1. With all of these, -var wins: eu-central-1.
  2. Without the flag, the workspace variable wins: eu-west-1.
  3. Without that too, the project-scoped set beats the global set: us-west-1.
  4. If the global set is marked priority, it beats everything: us-east-2.

Terraform Enterprise ignores terraform.tfvars. Use a priority set for a value teams must not change.

Upgrading Terraform across workspaces

A workspace uses the version set in its settings, an exact version or a constraint, and changing it needs workspace admin access. New workspaces start on the release current at creation, so a workspace set to an exact version stays there until you change it.

Find old versionsExplorerUpdate required_versionon a branchspeculative planCheck for changesSet workspace versionRun and applystate updates
  1. Survey. Use the Explorer's Terraform Versions view, and read the upgrade guide for the new version.
  2. Update required_version. Every constraint in the module tree must allow the new version, or the run fails.
  3. Test with a speculative plan. It can use a different version from the workspace, so you can test without changing settings. Look for a plan with no unexpected changes.
  4. Change the workspace version and merge.
  5. Apply. The next apply writes state with the new version. Merging alone does not update the state file.

An Allow empty apply run applies a plan with no infrastructure changes, so state can be upgraded when a version requires it, most notably 0.13.

Order across workspaces

Workspace B reads workspace A's outputs with terraform_remote_state, so upgrade B first, then A, whose next apply writes newer state. A CLI that does not support a state file format fails with a request to upgrade, and downgrades are not guaranteed. If workspace B reads workspace A's state through terraform_remote_state, the safer order is to upgrade B before A, so B can still read A's newer state.

Upgrade lower environments first, and roll out to production only after checking results. To change many workspaces consistently, manage the terraform_version argument on tfe_workspace resources with the tfe provider.

How the exam asks about this

  • "Test a new Terraform version without changing the workspace." Run a speculative plan with the new version.
  • "A workspace variable and a global set define the same key." The workspace variable wins, unless the set is a priority set.
  • "After the merge, state still shows the old version." The state updates only when an apply runs, using allow empty apply if there are no changes.

What to remember for the exam

  • Priority sets beat everything, including -var.
  • Workspace-specific variables beat ordinary variable sets.
  • *.auto.tfvars beats terraform.tfvars, and both sit below variable sets.
  • Every required_version in the root and its modules must be satisfied.
  • Speculative plans can use a different Terraform version from the workspace.
  • A workspace belongs to exactly one project.
Watch out

Plan to upgrade the workspaces that read a state before the workspace that writes it. Once newer state is written, an older reader is not guaranteed to read it.

Common mistakes

Expecting terraform.tfvars to override a workspace variable. It has the lowest precedence, and Terraform Enterprise ignores it entirely. Set the value in the workspace.

Stopping after changing the version setting. The state file keeps its old version until an apply writes it. Plan for that final step.

Sharing state with the whole organization. It is convenient but gives every workspace read access to outputs. Share only with the workspaces that need it.

Check yourself

  • Which wins, a -var flag or a priority global variable set?

    The priority global variable set, because priority sets rank above command line values.

  • How do you test a new Terraform version without changing a workspace?

    Run a speculative plan with the new version, which can differ from the workspace's selected version and cannot be applied.

  • What updates the state file's Terraform version?

    An apply using the new version, which may need an allow empty apply run if the plan has no changes.

Topic 2 of 3 in HCP Terraform / Enterprise Operations

Test yourself on HCP Terraform / Enterprise Operations

The full HashiCorp Terraform Infrastructure Engineer Professional question bank has 600 questions, with timed practice exams and an explanation for every answer.

This study guide is independent and is not affiliated with, endorsed by, or sponsored by HashiCorp. Vendor names, certification names and exam codes are trademarks of their respective owners and are used for identification only.