Workspace settings

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.
• Health: Settings that let you configure health assessments, including drift detection and continuous validation.
• Locking: Locking a workspace temporarily prevents new plans and applies.
• Notifications: Settings that let you configure run notifications.
• Policies: Settings that let you toggle between Sentinel policy evaluation experiences.
• 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.)

General

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.

ID

Every workspace has a unique ID that you cannot change. You may need to reference the workspace's ID when using the HCP Terraform API.

Click the icon beside the ID to copy it to your clipboard.

Name

The display name of the workspace.

Project

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.

To move a workspace, you must have the "Manage all Projects" organization permission or explicit team admin privileges on both the source and destination projects. Remember that moving a workspace to another project may affect user visibility for that project's workspaces. Refer to Project Permissions for details on workspace access.

Description (Optional)

Enter a brief description of the workspace's purpose or types of infrastructure.

Execution Mode

Whether to use HCP Terraform as the Terraform execution platform for this workspace.

By default, HCP Terraform uses an organization's default execution mode to choose the execution platform for a workspace. Alternatively, you can instead choose a custom execution mode for a workspace.

Specifying the "Remote" execution mode instructs HCP Terraform 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, which Terraform can access with the CLI integration. HCP Terraform does not evaluate workspace variables or variable sets in local execution mode.

If you instead need to allow HCP Terraform to communicate with isolated, private, or on-premises infrastructure, consider using HCP Terraform agents. By deploying a lightweight agent, you can establish a simple connection between your environment and HCP Terraform.

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 of runs that error when changing your workspace's execution mode, you should:

1. Disable auto-apply if you have it enabled.
2. Complete any runs that are no longer in the pending stage.
3. Lock your workspace to prevent any new runs.
4. Change the execution mode.
5. Enable auto-apply, if you had it enabled before changing your execution mode.
6. Unlock your workspace.

Auto-apply

Whether or not HCP Terraform should automatically apply a successful Terraform plan. If you choose manual apply, an operator must confirm a successful plan and choose to apply it.

The main auto-apply setting affects runs created by the HCP Terraform user interface, API, CLI, and version control webhooks. HCP Terraform also has a separate setting for runs created by run triggers from another workspace.

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.)

Terraform Version

The Terraform version to use for all operations in the workspace. The default value is whichever release was current when HCP Terraform created the workspace. You can also update a workspace's Terraform version to an exact version or a valid version constraint.

Hands-on: Try the Upgrade Terraform Version in HCP Terraform tutorial.

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.

HCP Terraform 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, HCP Terraform 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, HCP Terraform 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 production is only one level deep, so Terraform would upload the immediate parent directory. consul/production is 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 HCP Terraform. 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 HCP Terraform 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.

User Interface

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.

Locking

If you need to prevent Terraform runs for any reason, you can lock a workspace. This prevents all applies (and many kinds of plans) from proceeding, and affects runs created via UI, CLI, API, and automated systems. To enable runs again, a user must unlock the workspace.

Two kinds of run operations can ignore workspace locking because they cannot affect resources or state and do not attempt to lock the workspace themselves:

• Plan-only runs.
• The planning stages of saved plan runs. You can only apply a saved plan if the workspace is unlocked, and applying that plan locks the workspace as usual. Terraform Enterprise does not yet support this workflow.

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. HCP Terraform asks for confirmation when unlocking.

You can also manage the workspace's lock from the Actions menu.

Notifications

The "Notifications" page allows HCP Terraform to send webhooks to external services whenever specific run events occur in a workspace.

See Run Notifications for detailed information about configuring notifications.

Policies

HCP Terraform offers two experiences for Sentinel policy evaluations. On the "Policies" page, you can adjust your Sentinel Experience settings to your preferred experience. By default, HCP Terraform enables the newest policy evaluation experience.

To toggle between the two Sentinel policy evaluation experiences, click the Enable the new Sentinel policy experience toggle under the Sentinel Experience heading. HCP Terraform persists your changes automatically. If HCP Terraform is performing a run on a different page, you must refresh that page to see changes to your policy evaluation experience.

Run Triggers

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.

SSH Key

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.

Team Access

The "Team Access" page configures which teams can perform which actions on a workspace.

See Managing Access to Workspaces for detailed information.

Version Control

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

The Destruction and Deletion page allows admin users to delete a workspace's managed infrastructure or delete the workspace itself.

For details, refer to Destruction and Deletion for detailed information about this page.