Remote Operations

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

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

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

Terraform Cloud 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 Terraform Cloud are called remote operations. Remote runs can be initiated by webhooks from your VCS provider, by UI controls within Terraform Cloud, 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 Terraform Cloud'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

Terraform Cloud Agents are a paid feature that allows Terraform Cloud to communicate with isolated, private, or on-premises infrastructure. The agent polls Terraform Cloud 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.

Terraform Cloud 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

Terraform Cloud 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, Terraform Cloud 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 Terraform Cloud 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 — Terraform Cloud 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.

When you initiate a run, Terraform Cloud 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, new runs can be queued (automatically or manually) but no new runs can begin until the workspace is unlocked.

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

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

Terraform Cloud 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 Terraform Cloud.

You can initiate Terraform Cloud runs through the manual Start new run action in the workspace actions menu, VCS webhooks, the standard terraform apply command (with the CLI integration configured), and the Runs API (or any tool that uses that API).

Plans and Applies

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

In the default configuration, Terraform Cloud 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.)

Speculative Plans

In addition to normal runs, Terraform Cloud can also run speculative plans, to test changes to a configuration during editing and code review.

Speculative plans are plan-only runs: they show a set of possible changes (and check them against Sentinel policies), but cannot apply those changes. They can begin at any time without waiting for other runs, since they don't affect real infrastructure. Speculative plans do not appear in a workspace's list of runs; viewing them requires a direct link, which is provided when the plan is initiated.

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.

Planning Modes and Options

In addition to the normal run workflows described above, Terraform Cloud 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

Terraform Cloud 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 Terraform Cloud'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 Terraform Cloud.

Terraform Cloud 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.