• HashiCorp Developer

  • HashiCorp Cloud Platform
  • Terraform
  • Packer
  • Consul
  • Vault
  • Boundary
  • Nomad
  • Waypoint
  • Vagrant
Terraform
  • Install
  • Tutorials
    • About the Docs
    • Configuration Language
    • Terraform CLI
    • Terraform Cloud
    • Terraform Enterprise
    • CDK for Terraform
    • Provider Use
    • Plugin Development
    • Registry Publishing
    • Integration Program
  • Registry(opens in new tab)
  • Try Cloud(opens in new tab)
  • Sign up
Terraform Home

Terraform Cloud

Skip to main content
  • Terraform Cloud

  • Overview
  • Plans and Features
  • Getting Started
    • Remote Operations
    • Viewing and Managing Runs
    • Run States and Stages
    • Run Modes and Options
    • UI/VCS-driven Runs
    • API-driven Runs
    • CLI-driven Runs
    • The Run Environment
    • Installing Software
  • Migrating to Terraform Cloud

  • Terraform Cloud Agents

  • Resources

  • Tutorial Library
  • Certifications
  • Community Forum
    (opens in new tab)
  • Support
    (opens in new tab)
  • GitHub
    (opens in new tab)
  • Terraform Registry
    (opens in new tab)
  1. Developer
  2. Terraform
  3. Terraform Cloud
  4. Terraform Runs
  5. The Run Environment

»Terraform Cloud's Run Environment

Terraform Cloud is designed as an execution platform for Terraform, and most of its features are based around its ability to perform Terraform runs in a fleet of disposable worker VMs. This page describes some features of the run environment for Terraform runs managed by Terraform Cloud.

The Terraform Worker VMs

Terraform Cloud performs Terraform runs in single-use Linux virtual machines, running on an x86_64 architecture.

The operating system and other software installed on the worker VMs is an internal implementation detail of Terraform Cloud. It is not part of a stable public interface, and is subject to change at any time.

Before Terraform is executed, the worker VM's shell environment is populated with environment variables from the workspace, the selected version of Terraform is installed, and the run's Terraform configuration version is made available.

Changes made to the worker during a run are not persisted to subsequent runs, since the VM is destroyed after the run is completed. Notably, this requires some additional care when installing additional software with a local-exec provisioner; see Installing Additional Tools for more details.

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

Network Access to VCS and Infrastructure Providers

In order to perform Terraform runs, Terraform Cloud needs network access to all of the resources being managed by Terraform.

If you are using the SaaS version of Terraform Cloud, this means your VCS provider and any private infrastructure providers you manage with Terraform (including VMware vSphere, OpenStack, other private clouds, and more) must be internet accessible.

Terraform Enterprise instances must have network connectivity to any connected VCS providers or managed infrastructure providers.

Concurrency and Run Queuing

Terraform Cloud uses multiple concurrent worker VMs, which take jobs from a global queue of runs that are ready for processing. (This includes confirmed applies, and plans that have just become the current run on their workspace.)

If the global queue has more runs than the workers can handle at once, some of them must wait until a worker becomes available. When the queue is backed up, Terraform Cloud gives different priorities to different kinds of runs:

  • Applies that will make changes to infrastructure have the highest priority.
  • Normal plans have the next highest priority.
  • Speculative plans have the lowest priority.

Terraform Cloud can also delay some runs in order to make performance more consistent across organizations. If an organization requests a large number of runs at once, Terraform Cloud queues some of them immediately, and delays the rest until some of the initial batch have finished; this allows every organization to continue performing runs even during periods of especially heavy load.

State Access and Authentication

Terraform Cloud stores state for its workspaces.

When you trigger runs via the CLI workflow, Terraform reads from and writes to Terraform Cloud's stored state. Terraform Cloud uses the cloud block for runs, overriding any existing backend in the configuration.

Note: The cloud block is available in Terraform v1.1 and later. Previous versions can use the remote backend to configure the CLI workflow and migrate state.

Autogenerated API Token

Instead of using existing user credentials, Terraform Cloud generates a unique per-run API token and provides it to the Terraform worker in the CLI config file. When you run Terraform on the command line against a workspace configured for remote operations, you must have the cloud block in your configuration and have a user or team API token with the appropriate permissions specified in your CLI config file. However, the run itself occurs within one of Terraform Cloud's worker VMs and uses the per-run token for state access.

The per-run token can read and write state data for the workspace associated with the run, can download modules from the private registry, and may be granted access to read state from other workspaces in the organization. (Refer to cross-workspace state access for more details.) Per-run tokens cannot make any other calls to the Terraform Cloud API and are not considered to be user, team, or organization tokens. They become invalid after the run is completed.

User Token

Terraform Cloud uses the user token to access a workspace's state when you:

  • Run Terraform on the command line against a workspace that is not configured for remote operations. The user must have permission to read and write state versions for the workspace.

  • Run Terraform's state manipulation commands against a Terraform Cloud workspace. The user must have permission to read and write state versions for the workspace.

Refer to Permissions for more details about workspace permissions.

Environment Variables

Terraform Cloud automatically injects the following environment variables for each run:

Variable NameDescriptionExample
TFC_RUN_IDA unique identifier for this run.run-CKuwsxMGgMd4W7Ui
TFC_WORKSPACE_NAMEThe name of the workspace used in this run.prod-load-balancers
TFC_WORKSPACE_SLUGThe full slug of the configuration used in this run. This consists of the organization name and workspace name, joined with a slash.acme-corp/prod-load-balancers
TFC_CONFIGURATION_VERSION_GIT_BRANCHThe name of the branch that the associated Terraform configuration version was ingressed from.main
TFC_CONFIGURATION_VERSION_GIT_COMMIT_SHAThe full commit hash of the commit that the associated Terraform configuration version was ingressed from.abcd1234...
TFC_CONFIGURATION_VERSION_GIT_TAGThe name of the tag that the associated Terraform configuration version was ingressed from.v0.1.0

They are also available as Terraform input variables by defining a variable with the same name. For example:

variable "TFC_RUN_ID" {}
Edit this page on GitHub

On this page

  1. Terraform Cloud's Run Environment
  2. The Terraform Worker VMs
  3. Network Access to VCS and Infrastructure Providers
  4. Concurrency and Run Queuing
  5. State Access and Authentication
Give Feedback(opens in new tab)
  • Certifications
  • System Status
  • Terms of Use
  • Security
  • Privacy
  • Trademark Policy
  • Trade Controls
  • Give Feedback(opens in new tab)