You can change a workspace’s settings after creation. Workspace settings are separated into several pages.
- General: Settings that determine how the workspace functions, including its name, description, associated project, Terraform version, and execution mode.
- Locking: Locking a workspace temporarily prevents new plans and applies.
- Notifications: Settings that let you configure run notifications.
- Run Triggers: Settings that let you configure run triggers. Run triggers allow runs to queue automatically in your workspace when runs in other workspaces are successful.
- SSH Key: Set a private SSH key for downloading Terraform modules from Git-based module sources.
- Team Access: Settings that let you manage which teams can view the workspace and use it to provision infrastructure.
- Version Control: Manage the workspace’s VCS integration.
- Destruction and Deletion: Remove a workspace and the infrastructure it manages.
Changing settings requires admin access to the relevant workspace. (More about permissions.)
API: See the Update a Workspace endpoint (
General settings let you change a workspace's name, description, the project it belongs to, and details about how Terraform runs operate. After changing these settings, click Save settings at the bottom of the page.
Every workspace has a unique ID that you cannot change. You may need to reference the workspace's ID when using the Terraform Cloud API.
Click the icon beside the ID to copy it to your clipboard.
The display name of the workspace.
Warning: Some API calls refer to a workspace by its name, so changing the name may break existing integrations.
The project that this workspace belongs to. Changing the workspace’s project can change the read and write permissions for the workspace and which users can access it. Refer to Project Permissions for more detail on workspace access.
Enter a brief description of the workspace's purpose or types of infrastructure.
Enter a brief description of the workspace's purpose or types of infrastructure.
Whether to use Terraform Cloud as the Terraform execution platform for this workspace.
The default value is "Remote", which instructs Terraform Cloud to perform Terraform runs on its own disposable virtual machines. This provides a consistent and reliable run environment, and enables advanced features like Sentinel policy enforcement, cost estimation, notifications, version control integration, and more.
To disable remote execution for a workspace, change its execution mode to "Local". This mode lets you perform Terraform runs locally with the CLI-driven run workflow. The workspace will store state and variables, which Terraform can access with the CLI integration.
If you instead need to allow Terraform Cloud to communicate with isolated, private, or on-premises infrastructure, consider using Terraform Cloud Agents. By deploying a lightweight agent, you can establish a simple connection between your environment and Terraform Cloud.
Changing your workspace's execution mode after a run has already been planned will cause the run to error when it is applied.
To minimize the number runs that error when changing your workspace's execution mode, you should:
- Disable auto-apply if you have it enabled.
- Complete any runs that are no longer in the pending stage.
- Lock your workspace to prevent any new runs.
- Change the execution mode.
- Enable auto-apply, if you had it enabled before changing your execution mode.
- Unlock your workspace.
Whether or not Terraform Cloud should automatically apply a successful Terraform plan. If you choose manual apply, an operator must confirm a successful plan and choose to apply it.
Auto-apply has the following exception:
- Plans queued by users without permission to apply runs for the workspace must be approved by a user who does have permission. (More about permissions.)
- Plans queued due to run triggers from another workspace must always be manually applied.
The Terraform version to use for all operations in the workspace. The default value is whichever release was current when the workspace was created.
Hands-on: Try the Upgrade Terraform Version in Terraform Cloud tutorial.
API: You can specify a Terraform version when creating a workspace via the API. The API also supports setting a valid version constraint as the Terraform version.
Terraform Working Directory
The directory where Terraform will execute, specified as a relative path from the root of the configuration directory. Defaults to the root of the configuration directory.
Terraform Cloud will change to this directory before starting a Terraform run, and will report an error if the directory does not exist.
Setting a working directory creates a default filter for automatic run triggering, and sometimes causes CLI-driven runs to upload additional configuration content.
Default Run Trigger Filtering
In VCS-backed workspaces that specify a working directory, Terraform Cloud assumes that only changes within that working directory should trigger a run. You can override this behavior with the Automatic Run Triggering settings.
Parent Directory Uploads
If a working directory is configured, Terraform Cloud always expects the complete shared configuration directory to be available, since the configuration might use local modules from outside its working directory.
In runs triggered by VCS commits, this is automatic. In CLI-driven runs, Terraform's CLI sometimes uploads additional content:
- When the local working directory does not match the name of the configured working directory, Terraform assumes it is the root of the configuration directory, and uploads only the local working directory.
- When the local working directory matches the name of the configured working directory, Terraform uploads one or more parents of the local working directory, according to the depth of the configured working directory. (For example, a working directory of
productionis only one level deep, so Terraform would upload the immediate parent directory.
consul/productionis two levels deep, so Terraform would upload the parent and grandparent directories.)
If you use the working directory setting, always run Terraform from a complete copy of the configuration directory. Moving one subdirectory to a new location can result in unexpected content uploads.
Remote State Sharing
Which other workspaces within the organization can access the state of the workspace during runs managed by Terraform Cloud. The
terraform_remote_state data source relies on state sharing to access workspace outputs.
If "Share state globally" is enabled, all other workspaces within the organization can access this workspace's state during runs.
If global sharing is turned off, you can specify a list of workspaces within the organization that can access this workspace's state; no other workspaces will be allowed.
The workspace selector is searchable; if you don't initially see a workspace you're looking for, type part of its name.
By default, new workspaces in Terraform Cloud do not allow other workspaces to access their state. We recommend that you follow the principle of least privilege and only enable state access between workspaces that specifically need information from each other. To configure remote state sharing, a user must have read access for the destination workspace. If a user does not have access to the destination workspace due to scoped project or workspace permissions, they will not have complete visibility into the list of other workspace that can access its state.
Note: The default access permissions for new workspaces in Terraform Cloud changed in April 2021. Workspaces created before this change defaulted to allowing global access within their organization. These workspaces can be changed to more restrictive access at any time. Terraform Enterprise administrators can choose whether new workspaces on their instances default to global access or selective access.
Select the user experience for displaying plan and apply details.
The default experience is Structured Run Output, which displays your plan and apply results in a human-readable format. This includes nodes that you can expand to view details about each resource and any configured output.
The Console UI experience is the traditional Terraform experience, where live text logging is streamed in real time to the UI. This experience most closely emulates the CLI output.
Note: Your workspace must be configured to use a Terraform version of 1.0.5 or higher for the Structured Run Output experience to be fully supported. Workspaces running versions from 0.15.2 may see partial functionality. Workspaces running versions below 0.15.2 will default to the "Console UI" experience regardless of the User Interface setting.
Important: Unlike other settings, locks can also be managed by users with permission to lock and unlock the workspace. (More about permissions.)
If you need to prevent Terraform runs for any reason, you can lock a workspace. This prevents users with permission to queue plans from manually queueing runs, prevents automatic runs due to changes to the backing VCS repo, and prevents the creation of runs via the API. To enable runs again, a user must unlock the workspace.
Locking a workspace also restricts state uploads. In order to upload state, the workspace must be locked by the user who is uploading state.
Users with permission to lock and unlock a workspace can't unlock a workspace which was locked by another user. Users with admin access to a workspace can force unlock a workspace even if another user has locked it.
Locks are managed with a single "Lock/Unlock/Force unlock
<WORKSPACE NAME>" button. Terraform Cloud asks for confirmation when unlocking.
You can also manage the workspace's lock from the Actions menu.
The "Notifications" page allows Terraform Cloud to send webhooks to external services whenever specific run events occur in a workspace.
See Run Notifications for detailed information about configuring notifications.
The "Run Triggers" page configures connections between a workspace and one or more source workspaces. These connections, called "run triggers", allow runs to queue automatically in a workspace on successful apply of runs in any of the source workspaces.
See Run Triggers for detailed information about configuring run triggers.
If a workspace's configuration uses Git-based module sources to reference Terraform modules in private Git repositories, Terraform needs an SSH key to clone those repositories. The "SSH Key" page lets you choose which key it should use.
See Using SSH Keys for Cloning Modules for detailed information about this page.
The "Team Access" page configures which teams can perform which actions on a workspace.
See Managing Access to Workspaces for detailed information.
The "Version Control" page configures an optional VCS repository that contains the workspace's Terraform configuration. Version control integration is only relevant for workspaces with remote execution enabled.
See VCS Connections for detailed information about this page.
Destruction and Deletion
This page includes two sections:
- "Destroy Infrastructure"
- "Delete Workspace"
In almost all cases, you should perform both actions in that order when destroying a workspace.
Queueing a destroy plan destroys the infrastructure managed by a workspace. If you don't do this, the infrastructure resources will continue to exist but will become unmanaged; you'll need to go into your infrastructure providers to delete the resources manually.
Before queueing a destroy plan, you must enable the 'Allow destroy plans' setting and click the "Save settings" button.
Deleting a Workspace With Resources Under Management
Terraform does not automatically destroy managed infrastructure when you delete a workspace.
After you delete the workspace and its state file, Terraform can no longer track or manage the infrastructure. You must manually delete any remaining resources or import them into another Terraform workspace.
By default, workspace administrators can only delete unlocked workspaces that are not managing any infrastructure. Organization owners can force delete a workspace to override these protections. Organization owners can also configure the organization's settings to let workspace administrators force delete their own workspaces.