Module 8: HCP Terraform

Lesson 8.3: Integration and Run Workflows

Authenticating the CLI

Shell
terraform login                   # defaults to app.terraform.io
terraform login app.eu.terraform.io   # or another hostname, such as a Terraform Enterprise instance
  • terraform login opens a browser to create an API token and saves it to ~/.terraform.d/credentials.tfrc.json.
  • In automation, use the environment variable TF_TOKEN_app_terraform_io. Replace the dots in the hostname with underscores.
  • terraform logout removes the saved token.

The cloud block

HCL
terraform {
  cloud {
    organization = "acme-corp"

    workspaces {
      name = "web-dev" # one specific workspace
    }
  }
}
HCL
terraform {
  cloud {
    organization = "acme-corp"

    workspaces {
      tags = ["app:web"] # any workspace with this tag; switch with terraform workspace select
    }
  }
}

Rules for the cloud block:

  • It goes inside the terraform block. It replaces a backend block, so you can't have both.
  • hostname defaults to app.terraform.io.
  • The cloud block is preferred over the legacy backend "remote".
  • Running terraform init after adding the block offers to migrate existing state into the workspace. It creates the workspace if it doesn't exist.
  • With tags, the terraform workspace commands list and select the matching HCP Terraform workspaces. terraform workspace new creates a workspace carrying those tags.
  • Since 1.10, tags can also be a map of key-value tags. This course uses the list form (flagged).
  • Environment variables such as TF_CLOUD_ORGANIZATION, TF_CLOUD_HOSTNAME, and TF_WORKSPACE can supply settings, which allows a partially empty cloud {} block.

Three run workflows

Workflow How runs start Notes
VCS-driven The workspace is connected to a repo and branch. A push to the branch queues a plan. A pull request gets a speculative plan posted as a status check. Apply happens after a manual "Confirm & Apply" in the UI, or automatically if auto-apply is on. You can't run terraform apply from the CLI against a VCS-connected workspace.
CLI-driven terraform plan or apply on your machine uploads the configuration and streams the remote run's output to your terminal terraform plan from the CLI produces a speculative plan. Ctrl-C stops streaming, but the run continues remotely.
API-driven A pipeline uploads a configuration version (a tarball) and creates runs through the API Used for custom CI/CD integrations

Execution modes (a workspace setting)

Mode Where Terraform runs State
Remote (default) On HCP Terraform-managed workers HCP Terraform
Local On your machine, as normal CLI HCP Terraform, used only as a state backend
Agent On self-hosted HCP Terraform agents inside your network (check your plan) HCP Terraform

With remote execution, the run can't see your laptop:

  • Local environment variables aren't available.
  • Credential files aren't available.
  • Local services such as a Docker socket or an on-premises API aren't reachable.

Supply credentials as workspace variables (preferably dynamic provider credentials), or use agents for private networks.

The run pipeline

Text
Pending → Plan → Cost estimation (if enabled) → Policy check → (Confirm) → Apply → Applied

Run tasks can hook in at the pre-plan, post-plan, pre-apply, and post-apply stages. Speculative plans stop after policy checks and can never be applied.