Create workspaces

This topic describes how to create and manage workspaces in HCP Terraform and Terraform Enterprise UI. A workspace is a group of infrastructure resources managed by Terraform. Refer to Workspaces overview for additional information.

Hands-on: Try the Get Started - HCP Terraform tutorials.

Introduction

Create new workspaces when you need to manage a new collection of infrastructure resources. You can use the following methods to create workspaces:

• UI: Refer to Create a workspace for instructions.
• Workspaces API: Send a POSTcall to the /organizations/:organization_name/workspaces endpoint to create a workspace. Refer to the API documentation for instructions.
• Terraform Enterprise provider: Install the tfe provider and add the tfe_workspace resource to your configuration. Refer to the tfe provider documentation in the Terraform registry for instructions.
• No-code provisioning: Use a no-code module from the registry to create a new workspace and deploy the module's resources. Refer to Provisioning No-Code Infrastructure for instructions.

Each workspace belongs to a project. Refer to Manage projects for additional information.

Requirements

You must be a member of a team with one of the following permissions enabled to create and manage workspaces:

• Manage all projects
• Manage all workspaces
• Admin permission group for a project.

Workspace naming

We recommend using consistent and informative names for new workspaces. One common approach is combining the workspace's important attributes in a consistent order. Attributes can be any defining characteristic of a workspace, such as the component, the component’s run environment, and the region where the workspace is provisioning infrastructure.

This strategy could produce the following example workspace names:

• networking-prod-us-east
• networking-staging-us-east
• networking-prod-eu-central
• networking-staging-eu-central
• monitoring-prod-us-east
• monitoring-staging-us-east
• monitoring-prod-eu-central
• monitoring-staging-eu-central

You can add additional attributes to your workspace names as needed. For example, you may add the infrastructure provider, datacenter, or line of business.

We recommend using 90 characters or less for the name of your workspace.

Create a workspace

Complete the following steps to use the HCP Terraform or Terraform Enterprise UI to create a workspace:

1. Log in and choose your organization.
2. Click New and choose Workspace from the drop-down menu.
3. If you have multiple projects, HCP Terraform may prompt you to choose the project to create the workspace in. Only users on teams with permissions for the entire project or the specific workspace can access the workspace. Refer to Manage projects for additional information.
4. Choose a workflow type.
5. Complete the following steps if you are creating a workspace that follows the VCS workflow:
   1. Choose an existing version control provider from the list or configure a new system. You must enable the workspace project to connect to your provider. Refer to Connecting VCS Providers for more details.
   2. If you choose the GitHub App provider, choose an organization and repository when prompted. The list only displays the first 100 repositories from your VCS provider. If your repository is missing from the list, enter the repository ID in the text field .
   3. Refer to the following topics for information about configuring workspaces settings in the Advanced options screen:
      • Terraform Working Directory
      • Automatic Run Triggering
      • VCS branch
      • Include submodules on clone
6. Specify a name for the workspace. VCS workflow workspaces default to the name of the repository. The name must be unique within the organization and can include letters, numbers, hyphens, and underscores. Refer to Workspace naming for additional information.
7. Add an optional description for the workspace. The description appears at the top of the workspace in the Terraform Enterprise UI.
8. Click Create workspace to finish.

For CLI or API-driven workflow, the system opens the new workspace overview. For version control workspaces, the Configure Terraform variables page appears.

Configure Terraform variables for VCS workflows

After you create a new workspace from a version control repository, Terraform Enterprise scans its configuration files for Terraform variables and displays variables without default values or variables that are undefined in an existing global or project-scoped variable set. Terraform cannot perform successful runs in the workspace until you set values for these variables.

Choose one of the following actions:

• To skip this step, click Go to workspace overview. You can load these variables from files or create and set values for them later from within the workspace. Terraform Enterprise does not automatically scan your configuration again; you can only add variables from within the workspace individually.
• To configure variables, enter a value for each variable on the page. You may want to leave a variable empty if you plan to provide it through another source, like an auto.tfvars file. Click Save variables to add these variables to the workspace.

Next steps

If you have already configured all Terraform variables, we recommend manually starting a run to prepare VCS-driven workspaces. You may also want to do one or more of the following actions:

• Upload configuration versions: If you chose the API or CLI-Driven workflow, you must upload configuration versions for the workspace.
• Edit environment variables: Shell environment variables store credentials and customize Terraform's behavior.
• Edit additional workspace settings: This includes notifications, permissions, and run triggers to start runs automatically.
• Learn more about running Terraform in your workspace: This includes how Terraform processes runs within the workspace, run modes, run states, and other operations.
• Browse workspaces: Use the interfaces available in the UI to browse, sort, and filter workspaces so that you can track resource consumption.

VCS Connection

If you connected a VCS repository to the workspace, Terraform Enterprise automatically registers a webhook with your VCS provider. A workspace with no runs will not accept new runs from a VCS webhook, so you must manually start at least one run.

After you manually start a run, Terraform Enterprise automatically queues a plan when new commits appear in the selected branch of the linked repository or someone opens a pull request on that branch. Refer to Webhooks for more details.