HashiCorp : Terraform Cloud
Advanced Topics
Demo Terraform Cloud Run Agents
In this guide, we’ll walk through setting up Terraform Cloud’s self-hosted agents—a Business tier feature that allows Terraform runs to execute within your private network. By using agents, you eliminate the need to expose sensitive endpoints publicly, making them ideal for on-premises data centers, private VPCs, or any environment where Terraform Cloud cannot directly reach your infrastructure.
Table of Contents
- Prerequisites
- Creating an Agent Pool and Token
- Installing and Running an Agent on Linux
- Running an Agent in Docker
- Agent Auto-Update Behavior
- Configuring a Workspace for Agent Execution
- Running Terraform via the Agent
- Scaling with Multiple Agents
- Managing Pools and Tokens
- References
Prerequisites
- A Terraform Cloud organization on the Business tier
- Permissions to manage Settings → Agents
- Outbound TCP/443 connectivity to
app.terraform.io
Note
Agents use a pull-based model and require only outbound TCP/443 access to Terraform Cloud.
Creating an Agent Pool and Token
An Agent Pool is a logical group of self-hosted agents. You scope pools to environments (e.g., development
, production
) and assign tokens for authentication.
Component | Description | Example Command |
---|---|---|
Agent Pool | Logical grouping of agents | Manage under Settings → Agents |
API Token | Scoped to one pool; used by each registered agent | Created via the Create token button |
Agent Name | Unique identifier for each host/container | east-dc-1 , us-west-2 |
- Navigate to Settings → Agents in your Terraform Cloud organization.
- Click New Agent Pool, name it (e.g., development), and save.
- In the pool’s page, click Create token, scope it to your data center or environment (e.g.,
EastDC
), and copy the value.
Warning
Keep your agent tokens confidential. Rotate or revoke tokens regularly to maintain security.
Installing and Running an Agent on Linux
Download and unzip the latest agent binary on any Linux host:
# Replace with the current stable version if newer
curl -Lo tfc-agent_1.3.1_linux_amd64.zip \
https://releases.hashicorp.com/tfc-agent/1.3.1/tfc-agent_1.3.1_linux_amd64.zip
unzip tfc-agent_1.3.1_linux_amd64.zip
Set environment variables and start the agent:
export TFC_AGENT_TOKEN=<your_agent_pool_token>
export TFC_AGENT_NAME=east-dc-1
./tfc-agent
On launch, you’ll see a registration confirmation:
2022-10-05T12:14:31.806Z [INFO] core: Agent registered successfully with Terraform Cloud: agent.name=east-dc-1
Running an Agent in Docker
Alternatively, launch an agent as a Docker container:
export TFC_AGENT_TOKEN=<your_agent_pool_token>
export TFC_AGENT_NAME=east-dc-2
docker run -e TFC_AGENT_TOKEN -e TFC_AGENT_NAME hashicorp/tfc-agent:latest
This pulls the latest
image, auto-updates its core if enabled, and registers to your specified pool.
Agent Auto-Update Behavior
Agents check for newer core versions by default. Sample logs:
2022-10-05T12:14:30.066Z [INFO] agent: Core update is available: version=1.4.0
2022-10-05T12:14:31.061Z [INFO] agent: Core successfully updated: version=1.4.0
To manage updates manually, disable auto-updates under Settings → Agents → [Your Pool].
Configuring a Workspace for Agent Execution
- Go to Workspaces → [Your Workspace] in Terraform Cloud.
- Under Settings → Execution Mode, select Agent.
- Choose your development pool and save.
Running Terraform via the Agent
Trigger a run in the workspace. The agent logs will indicate progress:
2022-10-05T12:18:38.117Z [INFO] core: Job received: job.type=plan job.id=run-XXXXX
2022-10-05T12:19:38.105Z [INFO] terraform: Terraform CLI details: version=1.2.7
2022-10-05T12:19:38.717Z [INFO] terraform: Running terraform init
2022-10-05T12:19:48.210Z [INFO] terraform: Running terraform plan
Back in the UI, you’ll see the plan complete:
When changes are pushed, the agent will perform apply
as well:
Scaling with Multiple Agents
To increase throughput, register additional agents to the same pool. Your Terraform Cloud license determines the maximum concurrent agents.
Managing Pools and Tokens
- Create multiple tokens per pool or assign one per agent.
- Rotate or revoke tokens under Settings → Agents → [Your Pool] → Tokens.
- Delete agents or pools when no longer in use—ensure they aren’t linked to active workspaces.
Terraform Cloud Agents enable secure, scalable execution of Terraform runs within your network perimeter, giving you full control over connectivity and resources.
References
Watch Video
Watch video content