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.
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.
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.
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.
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.
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.
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, 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.
When a workspace is locked, Terraform Cloud 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).
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 use the following methods to initiate Terraform Cloud runs:
- Click the + New run button on the workspace's page
- Implement VCS webhooks
- Run the standard
terraform applycommand when the CLI integration is configured
- Call the Runs API using any API tool
Terraform Cloud 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, 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.)
If a plan contains no changes, Terraform Cloud 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.
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 planon 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-versionsAPI for more information.
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.
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.
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.
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.
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.