Workspaces
This topic provides an overview of the workspaces resource in HCP Terraform and Terraform Enterprise. A workspace is a group of infrastructure resources managed by Terraform.
Introduction
Working with Terraform involves managing collections of infrastructure resources, and most organizations manage many different collections.
When run locally, Terraform manages each collection of infrastructure with a persistent working directory, which contains a configuration, state data, and variables. Since Terraform CLI uses content from the directory it runs in, you can organize infrastructure resources into meaningful groups by keeping their configurations in separate directories.
HCP Terraform manages infrastructure collections with workspaces instead of directories. A workspace contains everything Terraform needs to manage a given collection of infrastructure, and separate workspaces function like completely separate working directories.
Hands-on: Try the Create a Workspace tutorial.
Workspace Contents
HCP Terraform workspaces and local working directories serve the same purpose, but they store their data differently:
| Component | Local Terraform | HCP Terraform |
|---|---|---|
| Terraform configuration | On disk | In linked version control repository, or periodically uploaded via API/CLI |
| Variable values | As .tfvars files, as CLI arguments, or in shell environment | In workspace |
| State | On disk or in remote backend | In workspace |
| Credentials and secrets | In shell environment or entered at prompts | In workspace, stored as sensitive variables |
In addition to the basic Terraform content, HCP Terraform keeps some additional data for each workspace:
State versions: Each workspace retains backups of its previous state files. Although only the current state is necessary for managing resources, the state history can be useful for tracking changes over time or recovering from problems. Refer to Terraform State in HCP Terraform for more details.
Run history: When HCP Terraform manages a workspace's Terraform runs, it retains a record of all run activity, including summaries, logs, a reference to the changes that caused the run, and user comments. Refer to Viewing and Managing Runs for more details.
The top of each workspace shows a resource count, which reflects the number of resources recorded in the workspace’s state file. This includes both managed resources and data sources.
Terraform Runs
For workspaces with remote operations enabled (the default), HCP Terraform performs Terraform runs on its own disposable virtual machines, using that workspace's configuration, variables, and state.
Refer to Terraform Runs and Remote Operations for more details.
HCP Terraform vs. Terraform CLI Workspaces
Both HCP Terraform and Terraform CLI have features called workspaces, but they function differently.
HCP Terraform workspaces are required. They represent all of the collections of infrastructure in an organization. They are also a major component of role-based access in HCP Terraform. You can grant individual users and user groups permissions for one or more workspaces that dictate whether they can manage variables, perform runs, etc. You cannot manage resources in HCP Terraform without creating at least one workspace.
Terraform CLI workspaces are associated with a specific working directory and isolate multiple state files in the same working directory, letting you manage multiple groups of resources with a single configuration. The Terraform CLI does not require you to create CLI workspaces. Refer to Workspaces in the Terraform Language documentation for more details.
Planning and Organizing Workspaces
We recommend that organizations break down large monolithic Terraform configurations into smaller ones, then assign each one to its own workspace and delegate permissions and responsibilities for them. HCP Terraform can manage monolithic configurations just fine, but managing infrastructure as smaller components is the best way to take full advantage of HCP Terraform's governance and delegation features.
For example, the code that manages your production environment's infrastructure could be split into a networking configuration, the main application's configuration, and a monitoring configuration. After splitting the code, you would create "networking-prod", "app1-prod", "monitoring-prod" workspaces, and assign separate teams to manage them.
Much like splitting monolithic applications into smaller microservices, this enables teams to make changes in parallel. In addition, it makes it easier to re-use configurations to manage other environments of infrastructure ("app1-dev," etc.).
In Terraform Enterprise, administrators can use Admin Settings to set the maximum number of workspaces for any single organization. You can also set a workspaces limit with the tfe-terraform-provider.
Organize Workspaces with Projects
Projects let you organize your workspaces into groups.
Note: On HCP Terraform Standard Edition, you can assign project permissions to scope access to collections of workspaces based on business units and responsibilities. Refer to HCP Terraform pricing for details.
Refer to Organize Workspaces with Projects for more details.
Creating Workspaces
You can create workspaces through the HCP Terraform UI, the Workspaces API, or the HCP Terraform CLI integration.
Workspace Health
Note: Health assessments are available in HCP Terraform Plus Edition. Refer to HCP Terraform pricing for details.
HCP Terraform can perform automatic health assessments in a workspace to assess whether its real infrastructure matches the requirements defined in its Terraform configuration. Health assessments include the following types of evaluations:
- Drift detection determines whether your real-world infrastructure matches your Terraform configuration.
- Continuous validation determines whether custom conditions in the workspace’s configuration continue to pass after Terraform provisions the infrastructure.
You can enforce health assessments for all eligible workspaces or let each workspace opt in to health assessments through workspace settings. Refer to Health in the workspaces documentation for more details.