» Creating and Managing Terraform Workspaces

Prerequisites: Before starting this guide, you should get access to Terraform Cloud and configure VCS access.

At this point, you've done all the setup Terraform Cloud needs, and can start using it for real work. Your first task should be to set up some workspaces.

» About Workspaces

Workspaces are how Terraform Cloud organizes infrastructure. A workspace consists of:

  • A collection of Terraform configurations (retrieved from a VCS repo).
  • Values for any variables those configurations require.
  • Persistent stored state for the resources it manages.
  • Historical state and run logs.

A well-designed Terraform workflow uses multiple configurations, so you can manage each logical grouping of infrastructure with its own code. Additionally, it's common to use the same configuration multiple times (with different values for variables) to manage different environments.

» Creating a Workspace

First, make sure you're viewing the workspace list. If you're still on the VCS settings (or any other page), click the "Workspaces" button in the top navigation bar.


The workspace list shows all of the workspaces you have access to; if you haven't created any, it's empty.

To create your first workspace, click the "+ New Workspace" button in the upper right.

new button

On the "Create a new Workspace" page, follow the instructions to configure a VCS repository and a workspace name, then confirm creation with the "Create workspace" button.

A workspace name should tell your colleagues what the workspace is for. Most workspaces are a particular environment of a particular Terraform configuration, so the name should include both the name of the configuration and the name of the environment.

In this example, we're using a configuration named "minimum" and we're deploying it in a production environment, so we named it minimum-prod.

For more details, see Creating Workspaces.

» What Happens in a New Workspace

When you create a new workspace, a few things happen:

  • Terraform Cloud doesn't immediately queue a plan for the workspace. Instead, it presents you with a dialog, with shortcut links to either queue a plan or edit variables.

    finish dialog

  • Terraform Cloud automatically registers a webhook with your VCS service. The next time new commits appear in the selected branch of that repo, Terraform Cloud will automatically queue a Terraform plan for the workspace.

» Editing Variables

For almost any workspace, you'll want to edit the Terraform variables and environment variables used by the code.

You can edit variables as soon as you've created a workspace, by clicking the workspace's "Variables" tab.

Screenshot: the variables page

The variables page has two sections: Terraform variables (as declared in your Terraform configurations) and environment variables.

Click the "+ Add Variable" button to create a new variable, or click an existing variable's text fields or pencil icon to change its values and settings. After editing a variable, be sure to click its "Save Variable" button.

Screenshot: editing a variable

Terraform variables start as basic string values, but you can also enter array or map values if you click the "HCL" checkbox for that variable. You can write these values with the same syntax you'd use in a Terraform configuration.

For more information, see Variables.

» Granting Access

The user account that created your organization is part of the "owners" team, which can do any action on any workspace. Most of your colleagues don't need that level of access; instead, an administrator can give them access to the specific workspaces they need to use.

Terraform Cloud manages access with teams. In your organization's settings, you can create any number of teams and add users to them — earlier in this getting started guide, you might have already created a team to bring other users into your organization. If you haven't done that yet, do it now.

Once you have some teams, you can add them to a workspace by choosing "Team Access" from the "Settings" menu:

managing team access to a workspace

A newly created workspace can't be used by anyone but the "owners" team; other teams can't even see it. To enable collaboration on a workspace, you must add other teams to it.

To add a team to a workspace, select it from the dropdown menu and choose which permissions the team should have. There are three levels of permissions available:

  • Read access lets team members view the workspace's variables and settings, view its run history, and view its StateVersions and ConfigurationVersions. They can't queue plans, apply existing plans, or change any variables or settings.
  • Plan access lets team members queue plans (and run speculative plans from the command line), but doesn't let them approve infrastructure changes; a user with write access must confirm the plan.
  • Write access lets team members create and approve runs, and lock or unlock the workspace. It doesn't let them change variables or settings.
  • Admin access lets team members change variables and settings, add other teams to the workspace, remove other teams from the workspace, and delete the workspace.

To change a team's permissions on a workspace, you must first delete their existing permissions, then add their new permissions.

» Configuring a Workspace

Each workspace has a "Settings" menu (available from the top links when viewing that workspace), which links to several pages where you can change the behavior of the workspace.

For more information, see Workspace Settings.

Most of your time in Terraform Cloud is spent in two views:

  • The workspace list. Use this to get an overview of the workspaces you're responsible for, and to navigate between workspaces.

    main page

    To get back to the workspace list at any time, click the "Workspaces" button in the top navigation bar.

  • The individual workspace pages, which provide more detail about a workspace's status, and let you manage runs, variables, and settings.

    To reach a workspace page, click that workspace's entry on the workspace list.

    a workspace page

» Next Steps

Now that you've created and configured at least one workspace, you're ready to start performing Terraform runs.