HCP Terraform · Topic 2 of 2
HCP Terraform Workspaces, Projects and Governance
Terraform Associate 004: HCP Terraform workspaces and projects, team permissions, variable sets, Sentinel and OPA policies, run tasks and drift checks.
- 5 min
- A workspace holds configuration, state, variables, run history and permissions; a project groups workspaces.
- HCP Terraform workspaces are far more than CLI workspaces, which separate only state.
- Fixed workspace permission sets are read, plan, write and admin; access can be granted per project.
What it is
In HCP Terraform, a workspace is the unit of work: one configuration with its own state, variables, run history and permissions. A project groups related workspaces inside an organization so you can grant access and apply settings to them together.
Around that structure sit the collaboration and governance features: teams and permissions, variable sets, policy enforcement with Sentinel or OPA, run tasks, health assessments and a private registry.
How it works
Workspaces
An HCP Terraform workspace holds everything Terraform needs to manage one collection of infrastructure.
| A workspace has | Purpose |
|---|---|
| Configuration | From a VCS repository, the CLI or an API upload |
| State | Current state plus earlier state versions |
| Variables | Terraform and environment variables, optionally sensitive |
| Run history | Every plan and apply, with logs |
| Settings and permissions | Execution mode, auto apply, team access |
A common pattern is one workspace per component and environment, such as network-prod and network-dev, so each has its own state and access rules.
HCP Terraform workspaces versus CLI workspaces
| HCP Terraform workspace | CLI workspace (terraform workspace) | |
|---|---|---|
| What it separates | Configuration, state, variables, runs and permissions | Only the state, for one configuration in one backend |
| Access control | Per team and permission set | None of its own |
| Created with | The UI, API or cloud block | terraform workspace new |
The same word means much more in HCP Terraform. Exam options that treat them as the same thing are usually wrong.
Projects
Every workspace belongs to exactly one project, and each organization starts with a default project. Projects let you grant a team access to all workspaces in the project at once, and you can scope variable sets and policy sets to a project. The cloud block selects one with workspaces { project = "..." }.
Teams and permissions
Users belong to teams, and teams get permissions. Every organization has an owners team with full control.
| Workspace permission set | Allows |
|---|---|
| Read | View runs, variables and state |
| Plan | Read, plus queue plans |
| Write | Plan, plus apply runs, edit variables, write state, lock and unlock |
| Admin | Write, plus workspace settings, team access and deleting the workspace |
Permissions can be granted on a single workspace or on a whole project, and custom permission sets are available when the fixed sets do not fit.
Variable sets
A variable set is a reusable group of variables, such as cloud credentials, applied to many workspaces. A set can apply to the whole organization (global), to chosen projects or to chosen workspaces. A workspace variable with the same key overrides a variable set value, unless the set is marked as a priority set.
Sensitive variables are write only: they can be used in runs but not read back in the UI or API. When two variable sets of the same scope set the same key, the set whose name sorts first alphabetically wins, and project or workspace scoped sets override global ones.
Policies, run tasks and health
| Feature | What it does |
|---|---|
| Sentinel policies | Policy as code checked against each plan; advisory, soft mandatory or hard mandatory |
| OPA policies | Rego policies checked against each plan; advisory or mandatory |
| Policy sets | Groups of policies applied globally, to projects or to workspaces |
| Run tasks | Call third party tools, such as security scanners, during a run |
| Health assessments | Drift detection and continuous validation of checks and conditions |
| Dynamic provider credentials | Short lived cloud credentials through OIDC instead of stored keys |
| Private registry | Share modules and providers only inside the organization |
| Change requests | Backlog items, often raised from explorer results, recorded on chosen workspaces |
A soft mandatory Sentinel failure stops the run unless someone with permission overrides it; a hard mandatory failure cannot be overridden. Health assessments run on a schedule and report drift without changing any resource. The explorer gives an organization wide view of workspaces, modules, providers and Terraform versions.
How the exam asks about this
- "Every workspace in the team's area must share AWS credentials without copying them." Create a variable set scoped to the project.
- "A policy failure should block the run, but a manager may approve an exception." Use a soft mandatory Sentinel policy.
- "You need to know when someone changes a resource in the console." Enable health assessments for drift detection.
What to remember for the exam
- A workspace holds configuration, state, variables, run history and permissions; a project groups workspaces.
- HCP Terraform workspaces are far more than CLI workspaces, which separate only state.
- Fixed workspace permission sets are read, plan, write and admin; access can be granted per project.
- Variable sets apply globally, to projects or to workspaces; sensitive variables are write only.
- Sentinel levels are advisory, soft mandatory and hard mandatory; OPA levels are advisory and mandatory.
- Health assessments detect drift and run continuous validation without changing infrastructure.
Policies check the plan before apply; they do not inspect live infrastructure. Drift made outside Terraform is found by health assessments, not by policy checks.
Common mistakes
Confusing the two kinds of workspace. Running terraform workspace new does not create an HCP Terraform workspace with its own variables and permissions. In HCP Terraform, workspaces are created in the UI, the API or through the cloud block.
Putting credentials in every workspace. Copying secrets into each workspace is hard to rotate. A variable set or dynamic provider credentials keep them in one place or remove them entirely.
Thinking advisory policies block runs. An advisory failure only warns. Use soft mandatory or hard mandatory in Sentinel, or mandatory in OPA, to stop a run.
Check yourself
What is the main purpose of an HCP Terraform project?
To group related workspaces so teams get access and settings such as variable sets and policy sets across all of them at once.
Which Sentinel enforcement level stops a run but allows an authorized override?
Soft mandatory. Advisory only warns, and hard mandatory stops the run with no override.
How does an HCP Terraform workspace differ from a CLI workspace?
It holds its own configuration, state, variables, run history and team permissions, while a CLI workspace only separates state for one configuration.
Topic 2 of 2 in HCP Terraform
Test yourself on HCP Terraform
The full HashiCorp Terraform Associate 004 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.