Intro to Terraform Cloud Agents

HashiCorp Terraform Cloud gives you a new option to decide where to run Terraform operations thanks to new self-hosted agents. The new per-workspace agent execution mode allows private environments to continue taking advantage of Terraform Cloud’s management interface without modifying ingress network traffic access. The agents securely connect back to Terraform Cloud, retrieve any work needing to be completed, apply the changes, and return the results back to Terraform Cloud. These agents are available as part of the Terraform Cloud Business tier.

Terraform Cloud Agents Configuration

The transition to using Terraform Cloud Agents is nearly seamless. Whether agents will be used with one or several of your workspaces, there are a couple of configuration areas to know about. The first area has to do with agent pools. These pools are how you can separate the isolated, private, or on-premises environments where the agents will be deployed. Pools can be created in the Organization Settings’ Agents sub-section.

The next area will be token management for each pool. The token is used to authenticate agents to Terraform Cloud. Tokens can be created for each agent or for all the agents in the pool. Each agent only uses one token, but a pool can have as many as your configuration requires. These tokens can also be revoked and recreated at any point in the individual Agent Pool view.

After generating a token, you’re given the token and some helpful sample code to deploy an agent into the desired environment using that token. The deployment can be performed in one of two ways, either as a container image or a binary for use on 64-bit Linux operating systems. For resiliency, we recommend pairing your agent containers with an agent supervisor such as HashiCorp Nomad, Kubernetes, or similar workload orchestrators.

The following sample code will assign the environmental variables then deploy the container image:

export TFC_AGENT_TOKEN= < agent_token >
export TFC_AGENT_NAME= < agent_name >
docker run -e TFC_AGENT_TOKEN -e TFC_AGENT_NAME hashicorp/tfc-agent:latest

Alternatively you could also deploy several agents with the use of a workload orchestrator, like HashiCorp Nomad, with the following code sample:

job "tfcagent" {
    datacenters = ["dc1"]
    group "tfcagent_tmmorg" {
      network {
          mode = "bridge"
    }
  
      count = 2
      task "tfcagent_tpmmorg" {
        driver = "docker"
        
        env {
          TFC_AGENT_TOKEN             = "<agent_token>"
          TFC_AGENT_NAME              = "<agent_name>"
      }
        
        config {
          image = "hashicorp/tfc-agent:latest"
      }
    }
  }
}

Once agents have been deployed, you can view information about them back on the Agents sub-section. Some of the information available will be the agent status, which can be idle, busy, unknown, errored, or exited. You can also find the agent’s ID, IP Address, and the last time it checked in.

The last area will be configuring your workspace to use the configured agent pool. This setting is available in a workspace’s General Settings area, under Execution Mode. You will need to change the execution mode from the current mode to Agent. You will also need to select the desired agent pool that should be used to process this workspace’s Terraform operations.

After those configuration steps are complete, you are now ready to use Terraform Cloud consistently in your private environments just as you would anywhere else. Additionally, those workspaces making use of agents will provide further information for each of the Terraform runs. Every Terraform plan and apply operation will include an extra line in the console to specify the agent pool and the particular agent which performed each operation.