Skip to main content
All right — you’ve connected and authenticated with HCP Terraform. Your CLI can talk to your account, your token is stored, and you’re ready to proceed. Before we do anything inside HCP Terraform, step back and understand the platform’s fundamental building block: HCP Terraform workspaces. Note that Terraform CLI workspaces are a separate concept — they share the name but behave very differently. This section clarifies those differences, scope, and when to use each. Why the distinction matters
  • CLI workspaces (created with terraform workspace new and switched with terraform workspace select) are a lightweight way to keep multiple state files for the same configuration (for example, dev vs prod) inside a single working directory. They’re managed locally by the Terraform CLI.
  • HCP Terraform workspaces are full, self-contained environments managed by the HCP platform (UI, CLI, or API). Each workspace includes config, state, variables, execution settings, run history, and access controls — everything needed to manage a defined set of infrastructure.
Comparison at a glance
An infographic comparing "CLI Workspaces" and "HCP Terraform Workspaces" with the Terraform logo centered. Each side lists contrasting points (e.g., "same configuration, multiple state files" vs "complete working environments") and a footer saying "Same Name, Fundamentally Different Concept."
What an HCP Terraform workspace contains According to the HashiCorp documentation, a workspace is everything Terraform needs to manage a given collection of infrastructure. Concretely, that includes:
  • Terraform configuration: the .tf files for the workspace (linked via a VCS repo or uploaded by the CLI during a run).
  • State and version history: encrypted, versioned state with full history and rollback capability.
  • Variables: workspace-specific Terraform variables and environment variables; sensitive variables are write-only and hidden after save.
  • Run history and logs: a complete audit trail of plans, applies, destroys, who triggered them, and their logs.
  • Execution settings: execution mode, pinned Terraform version, and auto-apply behavior options.
  • Team access and permissions: role-based controls for viewing, planning, applying, and managing variables.
Why this matters: an HCP Terraform workspace is much more than a remote state file — it’s a self-contained environment for managing a defined infrastructure lifecycle.
A presentation slide titled "Introduction to HCP Terraform Workspaces" that lists what a workspace contains (configuration, state file, variables, run history, execution settings, team access). It also features a large Terraform logo graphic on the right.
How workspaces fit into HCP Terraform
  • Organization: At the top level is your HCP Terraform organization — the container created when you first signed in. Organizations contain multiple workspaces.
  • Isolation: Each workspace (for example, NetworkingProd, AppOneProd, DBProd) is isolated with its own state, variables, run history, and settings. Changes in one workspace do not impact another.
  • Projects: Use projects to group related workspaces and make it easier to manage many environments.
  • Reuse: You can reuse the same repository across multiple workspaces (e.g., one repo used for prod and dev) by supplying different variables, but each workspace retains its own configuration metadata and state.
Inside a single workspace (example: NetworkingProd)
  • Variables: environment- and Terraform-specific variables (region, instance sizes, credentials, etc.).
  • Terraform version: pin the workspace to a specific Terraform version so runs are consistent across contributors.
  • Run history and audit trail: plans, applies, destroys, and their logs are stored.
  • Permissions: role-based access for viewing, planning, applying, and variable management.
  • State file: encrypted at rest and versioned for rollback.
  • Terraform configuration: .tf files for the workspace — typically linked via a VCS connection.
HCP Terraform encrypts workspace state at rest by default and retains versioned state history so you can safely roll back to previous states without additional state-encryption configuration.
VCS connection and workflows Linking a workspace to a VCS repository enables an integrated, Git-driven workflow: push code, receive an automatically generated plan, review it, then apply (manually or via auto-apply). This provides strong traceability between repository changes and infrastructure modifications. HCP Terraform supports three workflow types — choose based on team needs: Key CLI workspace commands (local concept)
  • Create a new CLI workspace: terraform workspace new <name>
  • Select a workspace: terraform workspace select <name>
  • List workspaces: terraform workspace list
Certification tip If you’re preparing for the Terraform Associate Certification, make sure you can:
  • Distinguish CLI workspaces from HCP Terraform workspaces.
  • Explain workspace contents (state, variables, run history, execution settings, RBAC).
  • Describe the three workflow types (VCS, CLI, API) and when to use each.
An infographic titled "Workspace Workflow Types" showing three columns for Version Control Workflow, CLI-Driven Workflow, and API-Driven Workflow, each with an icon and brief explanatory text. The design uses purple and teal colors with large icons and headings.
Further reading and references

Watch Video