Edit this page on GitHub
Hands-on: Try the Get Started - Terraform Cloud 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:
- Terraform Cloud UI: Create a Workspace
- Workspaces API: Create a Workspace endpoint
- Terraform Enterprise Provider:
- No-Code Provisioning: The no-code provisioning workflow creates a new workspace and deploys a no-code ready module's resources in it.
You must be a member of a team with manage workspaces permissions to create a workspace.
The workspace creation process varies depending on the workflow you choose (e.g., CLI-driven). To create a workspace in the Terraform Cloud UI:
- Click Workspaces to view a list of the workspaces within your organization.
- Click + New Workspace. The Create a new Workspace page appears.
- Choose a workflow type: Version control, CLI-driven, or API-driven.
- (Version control only) Choose an existing version control provider or configure a new one. Refer to Connecting VCS Providers for more details.
- (Version control only) Choose a repository from the filterable list. The Configure settings page appears.
Note: Depending on your provider, you may need to change which account's repositories are shown. You can also scroll to the bottom of the list and enter the repository ID in the text field if it is not immediately visible.
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 our workspace naming recommendations.
Add an optional Description that will appear at the top of the workspace in the Terraform Cloud UI.
(Version control only) Open Advanced options to optionally configure the following settings:
Click Create workspace.
For CLI and API-driven workspaces, the workspace overview page appears. For version control workspaces, the Configure Terraform variables page appears.
After you create a new workspace from a version control repository, Terraform Cloud scans its configuration files for Terraform variables and displays any that do not have a default value and do not have a definition in an existing global 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 Cloud 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.tfvarsfile. Click Save variables to add these variables to the 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.
If you connected a VCS repository to the workspace, Terraform Cloud 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 Cloud 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.