Study guide
13.3 Workspaces and Projects
HashiCorp Certified: Terraform Associate 004
Track your progress as you read
Finished sections get a check mark.
1 Introduction & Exam Overview
1.1 Current Exam Facts 1.2 Format, Delivery, Retakes, and Recertification 1.3 004 Changes, Terraform 1.12, and Study Plan
2 Infrastructure as Code with Terraform
2.1 What Infrastructure as Code Is 2.2 Advantages of IaC Patterns 2.3 Multi-Cloud, Hybrid, and Service-Agnostic Workflows
3 Terraform Fundamentals: Providers & State
3.1 Install and Version Terraform Providers 3.2 How Terraform Uses Providers 3.3 Configuration with Multiple Providers 3.4 How Terraform Uses and Manages State
4 Core Terraform Workflow: Init & Validate
4.1 The Terraform Write–Plan–Apply Workflow 4.2 Initialize a Working Directory 4.3 Validate a Configuration
5 Plan, Apply, Destroy, and Formatting
5.1 Generate and Review an Execution Plan 5.2 Apply Changes to Infrastructure 5.3 Destroy Terraform-Managed Infrastructure 5.4 Formatting and Style Adjustments
6 Resources, Data Sources, and References
6.1 Resource Blocks vs Data Blocks 6.2 Resource Attributes and Cross-Resource References 6.3 Resource Addressing and Interpolation Patterns
7 Variables, Outputs, and Complex Types
7.1 Input Variables, tfvars, and Precedence 7.2 Output Values 7.3 Complex Types: list, map, object, tuple, set
8 Dynamic Configuration and Dependencies
8.1 Expressions, count, for_each, and dynamic Blocks 8.2 Built-in Functions 8.3 Dependencies, depends_on, and Lifecycle Rules
9 Conditions, Secrets, and Sensitive Data
9.1 Custom Conditions: validation, precondition, postcondition, check 9.2 Sensitive Data Handling 9.3 Vault, Ephemeral Values, and Write-Only Arguments
10 Terraform Modules
10.1 How Terraform Sources Modules 10.2 Variable Scope within Modules 10.3 Using Modules in Configuration 10.4 Managing Module Versions
11 Terraform State Management
11.1 The Local Backend 11.2 State Locking 11.3 Remote State and the backend Block 11.4 Resource Drift and State Operations
12 Maintain Infrastructure with Terraform
12.1 Import Existing Infrastructure 12.2 Inspect State with the CLI 12.3 Verbose Logging and Diagnostics
13 HCP Terraform
13.1 Create Infrastructure with HCP Terraform 13.2 Collaboration and Governance Features 13.3 Workspaces and Projects 13.4 HCP Terraform Integrations
13.3 Workspaces and Projects
Key Takeaways Explain This Topic AI
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
Last updated: August 2026
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 workspace on 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 staging keeps 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.
Loading diagram...
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.