Creating Workspaces

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

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

• HCP Terraform UI: Create a Workspace
• Workspaces API: Create a Workspace endpoint
• Terraform Enterprise Provider: tfe_workspace resource
• No-Code Provisioning: The no-code provisioning workflow creates a new workspace and deploys a no-code ready module's resources in it.

Permissions

You must be a member of a team with manage all projects permissions, manage all workspaces permissions, or admin permissions for a project to create a workspace.

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

The workspace creation process varies depending on the workspace workflow you choose (VCS, API, or CLI-driven). To create a workspace in the HCP Terraform UI:

1. Click Projects & workspaces to view a list of the workspaces within your organization.

2. Click New, then select Workspace from the dropdown menu.

3. If you have access to multiple projects, you may be prompted to choose a Project to add the workspace to. Only teams with permissions for the entire project or the specific workspace will be able to access the workspace. Refer to Organizing Workspaces with Projects for more details.

4. Choose a workflow type: Version control, CLI-driven, or API-driven.

5. (Version control only) Choose an existing version control provider from the list or configure a new one. Only version control providers enabled for the selected project will be available to connect. Refer to Connecting VCS Providers for more details.

6. (Version control only) Choose an organization (GitHub App only), and repository from the filterable list. The Configure settings page appears.

   Tip: If your repository is missing from the list, enter the repository ID in the text field below the list. The list only displays the first 100 repositories from your VCS provider.

7. Enter a Workspace Name. This defaults to the repository name, if applicable. The name must be unique within the organization and can include letters, numbers, dashes (-), and underscores (_). Refer to the workspace naming recommendations.

8. Add an optional Description that will appear at the top of the workspace in the HCP Terraform UI.

9. (Version control only) Open Advanced options to optionally configure the following settings:

   • Terraform Working Directory
   • Automatic Run Triggering
   • VCS branch
   • Include submodules on clone

10. Click Create workspace.

For CLI and API-driven workspaces, the workspace overview page appears. For version control workspaces, the Configure Terraform variables page appears.

Workspace Tags

After you create a workspace, you can create or assign tags to it. Tags are subject to the following rules:

• Workspace tags or tags must be one or more characters, have a 255 character limit, and can include letters, numbers, colons, hyphens, and underscores.
• You can create tags for a workspace using the user interface or the API. After you create a tag, you can assign it to other workspaces in the same organization.
• You cannot create tags for a workspace using the CLI.
• You cannot set tags at the project level, so there is no tag inheritance from projects to workspaces.

Configure Terraform Variables (Version Control Only)

After you create a new workspace from a version control repository, HCP Terraform 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. HCP Terraform 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.

After Creating a Workspace

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, etc.

VCS Connection

If you connected a VCS repository to the workspace, HCP Terraform 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, HCP Terraform 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.