13.1 Create Infrastructure with HCP Terraform

13.1 Create Infrastructure with HCP Terraform

Quick Answer: Add a cloud block, run terraform login and terraform init, then start runs from VCS, the CLI, or the API. HCP Terraform stores that workspace's state and, unless you switch the execution mode to Local, performs plan and apply on remote workers. UI/VCS is the primary workflow. Do not put a backend block next to cloud.

Objective 8a on Terraform Associate (004) asks you to use HCP Terraform to create infrastructure. Product version on the exam is Terraform 1.12. Official references: What is HCP Terraform?, Connect to HCP Terraform, Remote operations, and Terraform Editions.

HashiCorp renamed the hosted product HCP Terraform. Older docs, blogs, and exam stems may still say Terraform Cloud. That is the same SaaS, not a second product. Use HCP Terraform as the current name after this mention.

Community, HCP Terraform, and Terraform Enterprise

004's audience must tell HashiCorp's editions apart. The official editions page lists three products, not three prices:

Do not invent dollar amounts or resource-hour rates on the exam. When a feature is edition-gated, HashiCorp's cloud-docs say so next to that feature. Community cannot "turn on Sentinel locally" and call it HCP Terraform. Enterprise is not Community with a bigger laptop.

Why a remote run exists

Community Terraform is a local workflow: the CLI on the machine that invoked it reads the working directory, talks to providers, and writes terraform.tfstate. That is enough for one engineer. A team needs a shared state file, a consistent Terraform version, an audit trail, and a place to approve applies. HCP Terraform is that remote workflow.

A workspace is the remote equivalent of a working directory. It holds the configuration version, the variable set used for the run, the state snapshot, and the run history. Every HCP run happens in a workspace. You cannot manage resources in HCP Terraform without at least one workspace.

By default HCP Terraform performs remote operations on disposable Linux VMs that it owns. You can instead attach HCP Terraform agents (a paid feature) so the same remote-operations contract runs on your private network. You can also set the workspace execution mode to Local, which turns the workspace into a remote state store only.

Remote execution is what unlocks Sentinel or OPA evaluation, cost estimation, run notifications, and VCS-driven applies. Local execution does not evaluate those features.

Three ways to start a run

HashiCorp documents three run workflows. They all produce a plan first, then (if allowed) an apply. They differ in who uploads the configuration and what is allowed to apply.

UI/VCS is the default you should picture first. Connecting a workspace to GitHub, GitLab, Bitbucket, or Azure DevOps registers a webhook. New commits on the workspace branch queue a run. Pull requests get a speculative (plan-only) run so reviewers can see the plan without changing infrastructure.

CLI-driven runs need Terraform 1.1+ for the cloud block (1.12 is well past that). Authenticate with terraform login (preferred) or credentials in the CLI config file. Then:

• terraform plan starts a speculative plan in the workspace. It works even on VCS-connected workspaces. It cannot apply.
• terraform apply starts a full remote plan-and-apply. HashiCorp allows this only when the workspace is not linked to a VCS repository. The repo is the source of truth; you apply VCS workspaces by merging.
• Saved plans (terraform plan -out then terraform apply <file>) need CLI 1.6+ and the same non-VCS rule.

API-driven workflow is for an orchestrator that can watch your code and call HCP Terraform. You upload a configuration version, create a run, and optionally apply. It is more flexible and more work. 004 does not ask you to memorize endpoint paths; it asks you to know the API is a first-class third workflow, not a secret back door around state.

A workspace queues runs. A new run stays pending until the current run finishes, because the current apply may change what the next plan would do. Speculative plans are the exception: they do not write state, so they can start without waiting.

The cloud block

The current way to point Terraform 1.12 at HCP Terraform is a cloud block inside terraform { }. It is not a backend block. You cannot combine cloud and backend.

terraform {
  cloud {
    organization = "my-org"
    hostname     = "app.terraform.io" # optional; this is the default

    workspaces {
      project = "networking-development" # optional
      tags = {
        layer  = "networking"
        source = "cli"
      }
    }
  }
}

Required pieces HashiCorp lists:

• organization — the HCP Terraform organization name.
• workspaces.name or workspaces.tags — pick one. name pins a single existing (or implicitly created) workspace. tags links the working directory to every workspace in the organization (and optional project) that matches those tags. If none match, terraform init can prompt you to create one.
• workspaces.project — optional project name so name/tag matching happens inside that project.
• hostname — optional. Default is app.terraform.io. Terraform Enterprise and HCP Europe use a different hostname.

Do not put an API token in the cloud block. Use terraform login.

After you add or change the block, run terraform init. If the working directory already has local or backend state, init migrates it. If the directory was using backend "remote", replace that block with cloud and keep the same workspace; the prefix argument does not exist on cloud (use tags, and select workspaces by their full HCP names).

CLI-driven remote plan/apply uploads the configuration directory. Add .terraformignore (gitignore syntax) at the root to exclude secrets or huge trees. If the file is missing, Terraform still skips .git/ and .terraform/ (except .terraform/modules).

Remote versus local execution

Local mode is how you keep using terraform plan on a workstation while the snapshot stays locked and versioned in HCP. The workspace still exists. Teammates still read the same state. You just gave up the hosted runner.

HCP Terraform does not remotely execute terraform import. Import (and several state-mutation commands) run locally against the workspace as a remote state store. Import blocks in configuration are the recommended 1.5+ / 1.12 path for bringing objects under management during a remote run.

Scenario: Priya ships the first VPC

Priya's org already has HCP Terraform. She writes a root module, adds a cloud block with organization = "acme" and workspaces { name = "net-prod-use1" }, runs terraform login and terraform init, and sets AWS credentials as workspace environment variables (not on her laptop). terraform plan streams a speculative plan from app.terraform.io. Because this workspace is CLI-driven (no VCS), terraform apply runs the plan remotely, stores state in net-prod-use1, and leaves a run URL her teammates can open. If she later connects the same workspace to GitHub, terraform apply from her laptop will be refused; merges become the apply path.

004 traps for objective 8a

• HCP Terraform is the current product name; Community is the CLI; Enterprise is self-hosted HCP Terraform.
• Three workflows: VCS (primary), CLI, API. All of them can create infrastructure; they are not mutually exclusive across an organization.
• cloud uses organization + workspaces.name or tags. There is no prefix on cloud.
• terraform plan against HCP is speculative. terraform apply is blocked on VCS-connected workspaces.
• State lives in the HCP workspace, even when execution is Local.
• cloud and backend cannot appear together.