Terraform Cloud Plugin

The Terraform Cloud plugin provides workspace visualization and run management for Terraform Cloud organizations.

Overview

Property	Value
Package	@internal/plugin-terraform-cloud
Type	Frontend
Plugin ID	terraform-cloud
Backend	terraform-cloud-backend

Architecture

Components

TerraformCloudPage

Main page for Terraform Cloud integration.

<TerraformCloudPage />

Features:

• Organization selection
• Workspace browser
• Run history and status

WorkspaceList

Lists workspaces in an organization.

<WorkspaceList organization="my-org" onWorkspaceSelect={handleSelect} />

Features:

• Search and filter
• Status indicators
• Resource counts

WorkspaceDetail

Detailed workspace information.

<WorkspaceDetail organization="my-org" workspaceName="my-workspace" />

Features:

• Current state version
• Variables and outputs
• Run triggers

RunList

Lists runs for a workspace.

<RunList workspaceId="ws-xxxxx" onRunSelect={handleSelect} />

Features:

• Run status badges
• Plan/apply details
• Cost estimates

API Client

interface TerraformCloudApi {
  // Organizations
  listOrganizations(): Promise<Organization[]>;

  // Workspaces
  listWorkspaces(organization: string): Promise<Workspace[]>;
  getWorkspace(organization: string, name: string): Promise<Workspace>;

  // Runs
  listRuns(workspaceId: string): Promise<Run[]>;
  getRun(runId: string): Promise<Run>;

  // State
  getCurrentStateVersion(workspaceId: string): Promise<StateVersion>;
}

Workspace States

Run Status Indicators

Status	Color	Description
pending	Gray	Run queued
planning	Blue	Plan in progress
planned	Yellow	Plan complete, awaiting
applying	Blue	Apply in progress
applied	Green	Successfully applied
errored	Red	Run failed
discarded	Gray	Run cancelled

Configuration

# app-config.yaml
terraformCloud:
  apiUrl: https://app.terraform.io/api/v2 # or your TFE URL

TypeScript Config Schema

// config.d.ts
export interface Config {
  terraformCloud?: {
    /**
     * Terraform Cloud API URL
     * @default https://app.terraform.io/api/v2
     */
    apiUrl?: string;
  };
}

Token Resolution

Tokens are resolved from Vault in this priority:

1. Organization-specific token: groups/{group}/tfc-{org-name}
2. Generic TFC token with org key: groups/{group}/tfc-token[org-name]
3. Default TFC token: groups/{group}/tfc-token

Related Documentation

• Terraform Cloud Backend - Backend API
• Terraform State Backend - State management
• Plugins Overview