Collaborate with Terraform Cloud

You’ve mastered Terraform on your local machine: state files, modules, workspaces — all running happily in a single terminal. But the moment a teammate runs terraform plan against the same state, everything starts to break. The pain is real: state file conflicts, out-of-date plans, and the terrifying question, “Who changed the infrastructure last night?” This lesson introduces Terraform Cloud basics and shows you how to collaborate with Terraform Cloud — turning infrastructure management from a solo act into a team sport without the usual chaos.

The problem this lesson solves

Local-only Terraform workflows don’t scale beyond one person. The state file — the single source of truth for your infrastructure — lives on your laptop or a shared drive, and that’s a recipe for disaster. Here’s what happens when you collaborate without a proper backend:

• State file conflicts: Two teammates run terraform apply at the same time; the second overwrites the first’s changes, and resources drift silently.
• No audit trail: You have no idea who changed what, when, or why — unless someone remembers to update a changelog.
• Secret sprawl: Variables like API keys and database passwords sit in plain text in terraform.tfvars files, passed around via chat or email.
• Terraform Cloud basics solves these problems by centralizing state, locking it during operations, and providing role-based access control.

Without a remote collaboration layer, your team will eventually hit a destructive apply that nobody can explain. Terraform Cloud is the managed answer — but the basics are what you need before you can trust it.

Pro tip: If you’re a solo developer, you might think this lesson isn’t for you. But Terraform Cloud’s free tier gives you the same benefits — remote state, automatic locking, and a clean UI to inspect plans — even if you only ever deploy from your own machine.

Core concept / mental model

Think of Terraform Cloud as a conductor for your infrastructure orchestra. Each musician (teammate) plays their part, but the conductor ensures everyone is in sync: they give the cue to play, they hold up a hand to stop, and they keep the score (the state) so no one loses their place.

In technical terms, Terraform Cloud is a managed service that provides:

• Remote state storage — your terraform.tfstate lives in a secure, versioned bucket in the cloud, not on your hard drive.
• Remote operations — terraform plan and terraform apply run in Terraform Cloud’s infrastructure, not locally. This means your local machine just sends the configuration; the heavy lifting and state updates happen centrally.
• State locking — whenever an operation runs, Terraform Cloud locks the state. Other operations queue up and wait, preventing nearly all “thundering herd” corruption.
• Workspaces and teams — you organize environments (dev, staging, prod) as workspaces, and assign team members with roles (read, write, plan, apply) to control who can do what.

Here’s a mental diagram in words:

Your local machine  +  Teammate’s machine  +  CI/CD pipeline
         |                    |                       |
         +-----------+--------+-----------------------+--+
                     |                                    |
              Terraform Cloud API                        |
                     |                                    |
              +------+--------+                           |
              |  State file  |<----locks during ops-------+
              +-------------+

Terraform Cloud doesn’t replace your code — it replaces the fragile parts: state handling and execution. You still write your .tf files in Git; you still run terraform plan (though it may execute remotely); but now the state is shared, safe, and audited.

Definition: Terraform Cloud basics refers to the minimal setup to start collaborating: creating an account, configuring a workspace, connecting your repository (or local files), and moving remote state. No advanced features like Sentinel or run triggers — just the essentials.

How it works step by step

The flow to collaborate with Terraform Cloud is straightforward, but each step has a purpose. Here’s the logical sequence:

1. Create a Terraform Cloud account (app.terraform.io) and an organization. The organization groups your workspaces and teams.
2. Create a workspace — a workspace maps to a specific set of infrastructure (e.g., prod-aws, dev-vpc). You can connect it to a VCS repo or start from CLI-driven run.
3. Define variables — both Terraform variables and environment variables (like AWS_ACCESS_KEY_ID) are stored encrypted in Terraform Cloud, never in your code.
4. Run an initial operation — either by pushing to your connected repo, or by running terraform remote commands locally on CLI-driven runs.
5. Lock the state automatically — during every plan/apply, Terraform Cloud locks the state; other runs queue up.
6. Review and apply — team members with the right permissions review the plan in the UI and approve the apply.

Key takeaway: from a code perspective, you don’t change much. You add a cloud block to your configuration (or set the backend), and Terraform Cloud handles the rest.

Hands-on walkthrough

Let’s go from zero to a working collaboration setup using the CLI-driven workflow — the simplest way to try Terraform Cloud without hooking up a Git repo.

Prerequisites

• Terraform CLI v1.1 or later
• A Terraform Cloud account (free tier is fine)
• An AWS account (or any provider) with credentials for your test infrastructure

Step 1: Create your organization and workspace

1. Log in to app.terraform.io, create an organization named my-org (or any unique name).
2. Create a workspace, choose CLI-driven run as the workflow, and name it dev.
3. Note the workspace name — you’ll use it in your code.

Step 2: Configure your Terraform code

Create a directory and add a main.tf with a minimal configuration. Instead of defining a backend, use the cloud block:

terraform {
  required_version = ">= 1.1.0"

  cloud {
    organization = "my-org"
    workspaces {
      name = "dev"
    }
  }
}

provider "aws" {
  region = "us-east-1"
}

resource "aws_s3_bucket" "example" {
  bucket = "tfc-basics-bucket-${random_string.suffix.result}"
}

resource "random_string" "suffix" {
  length  = 8
  special = false
  upper   = false
}

Notice you don’t need a backend "remote" and workspaces { name = ... } separately — the cloud block is the modern way. After this change, any terraform command automatically uses Terraform Cloud’s remote state.

Step 3: Initialize and authenticate

Run the following commands in your terminal:

export TF_CLOUD_ORGANIZATION="my-org"
terraform login

The login command opens a browser to generate an API token. Paste it back into the terminal to authenticate. Then run terraform init to connect to your workspace:

terraform init

Expected output:

Initializing Terraform Cloud...
Successfully configured the backend "cloud"!
Terraform has been successfully initialized!

Step 4: Run a plan and apply

Now run a plan locally — but note that the plan executes in Terraform Cloud:

terraform plan

You’ll see a URL where the plan is viewable in the web UI. Approve it by running:

terraform apply -auto-approve

Expected output (truncated):

Running apply in Terraform Cloud. Output will stream here.
...
Apply complete! Resources: 2 added, 0 changed, 0 destroyed.

At this point, your terraform.tfstate is in Terraform Cloud, locked during the apply, and shared with anyone in your organization.

Pro tip: Check the Runs tab in the Terraform Cloud UI. You’ll see a history of runs with metadata (who, when, what changed). That’s your audit trail.

Compare options / when to choose what

When you collaborate with Terraform Cloud, you have two main ways to trigger runs. Here’s a comparison:

When to choose: If you’re just starting your Terraform Cloud basics journey, start with CLI-driven to learn the concept. Move to VCS-driven when you want plan-on-PR and auto-apply on merge — the foundation of Infrastructure as Code collaboration.

Another comparison: Terraform Cloud vs. an open-source remote backend like an S3 backend with DynamoDB locking. Terraform Cloud adds a UI, audit logs, and role-based access control out of the box, but if you’re deeply invested in AWS and want self-managed, the S3 backend works. For a team, Terraform Cloud’s convenience often outweighs the cost (free for up to 5 users).

Troubleshooting & edge cases

Here are the pitfalls you’ll hit with collaborate with terraform cloud basics, and how to solve them:

• Error: “Failed to query available provider packages” — Usually this means your cloud block points to a workspace that hasn’t been created, or your token lacks permissions. Double-check your organization name and workspace name — typo’s are the #1 cause.
• “Backend initialization required: please run "terraform init"” — You changed the cloud block after writing configuration. Re-run terraform init to reinitialize.
• Local state still present — After switching to the cloud block, your old local terraform.tfstate becomes orphaned. Use terraform state push only if you’re sure you want to migrate; otherwise leave it as a backup.
• Secret variables are visible in plan logs — Terraform Cloud masks variables marked as sensitive, but terraform plan shows values if they’re used in resource arguments. Mark them as sensitive and avoid printing values.
• Permission denied when approving runs — Terraform Cloud roles separate read vs. write. Ensure the person approving has “Apply” permission; otherwise they can only comment.
• Slow CLI-driven runs — The plan runs remotely, so network latency and queue time matter. If you have frequent changes, the VCS-driven workflow feels faster because it’s automated.

Edge case: If you connect a Git repo, Terraform Cloud uses the repo’s default branch to trigger plans. Accidentally pushing to main might trigger an apply you didn’t want — configure “apply manually” in the workspace settings to require human approval.

What you learned & what's next

In this lesson, you mastered the essentials of collaborate with terraform cloud basics: you created an organization and workspace, configured the cloud block, ran remote plans/applies, and learned how to pick between CLI-driven and VCS-driven workflows. You can now explain the core idea — remote state, locking, and centralized execution — and you’ve completed a practical exercise that proves your setup works.

Now that you can collaborate safely, the next step is to make your runs smarter: automate with Terraform Cloud’s run triggers and Sentinel policies — turning manual approvals into guardrails that enforce your team’s standards. With these basics, you’re ready to build a deployment pipeline that scales with your team.