»Workspaces

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.

Terraform Cloud 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

Terraform Cloud workspaces and local working directories serve the same purpose, but they store their data differently:

In addition to the basic Terraform content, Terraform Cloud 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 Terraform Cloud for more details.

• Run history: When Terraform Cloud 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](/language/data-sources.

Terraform Runs

For workspaces with remote operations enabled (the default), Terraform Cloud 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.

Terraform Cloud vs. Terraform CLI Workspaces

Both Terraform Cloud and Terraform CLI have features called workspaces, but they function differently.

• Terraform Cloud 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 Terraform Cloud. 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 Terraform Cloud 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.

Listing and Filtering Workspaces

Click Projects & workspaces. Terraform Cloud displays the workspaces the current user account has permission to read runs for. The project drawer lists any projects the user has access to. (More about permissions.)

If your organization contains many workspaces, you can use the filter tools at the top of the list to find the workspaces you are interested in.

The following filters are available:

• Project filter: Click the left chevron icon next to Workspaces to open the project drawer. Clicking on a project will filter the workspaces list to show only the workspaces in the selected project. If your organization has many projects, click the search icon next to Projects to find a project.

• Run Status filter buttons: These filters display workspaces with the selected run status. There are five quick filter buttons that collect the most commonly used groups of statuses: Needs Attention, Errored, Running, On Hold, and Applied.

• Tag filter: The tag filter shows a list of tags added to all workspaces. Choosing one or more will show only workspaces tagged with all of the chosen tags.

• Status filter - The status filter shows a list of all possible statuses that apply to workspaces. When you choose a status filter, the list will only include workspaces whose current runs match the selected statuses.

• Health filter - The health filter lists workspaces based on the results of the last health assessment: Drifted, Health error, or Check failed.

• Column sorting: For any columns marked with two arrows, you can click the arrows to change the sort order for the column. You can sort the list by workspace name by alphabetical order, or by the latest change time for the workspace.

• Workspace search bar: The search field at the far right of the filter bar lets you filter workspaces by name. If you enter a string in this field and press enter, only workspaces whose names contain that string will be shown.

  The name filter can combine with a status and/or tag filter, to narrow the list down further.

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. Terraform Cloud can manage monolithic configurations just fine, but managing infrastructure as smaller components is the best way to take full advantage of Terraform Cloud'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. Organizations with the Team & Governance tier can assign project permissions to scope access to collections of workspaces based on business units and responsibilities.

Refer to Organize Workspaces with Projects for more details.

Creating Workspaces

You can create workspaces through the Terraform Cloud UI, the Workspaces API, or the Terraform Cloud CLI integration.

Workspace Health

Terraform Cloud 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 the configuration in your Terraform state file.
• 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.