Remote Operations

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

HCP Terraform provides a central interface for running Terraform within a large collaborative organization. If you're accustomed to running Terraform from your workstation, the way HCP Terraform manages runs can be unfamiliar.

This page describes the basics of how runs work in HCP Terraform.

HCP Terraform is designed as an execution platform for Terraform, and can 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.

Terraform runs managed by HCP Terraform are called remote operations. Remote runs can be initiated by webhooks from your VCS provider, by UI controls within HCP Terraform, by API calls, or by Terraform CLI. When using Terraform CLI to perform remote operations, the progress of the run is streamed to the user's terminal, to provide an experience equivalent to local operations.

Disabling Remote Operations

Many of HCP Terraform's features rely on remote execution and are not available when using local operations. This includes features like Sentinel policy enforcement, cost estimation, and notifications.

You can disable remote operations for any workspace by changing its Execution Mode to Local. This causes the workspace to act only as a remote backend for Terraform state, with all execution occurring on your own workstations or continuous integration workers.

Protecting Private Environments

HCP Terraform agents are a paid feature that allows HCP Terraform to communicate with isolated, private, or on-premises infrastructure. The agent polls HCP Terraform or Terraform Enterprise for any changes to your configuration and executes the changes locally, so you do not need to allow public ingress traffic to your resources. Agents allow you to control infrastructure in private environments without modifying your network perimeter.

HCP Terraform agents also support running custom programs, called hooks, during strategic points of a Terraform run. For example, you may create a hook to dynamically download software required by the Terraform run or send an HTTP request to a system to kick off an external workflow.

Runs and Workspaces

HCP Terraform always performs Terraform runs in the context of a workspace. The workspace serves the same role that a persistent working directory serves when running Terraform locally: it provides the configuration, state, and variables for the run.

Configuration Versions

Each workspace is associated with a particular Terraform configuration, but that configuration is expected to change over time. Thus, HCP Terraform manages configurations as a series of configuration versions.

Most commonly, a workspace is linked to a VCS repository, and its configuration versions are tied to revisions in the specified VCS branch. In workspaces that aren't linked to a repository, new configuration versions can be uploaded via Terraform CLI or via the API.

Ordering and Timing

Each workspace in HCP Terraform maintains its own queue of runs, and processes those runs in order.

Whenever a new run is initiated, it's added to the end of the queue. If there's already a run in progress, the new run won't start until the current one has completely finished — HCP Terraform won't even plan the run yet, because the current run might change what a future run would do. Runs that are waiting for other runs to finish are in a pending state, and a workspace might have any number of pending runs.

There are two exceptions to the run queue, which can proceed at any time and do not block the progress of other runs:

Plan-only runs.
The planning stages of saved plan runs. You can only apply a saved plan if no other run is in progress, and applying that plan blocks the run queue as usual. Terraform Enterprise does not yet support this workflow.

When you initiate a run, HCP Terraform locks the run to a particular configuration version and set of variable values. If you change variables or commit new code before the run finishes, it will only affect future runs, not runs that are already pending, planning, or awaiting apply.

Workspace Locks

When a workspace is locked, HCP Terraform can create new runs (automatically or manually), but those runs do not begin until you unlock the workspace.

When a run is in progress, that run locks the workspace, as described above under "Ordering and Timing".

There are two kinds of run operation that can ignore workspace locking:

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.

A user or team can also deliberately lock a workspace, to perform maintenance or for any other reason. For more details, see Locking Workspaces (Preventing Runs).

Starting Runs

HCP Terraform has three main workflows for managing runs, and your chosen workflow determines when and how Terraform runs occur. For detailed information, see:

The UI/VCS-driven run workflow, which is the primary mode of operation.
The API-driven run workflow, which is more flexible but requires you to create some tooling.
The CLI-driven run workflow, which uses Terraform's standard CLI tools to execute runs in HCP Terraform.

You can use the following methods to initiate HCP Terraform runs:

Click the + New run button on the workspace's page
Implement VCS webhooks
Run the standard terraform apply command when the CLI integration is configured
Call the Runs API using any API tool

Plans and Applies

HCP Terraform enforces Terraform's division between plan and apply operations. It always plans first, then uses that plan's output for the apply.

In the default configuration, HCP Terraform waits for user approval before running an apply, but you can configure workspaces to automatically apply successful plans. Some plans can't be auto-applied, like plans queued by run triggers or by users without permission to apply runs for the workspace. (More about permissions.)

If a plan contains no changes, HCP Terraform does not attempt to apply it. Instead, the run ends with a status of "Planned and finished". The allow empty apply run mode can override this behavior.

Speculative Plans

In addition to normal runs, HCP Terraform can run speculative plans to test changes to a configuration during editing and code review. Speculative plans are plan-only runs. They show possible changes, and policies affected by those changes, but cannot apply any changes.

Speculative plans can begin without waiting for other runs to finish because they don't affect real infrastructure. HCP Terraform lists past speculative plan runs alongside a workspace's other runs.

There are three ways to run speculative plans:

In VCS-backed workspaces, pull requests start speculative plans, and the VCS provider's pull request interface includes a link to the plan. See UI/VCS Runs: Speculative Plans on Pull Requests for more details.
With the CLI integration configured, running terraform plan on the command line starts a speculative plan. The plan output streams to the terminal, and a link to the plan is also included.
The runs API creates speculative plans whenever the specified configuration version is marked as speculative. See the configuration-versions API for more information.

Retry a speculative plan in the UI

If a speculative plan fails due to an external factor, you can run it again using the "Retry Run" button on its page:

Retrying a plan requires permission to queue plans for that workspace. (More about permissions.) Only failed or canceled plans can be retried.

Retrying the run will create a new run with the same configuration version. If it is a VCS-backed workspace, the pull request interface will receive the status of the new run, along with a link to the new run.

Saved Plans

Version note: Using saved plans from the CLI with HCP Terraform requires at least Terraform CLI v1.6.0.

HCP Terraform also supports saved plan runs. If you have configured the CLI integration you can use terraform plan -out <FILE> to perform and save a plan, terraform apply <FILE> to apply a saved plan, and terraform show <FILE> to inspect a saved plan before applying it. You can also create saved plan runs via the API by using the save-plan option.

Saved plan runs affect the run queue differently from normal runs, and can sometimes be automatically discarded. For more details, refer to Run Modes and Options: Saved Plans.

Planning Modes and Options

In addition to the normal run workflows described above, HCP Terraform supports destroy runs, refresh-only runs, and several planning options that can modify the behavior of a run. For more details, see Run Modes and Options.

Run States

HCP Terraform shows the progress of each run as it passes through each run state (pending, plan, policy check, apply, and completion). In some states, the run might require confirmation before continuing or ending; see Managing Runs: Interacting with Runs for more information.

In the list of workspaces on HCP Terraform's main page, each workspace shows the state of the run it's currently processing. (Or, if no run is in progress, the state of the most recent completed run.)

For full details about the stages of a run, see Run States and Stages.

Import

We recommend using import blocks, introduced in Terraform 1.5, to import resources in HCP Terraform.

HCP Terraform does not support remote execution for the terraform import command. For this command the workspace acts only as a remote backend for Terraform state, with all execution occurring on your own workstations or continuous integration workers.

Since terraform import runs locally, environment variables defined in the workspace are not available. Any environment variables required by the provider you're importing from must be defined within your local execution scope.