Terraform Workspaces Explained: CLI vs Cloud for Ops and the Exam

“Workspace” in Terraform is a single word with two very different meanings. In the CLI it manages multiple states against the same config; in Cloud/Enterprise it is a fully independent execution unit.

Picking the wrong one when designing environment separation or permissions can lead to state collisions and permission gaps. This article walks through how to use each correctly, with diagrams, a comparison table, and command examples.

Terminology: CLI and Cloud Workspaces Are Different Things

A CLI workspace switches the state file used against a single Terraform config in a single directory. In other words: one config, multiple states. State names are separated locally or on the backend.

A Terraform Cloud/Enterprise (TFC/E) workspace is an “execution unit” that bundles VCS integration, variable scope, run history, roles/permissions, and policy enforcement. Each workspace typically has its own state and execution pipeline.

• CLI: switches state against a single config. Useful for small environment differences.
• TFC/E: a fully managed execution unit built for organization and team workflows. Tightly coupled with VCS triggers, queueing, and permissions.

Basic CLI workspace commands (works with local or any backend)

terraform workspace list
terraform workspace new dev
terraform workspace select dev
terraform plan -var-file=vars/dev.tfvars
terraform apply

CLI Workspaces: Where to Use Them and What to Avoid

CLI workspaces are a fit when you want to apply the same config while switching state. A good example is lightweight environment separation (dev, test, qa) where the configs barely differ in behavior.

On the other hand, papering over environments with very different variables, provider settings, or module compositions using only CLI workspaces is risky. Human error around applying to the wrong workspace and complex conditional branches kill readability and breed review misses.

• Good fit: small environment differences, namespace separation within the same region, PoCs.
• Avoid: large environment diffs, production workloads needing strong access control, multi-region or multi-account setups.

CLI workspaces and backend state naming (S3 backend example)

terraform {
  backend "s3" {
    bucket = "example-tfstate"
    key    = "projectA/terraform.tfstate"   # 実際は workspace 名で分岐されることに注意
    region = "ap-northeast-1"
  }
}
# ワークスペース名をキーに含めるには、backend の機能や規約で設計（例: key に workspace を埋め込む命名規約）

Terraform Cloud/Enterprise Workspaces: The Unit of Execution and Governance

A TFC/E workspace bundles everything you need to manage runs: VCS branch integration, variable and secret scope, plan/apply queues, roles and policies, plus state sharing and output references (run tasks and DRY design).

Cross-workspace integration is done safely via shared variables and output references (such as the remote state data source or TFC/E's built-in integrations). Avoid manually shuttling state files between workspaces.

• VCS integration: standardize a review flow where push triggers plan and approval triggers apply.
• RBAC and Policy: enforce team-level permissions and guardrails on a per-workspace basis.

Connecting to TFC/E (cloud block; variables managed in TFC/E)

terraform {
  cloud {
    organization = "your-org"
    workspaces {
      name = "projectA-prod"
    }
  }
}
# remote backend でも可。資格試験では、TFC/E workspace が state・実行・権限の単位である点を押さえる。

The Core Differences: Variables, Execution, Locking, Permissions (Comparison Table)

Here are the differences that matter in day-to-day operations. On the exams in particular, confusing the CLI and TFC/E meanings of “workspace” is a very common trap.

The table below captures the points to remember for both design decisions and exam prep.

• Classic exam question: “CLI workspaces do not bundle multiple configs together.”
• In practice: “If you need access control and audit, separate environments with TFC/E workspaces” is the baseline rule.

How workspaces and state relate in CLI vs TFC/E

Execution differences (CLI is manual; TFC/E uses a queue plus approvals)

# CLI: 手動で実行
terraform plan
terraform apply

# TFC/E: VCS 連携（例）
# - main ブランチに PR -> Plan 作成
# - 承認者が Apply を承認 -> 実行
# API/手動トリガーも可（詳細は TFC/E の Run キュー挙動に依存）

Environment Separation Strategy: Picking Between Directories, CLI Workspaces, and TFC/E Workspaces

The big question is what you split on. If the diff is large, split with directories or repos. If you need strong permissions and audit, split with TFC/E workspaces. If the diff is small and the same config works, switch lightly with CLI workspaces.

Set up naming conventions that bake the workspace name into resource names and backend keys, and pair them with pre-commit hooks, visible plan output, and an approval flow to prevent misapplies.

• Large diff (very different region/account/provider settings): split by directory inside a monorepo, or by separate repos.
• Medium diff (same structure but permissions and audit required): split TFC/E workspaces per environment.
• Small diff (just tags or sizes): switch with CLI workspaces and tfvars.

Naming convention example (reflecting the workspace name)

locals {
  ws = terraform.workspace
}

resource "aws_s3_bucket" "app" {
  bucket = "app-${local.ws}"
  tags = {
    env = local.ws
  }
}
# 注意: terraform.workspace は CLI/TFC/E 双方で有効だが、命名衝突や容量制限を考慮すること

Exam Prep and Operational Pitfall Checklist

On the Associate and Pro exams, “CLI workspaces are a state-switching mechanism and do not provide full environment isolation or RBAC” shows up constantly. Also memorize that “TFC/E workspaces are the unit for runs, variables, and permissions, and include VCS integration and queueing.”

In production, watch out for ops flows getting tangled because the same word means different things. Even when using CLI and TFC/E together, make the responsibility split explicit: who applies and approves, where, and how.

• Prevent misapplies: surface the workspace name, embed it in resource names, enforce protected branches and required reviews.
• Avoid state collisions: lean on a lock-capable backend and the TFC/E run queue.

Commonly used verification commands

# 現在のワークスペース確認（CLI）
terraform workspace show

# 変数の優先度確認（計画時の -var-file と環境変数）
terraform plan -var-file=vars/prod.tfvars

# TFC/E: 実行は UI/API が中心（CLI は cloud ブロック経由で送信）

Check Your Understanding

Frequently Asked Questions