Skip to content

Terraform Cloud

Terraform Cloud is a SaaS platform that helps teams collaborate effectively when using Terraform. It provides secure state management, workflows, policy controls, and collaboration features.

Key Features

  • Managed remote state storage
  • Full run history (plans, applies, logs)
  • State version history
  • Secure variable injection
  • Resource tagging
  • Run triggers (workspace chaining)
  • Per-workspace Terraform version selection
  • Global state sharing
  • Commenting on runs
  • Notifications (webhooks, email, Slack)
  • Organization and workspace-level RBAC
  • Policy as Code (Sentinel)
  • MFA
  • SSO (Business tier)
  • Cost estimation (Teams & Governance tier)
  • Integrations (ServiceNow, Splunk, Kubernetes, custom run tasks)

Terraform Cloud is available as a hosted service at app.terraform.io.

Terraform Cloud Terminology

I. Organization: A top-level container that groups workspaces.

II. Workspace: An isolated Terraform execution environment. Each workspace holds:

  • its own state
  • its own variables
  • its own runs
  • its own Terraform settings

A workspace always belongs to an organization.

III. Teams: Groups of users. Teams can be assigned to workspaces with specific permissions.

IV. Runs: A single execution of the Terraform workflow (plan → apply). Runs can be triggered via:

  • UI
  • VCS
  • API
  • CLI

Each run executes within one workspace.

Terraform Cloud – Run Workflows

When creating a workspace, you must choose one of these Run Workflows:

A. Version-Control Workflow (VCS-driven) (most common)

  • Terraform Cloud integrates with a VCS branch via webhooks.
  • Pull Requests → produce speculative plans.
  • Merges to the branch → trigger full runs.

B. CLI-Driven Workflow

  • Runs are initiated by users running Terraform CLI locally (authenticated via terraform login).

C. API-Driven Workflow

  • A third-party system uploads a configuration version (a .tar.gz bundle containing Terraform files) through the API to trigger runs.

Permissions

A. Organization-Level permissions define access to organization-wide settings:

  • Manage policies
  • Manage policy overrides
  • Manage workspaces
  • Manage VCS settings

Organization Owner is a special role with full access. Owners can:

  • Publish private modules
  • Invite users to the organization
  • Manage team membership
  • View all “secret” teams
  • Manage permissions, settings, billing
  • Delete the organization
  • Manage agents

B. Workspace-Level permissions control access for specific workspaces. Permission Models:

  • Granular permissions (fully customizable)
  • Premade permission sets: read, plan, write

Workspace Admin is a special role which grants all workspace permissions, plus the ability to:

  • Edit workspace settings
  • Assign/remove team permissions
  • Delete the workspace

API Tokens

Terraform Cloud supports Organization, Team, and User API tokens.

A. Organization Tokens

  • Apply to the entire organization
  • Only one active token at a time
  • Only org owners can create/revoke
  • Designed for automation that configures org/workspace structure

B. Team Tokens

  • Access limited to the workspaces that the team has permissions for
  • Only one active token per team
  • Any team member may generate/revoke
  • Used for workspace-level automation

C. User Tokens

  • Inherit the permissions of the user
  • Most flexible
  • Suitable for real users or service/machine accounts

Cost Estimation

Provides estimated monthly cloud costs alongside runs. Available at Teams & Governance tier and above but it supports only some resources from: AWS, Azure, GCP.

Terraform Cloud – Workflow Options

For each workspace, you have the option to choose:

  • any Terraform version
  • to share the state globally across your organization
  • auto-apply vs manual approval workflows

Migrating Local State to Terraform Cloud

To migrate an existing local project (using the default local workspace):

  1. Create a workspace in Terraform Cloud
  2. Update your Terraform configuration with a cloud backend
  3. Run terraform init and approve the state migration

VCS Integrations

Terraform Cloud supports the following VCS providers:

  • GitHub / GitHub OAuth / GitHub Enterprise
  • GitLab / GitLab EE / GitLab CE
  • Bitbucket Cloud / Bitbucket Server / Bitbucket Data Center
  • Azure DevOps Services
  • Azure DevOps Server

Terraform Cloud – Run Environment

Terraform Cloud executes runs in a single-use, ephemeral Linux VM/container (x86_64). Environment internals are not exposed.

Terraform Cloud automatically injects environment variables:

  • TFC_RUN_ID
  • TFC_WORKSPACE_NAME
  • TFC_WORKSPACE_SLUG
  • TFC_CONFIGURATION_VERSION_GIT_BRANCH
  • TFC_CONFIGURATION_VERSION_GIT_COMMIT_SHA
  • TFC_CONFIGURATION_VERSION_GIT_TAG

These can be used as Terraform variables:

variable "TFC_RUN_ID" {}

Run Triggers

Run Triggers allow chaining workspaces.

  • A workspace can depend on up to 20 source workspaces
  • When a source workspace completes a successful apply, dependent workspaces will automatically queue runs

Useful for multi-layer architectures (network → security → compute → applications).

Terraform Cloud Agents

A Business tier feature enabling Terraform Cloud to operate inside private, restricted, or on-prem environments.

Key characteristics:

  • Pull-based (no inbound connections required)
  • Linux x86_64 only
  • Can run inside Docker (using the official Terraform agent Docker image)
  • Supports Terraform 0.12+
  • System requirements: 4 GB disk, 2 GB RAM
  • Agents must have HTTPS outbound access to:
  • app.terraform.io
  • registry.terraform.io
  • releases.hashicorp.com
  • archivist.terraform.io

Terraform Enterprise (TFE)

Terraform Enterprise is the self-hosted version of Terraform Cloud. Benefits:

  • No resource limits
  • Full audit logging
  • Enterprise-grade SSO
  • Complete data control
  • Air-gapped (isolated with no public internet access) installation support

Operational Modes (how data is stored)

A. External Services mode: uses an external PostgreSQL DB and an external storage (e.g., S3)

B. Mounted Disk mode: stores data on a mounted external disk (e.g., EBS)

C. Demo Mode: All data stored locally but this is suitable only for testing (not production)

Requirements

  • Valid Terraform Enterprise license
  • TLS certificate + private key
  • Enterprise-grade Linux machine (Debian, Ubuntu, RHEL, CentOS, Amazon Linux, Oracle Linux)