Products & Technology

An Introduction to Terraform Cloud Agents

HashiCorp Terraform Cloud Business tier provides self-hosted agents which allow customers to decide where they want to run their Terraform operations.

Mar 04 2021Kyle Ruddy

Many organizations have a significant and often growing investment in their existing on-premises data centers. Even if those organizations have gone all-in on the public cloud, they frequently need to manage resources that are not necessarily accessible from the public internet. This presents a challenge for a managed service that operates on the public internet and needs to reach those private resources.

HashiCorp Terraform Cloud provides customers with a new option to decide where they want to run their Terraform operations through the use of 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 to Terraform Cloud customers enrolled in the 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.

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

export TFC_AGENT_TOKEN=&lt;agent_token>
 
export TFC_AGENT_NAME=&lt;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             = "&lt;agent_token>"
          TFC_AGENT_NAME              = "&lt;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.

»Summary

Terraform Cloud’s Business tier includes a number of enterprise-grade features. One of the notable features is the ability to manage more of your resources, including those in isolated, private, or on-premises environments, in the same way as the rest of your environment. The self-hosted Terraform Cloud Agents provide all the Terraform Cloud features without the requirement of modifying any ingress networking policies.

Terraform Cloud is free to get started, and organizations can upgrade to the Team and Governance or the Business tier at any time. To get started, sign-up for Terraform Cloud and follow our Get Started tutorial or contact HashiCorp Sales.

To discover more about using Terraform Cloud Agents, review the guides on HashiCorp Learn.

An Introduction to Terraform Cloud Agents

»Terraform Cloud Agents Configuration

»Summary

Sign up for the latest HashiCorp news

More blog posts like this one

New Terraform integrations with Crowdstrike, Datadog, JFrog, Red Hat, and more

Terraform delivers launch-day support for Amazon S3 Tables, EKS Hybrid Nodes, and more at re:Invent

HashiCorp at re:Invent 2024: Infrastructure Lifecycle Management with AWS