13.3 Workspaces and Projects
Key Takeaways
- An HCP Terraform workspace is the collection of configuration, state, variables, and run history for one root module — one workspace, one state
- CLI terraform workspace only isolates extra state files inside one working directory; it is not an HCP workspace and is not required
- Projects are folders of workspaces (and Stacks) used to grant team access to a group instead of to every workspace or the whole organization
- HCP variables are Terraform or environment; Terraform values may be parsed as HCL; sensitive values are write-only after save
- Execution mode (Project Default, Remote, Local, Agent) and settings such as auto-apply, Terraform version, working directory, and remote-state sharing are per workspace
13.3 Workspaces and Projects
Quick Answer: An HCP Terraform workspace holds one root module's configuration, state, variables, and run history. One workspace = one state. A project is a folder of workspaces used for access control.
terraform workspaceon the CLI is a different feature that juggles extra state files in one directory. Do not treat those names as synonyms.
Objective 8c is new on the 004 blueprint. Official references: Workspaces, Manage projects, Workspace settings, and Variables.
What lives in an HCP workspace
When you run Community Terraform, a persistent working directory is the unit of management: .tf files, terraform.tfstate, and whatever variables you pass. HCP Terraform replaces that directory with a workspace:
| Component | Local working directory | HCP Terraform workspace |
|---|---|---|
| Configuration | Files on disk | Linked VCS repo, or uploads from CLI/API (configuration versions) |
| Variables | .tfvars, -var, shell env | Stored on the workspace (and variable sets) |
| State | Local file or a backend you configured | Stored in that workspace, with prior state versions |
| Credentials | Shell or prompts | Workspace environment variables, often marked sensitive |
| History | Your terminal scrollback | Run history (summaries, logs, who started it, comments) |
The workspace header also shows a resource count from state (managed resources and data sources). You create workspaces in the UI, with the Workspaces API, or implicitly via the CLI integration when terraform init sees a cloud block name that does not exist yet.
HashiCorp's planning advice: split monoliths. networking-prod, app-prod, and monitoring-prod can move in parallel and reuse the same module in *-dev. Each of those is its own workspace with its own state. You do not get three states by running terraform workspace new inside one HCP workspace.
Not the same as terraform workspace
This is the 8c trap.
- HCP workspaces are required. They are how the organization inventories infrastructure. They are a unit of RBAC. No workspace, no managed resources in HCP Terraform.
- CLI workspaces are optional.
terraform workspace new stagingkeeps additional state files beside the default one in a single configuration directory. Community Terraform never forces you to create them.
Migrating CLI workspaces into HCP is why terraform init may ask you to rename them. HCP names must be unique in the organization. A common pattern is <component>-<environment>-<region>. After you leave backend "remote" prefix behind, you select the full HCP name (terraform workspace select networking-prod), not the short suffix.
flowchart TD
Org["HCP organization"] --> P1["Project: platform"]
Org --> P2["Project: app-team"]
P1 --> W1["Workspace net-prod\n1 state"]
P1 --> W2["Workspace net-dev\n1 state"]
P2 --> W3["Workspace app-prod\n1 state"]
CLI["CLI terraform workspace\noptional extra state files\nin one directory"] -.->|"not the same object"| W1
Projects
A project is a folder that contains workspaces (and, in current HCP Terraform, Stacks). Every organization has at least a default project. You create more from Projects → + New project. Names are unique in the organization and may include letters, numbers, inner spaces, hyphens, and underscores.
Why projects exist: grant a team access to this collection instead of org-wide "manage all workspaces" or a hundred per-workspace grants. Official docs: organizations on Essentials, Standard, and Premium can assign project permissions for that scoping. Moving a workspace to another project can change who can see it; you need manage-all-projects or admin on both source and destination.
You can tag projects (key/value). Workspaces created in the project inherit those tags. HashiCorp documents a cap of 10 tags on a project and 10 on a workspace (up to 20 on a workspace when you count both). You cannot delete a project that still contains workspaces or Stacks.
Projects can also set a default execution mode and, on Standard/Premium, ephemeral / auto-destroy behavior for inactive workspaces. Auto-destroy is for non-prod; the UI will not ask a human to approve those destroy plans.
Variables: Terraform, environment, HCL, sensitive
HCP variables are how a remote run gets input without baking secrets into Git.
| Kind | What it is | Typical use |
|---|---|---|
| Terraform variable | An input variable (variable "name" in HCL) | instance_count, CIDR, environment name |
| Environment variable | Exported into the POSIX shell on the runner | Provider credentials (AWS_…), TF_LOG, TFE_PARALLELISM |
| HCL (checkbox on Terraform variables only) | Parse the value as HCL, not a raw string | Lists, maps, objects: ["a","b"] or { key = "val" } |
| Sensitive | Write-only after save; redacted in the UI and logs | Tokens, passwords, private keys |
If a required Terraform variable has no value, the plan fails and the log says why. Sensitive values cannot be read back, even by admins — you overwrite them. Marking a value sensitive is not the same as a sensitive = true argument on an output; it is an HCP storage flag.
Scope (coarser to finer, before priority flags): global variable sets, project-scoped sets, workspace-scoped sets, workspace-specific variables, then (CLI workflow) TF_VAR_* and -var / -var-file. Priority / prioritized sets can break that order — know that the UI marks overwritten keys rather than memorizing every row of the precedence table. Variable sets are how you share a standard AWS role or a common tag map. Local execution mode does not evaluate workspace variables or variable sets; you must supply them locally.
Execution modes and other settings
Workspace General settings (admin):
- Execution mode: Project Default, Remote (custom), Local (custom), Agent (custom). Changing mode mid-flight after a plan will error the apply; HashiCorp's sequence is: disable auto-apply, finish in-flight runs, lock, change mode, restore auto-apply, unlock.
- Auto-apply versus manual apply.
- Terraform version (or a version constraint). Defaults to whatever release was current when the workspace was created — pin it for 1.12 exam realism.
- Working directory relative to the repo root. In VCS workspaces this also becomes the default path filter for automatic runs.
- Remote state sharing: organization, project, or named workspaces. Default for new workspaces is named + empty.
- User interface: Structured Run Output (default, Terraform ≥ 1.0.5) versus streaming Console UI.
Other settings pages: Health (drift detection and continuous validation — Standard / Premium), Locking, Notifications, Policies, Run Triggers, SSH key (for Git-based modules), Team access, Version control, Destruction and deletion.
Health assessments are not Free-tier features. Do not list drift detection as something every Free workspace has.
Scenario: two "staging" states
Devon used Community workspaces: one directory, terraform workspace select staging. After adding a cloud block with workspaces.name = "app", they expect HCP to keep a hidden staging snapshot. It will not. HCP app is one state. The fix is a second HCP workspace (app-staging) in the app-team project, same repo, different working directory or branch, different variables. That is 8c: organize with HCP workspaces and projects, not CLI workspace names.
004 traps for objective 8c
- HCP workspace ≠
terraform workspace. - One HCP workspace, one state. Split environments by creating more HCP workspaces.
- Projects are access-control folders, not extra state files.
- Terraform variable vs environment variable vs HCL parse vs sensitive are four different checkboxes/concepts.
- Local execution ignores HCP variable values.
- Do not assign Standard/Premium-only health assessments or ephemeral destroy to Free.
A teammate says they created a second environment by running terraform workspace new staging inside a directory that already uses a cloud block pointed at HCP workspace app-prod. What should you tell them on the 004 exam?
Which statement about HCP Terraform state is correct?
A workspace execution mode is set to Local. An engineer added AWS keys as a sensitive environment variable on the workspace Variables page. What happens on the next CLI apply?