What does an HCP Terraform workspace hold, and how does that differ from a Terraform CLI workspace?
answer
- two features, one shared name
- what a working directory used to hold
- state history and run history
- the unit teams get permissions on
- one directory, several state files
basics
~20 sAn HCP Terraform workspace holds what a working directory would: configuration, variables, credentials and state, plus state and run history and team permissions. A CLI workspace just gives one working directory an additional state file.
solid answer
~40 sThey share a name and little else. HCP Terraform manages infrastructure with workspaces instead of directories, so a workspace carries its configuration (from a linked repository or uploaded through the CLI or API), its variable values, its credentials as sensitive variables, and its state. It also keeps previous state versions and a record of its runs, and it is the unit you grant teams access on: Read, Plan, Write or Admin. A CLI workspace belongs to one working directory and isolates multiple state files there, so the code, the shell and the credentials stay the same. Terraform's own docs warn that CLI workspaces do not suit deployments needing separate credentials and access controls. HCP Terraform workspaces are also required: you cannot manage resources there without at least one.
go deeper
Recall the four things a workspace holds in place of a directory: configuration, variables, credentials and state. Then say plainly that a CLI workspace only adds another state file to one directory.
Explain how the cloud block connects the two: name ties a directory to one workspace, tags associate it with a matching set, and terraform workspace select then picks a full HCP Terraform workspace.
Show you have seen the confusion cost something: a CLI-workspace layout migrated without rethinking names, or a team assuming separate state meant separate credentials. Name what the workspace actually isolates and what it leaves shared.
Treat the workspace as the unit of permissions and run history, not only of state. That framing decides how an estate gets split, because a boundary that does not match team ownership forces over-broad grants.
## Two features that share a name Terraform has two different things called a workspace, and an interviewer asking this question wants to hear that you keep them apart. - An **HCP Terraform workspace** is an object in HashiCorp's HCP Terraform service, the hosted platform that runs Terraform and stores its results. - A **CLI workspace** is a feature of the `terraform` command that lets one working directory keep more than one state file. When you run Terraform locally, a persistent **working directory** holds the configuration, the state data and the variables. HCP Terraform replaces that directory with a workspace, and separate workspaces behave like completely separate working directories. ## What an HCP Terraform workspace holds | Component | Local Terraform | HCP Terraform workspace | |---|---|---| | Configuration | On disk | In a linked repository, or uploaded through the API or CLI | | Variable values | `.tfvars` files, CLI arguments, shell environment | In the workspace | | State | On disk or in a remote backend | In the workspace | | Credentials and secrets | Shell environment or prompts | In the workspace, as sensitive variables | On top of that, the service keeps data a directory never had: - **State versions:** backups of previous state files, useful for tracking changes and recovering from problems. - **Run history:** summaries, logs, what caused each run, and user comments. - **Settings:** the execution mode, the Terraform version, auto-apply and the working directory. - **Team access:** which teams can read, plan, apply or administer this workspace. - **A run queue:** each workspace processes its own runs in order. The configuration is tracked as a series of **configuration versions**, because the code changes over time, and each run is pinned to one of them. An HCP Terraform workspace manages a single state file, and it is required: you cannot manage resources in HCP Terraform without creating at least one. ## What a CLI workspace holds A CLI workspace belongs to a specific working directory and isolates multiple state files inside it. The configuration is the same code and the shell is the same shell. It has no variables, permissions or run history of its own, and the CLI does not make you create one, because every directory starts on a workspace named `default`. The Terraform language documentation states that CLI workspaces are not appropriate for deployments requiring separate credentials and access controls. ## Side by side | Question | HCP Terraform workspace | CLI workspace | |---|---|---| | Where it lives | In an HCP Terraform organization | Attached to one working directory | | Name scope | Unique within the organization | Local to that directory's backend | | Own variables | Yes | No | | Own credentials | Yes, as sensitive variables | No, whatever the shell holds | | Own permissions | Yes, granted per team | No | | Own run history | Yes, when HCP Terraform manages the runs | No | ## How the two meet in the `cloud` block The `cloud` block links a working directory to HCP Terraform workspaces, and this is where people mix the two up. - With `workspaces.name`, the directory is tied to one HCP Terraform workspace, and you cannot manage the workspace from the CLI. - With `workspaces.tags`, the directory is associated with every workspace matching all the tags, and `terraform workspace select` picks among them by full name. - When a directory with several CLI workspaces migrates, `terraform init` may prompt you to rename them, because HCP Terraform workspaces need unique names in the organization. A common pattern is `networking-prod-us-east`. So the CLI command survives, but the thing it selects is now a full HCP Terraform workspace, with its own variables and permissions. ## Mistakes to avoid in the answer 1. Saying an HCP Terraform workspace is a CLI workspace hosted remotely. It holds far more than state. 2. Saying `terraform workspace select` gives you a new set of credentials in a plain CLI setup. It switches the state file, and the credentials stay whatever the shell holds. 3. Forgetting credentials when you list the contents. Moving them off laptops is much of the practical value, as long as the run actually executes remotely.
- Why might one configuration map to several HCP Terraform workspaces?The same code often manages several environments. A `cloud` block using `workspaces.tags` associates the directory with every workspace matching all the tags, so `networking-prod` and `networking-staging` share code while each keeps its own state, variables and permissions. You switch with `terraform workspace select` and the full workspace name.
- Can you read a sensitive HCP Terraform workspace variable back after setting it?No. Marking a variable sensitive makes it write-only, so nobody can view it in the UI or read it through the Variables API, including the person who set it. Users with read and write access on variables can set a new value. The docs warn that even sensitive variables can sometimes end up in logs and state files.
- Does a new HCP Terraform workspace created by `terraform init` come ready to use?Not necessarily. It has no Terraform or environment variables unless a global variable set applies, no VCS connection and no working directory, and its Terraform version is the latest release at creation. Check its settings in the UI before performing any runs.
- An HCP Terraform workspace is just a CLI workspace hosted in the cloud.
- A CLI workspace gives each environment its own credentials and permissions.
- HCP Terraform workspaces are optional; you can run there without creating one.
- One HCP Terraform workspace holds a separate current state for each environment.
- A workspace variable is shared automatically with every workspace in the organization.