HashiCorp Certified: Terraform Associate
HCP Terraform workspaces and execution modes: Terraform Associate
An HCP Terraform workspace holds what Terraform needs for one collection of infrastructure: its state, variables, credentials and run history. Its execution mode decides where runs happen. Remote runs on HCP Terraform's own disposable machines, Local runs on your workstation while HCP Terraform keeps the state, and Agent runs through agents inside your own network.
What a workspace holds
Run locally, Terraform uses a working directory that holds configuration, state and variables. HCP Terraform uses workspaces instead, and separate workspaces act like separate working directories.
The configuration comes from a linked version control repository or is uploaded through the API or CLI. Variable values, state, and credentials (as sensitive variables) are stored in the workspace. HCP Terraform also keeps earlier state versions and a run history with logs and comments.
Workspaces are also a main unit of access control. You grant teams permissions on workspaces, and projects group workspaces so permissions can be granted per project.
HCP Terraform workspaces vs CLI workspaces
The two features share a name but work differently. HCP Terraform workspaces are required: you cannot manage resources in HCP Terraform without at least one.
Terraform CLI workspaces belong to one working directory and keep several state files for the same configuration. They are optional.
Execution modes
Project Default is the default setting: the workspace uses its project's execution mode.
Remote: HCP Terraform runs Terraform on its own disposable virtual machines. This enables features such as Sentinel policy enforcement, cost estimation, notifications and version control integration.
Local: you run Terraform on your workstation with the CLI. The workspace still stores the state. HCP Terraform does not evaluate workspace variables or variable sets in this mode.
Agent: HCP Terraform sends runs to lightweight agents you deploy, so Terraform runs in isolated, private or on-premises networks. The agent needs only outbound connectivity to HCP Terraform. Runs are still managed by HCP Terraform.
If you change the execution mode after a run has been planned, that run errors when it is applied. HashiCorp suggests turning off auto-apply, finishing pending runs, and locking the workspace before you change it.
Other settings worth knowing
Run triggers queue a run in a workspace when a run in a source workspace applies successfully.
Remote state sharing controls which workspaces can read this workspace's state through terraform_remote_state. New workspaces default to sharing with specific workspaces, with an empty list, so no other workspace can read the state until you add one.
The auto-apply setting covers runs from the UI, API and VCS. Runs started from the CLI use -auto-approve instead.
Where the exam catches people
- Believing CLI workspaces and HCP Terraform workspaces are the same thing: CLI workspaces keep several state files for one working directory, while HCP Terraform workspaces hold state, variables and run history and carry team permissions.
- Believing Local execution mode still uses workspace variables: HCP Terraform does not evaluate workspace variables or variable sets in Local mode.
- Believing runs in a private network need Local mode: Agent mode runs them inside your network while HCP Terraform manages them.
- Believing a new workspace's state is readable by every workspace in the organization: by default no other workspace can read it until you add it to the list.
- Believing the workspace auto-apply setting covers CLI runs: CLI runs use
-auto-approve.