Agent Requirements

Ensure your system meets the following requirements before installing and configuring HCP Terraform Agents. Refer to HCP Terraform Agents on Terraform Enterprise for additional Terraform Enterprise requirements.

Environment

You can deploy agents to x86_64 and ARM64 Linux. You can also run the agent in Docker using our official HCP Terraform Agent Docker container.

All agents in an agent pool should have the same operating system. If the agents use different resources, run performance can vary significantly between each agent in the pool.

The architecture of the agent pool is determined by the first agent that connects to HCP Terraform. For example, when the first agent to register to an empty pool is an ARM64 agent, subsequent agents that register must be ARM64 agents. Attempting to register an ARM64 agent to an existing x86-only agent pool results in an error.

Refer to Change the agent pool architecture for instructions on how to switch between architectures.

Terraform versions

You can use the agent with the following versions of Terraform.

• Terraform 0.12 and newer for agents on x86-64.
• Terraform 0.13.5 and newer for agents on ARM64.

Workspaces configured to use Terraform versions older than 0.12 cannot select the agent-based execution mode.

Hardware

The host running the agent has varying resource requirements depending on the workspaces the agent serves and the agent's configuration. A host can be a dedicated or shared cloud instance, virtual machine, bare metal server, or a container. You should monitor and adjust memory, CPU, and disk space based on each workspace's usage and performance.

All agents in an agent pool should have the same hardware resources available. If the agents use different resources, run performance can vary significantly between each agent in the pool.

Use the following specifications as a reference:

• At least 4GB of free disk space
  • Each run requires the agent to temporarily store local copies of the tarred repository, extracted repository, state file, any providers or modules, and the Terraform binary itself.
  • When using agents for private VCS operations, we recommend that the agent has storage capacity equal to at least twice the maximum expected repository size.
• At least 2GB of system memory
  • This provides the agent with enough memory to complete run operations, such as terraform plan, git clone, and sentinel apply. This also supports operations such as uploading and downloading artifacts, constructing temporary execution environments, and parsing configurations.
  • If you enable request forwarding, we recommend that you add at least 250MB of additional memory. The agent may hold multiple forwarded requests and responses in memory until they are successfully executed and relayed to HCP Terraform.

Software

Agents may depend on third-party tooling for certain features and functionality. The tfc-agent itself does not have any direct dependency on any of the following tools, though most common uses of Terraform will require them. The agent makes the assumption that the following utilities are pre-installed, and their respective CLI commands available on the $PATH of the user running tfc-agent.

• git - The Git CLI. May be used by the Terraform CLI when downloading modules from remote Git servers. Git version 2.3 or greater is required.
• ssh - The SSH CLI. Used by git when the remote source uses the SSH protocol.

In addition to the above tools, it is often useful to install the following optional software to support a broad range of uses. These tools may be used by Terraform's local-exec provisioners, an external data source, or a tfc-agent hook script.

• curl - Simple command-line HTTP client.
• wget - Simple command-line HTTP client.
• jq - JSON data inspection utility.
• unzip - Unarchiver for zip archives.
• tar - Unarchiver for tar archives.
• gzip - Decompression utility for gzipped archives.

Networking

In order for an agent to function properly, it must be able to make outbound TCP connections to the HCP Terraform application APIs. These requests may require perimeter networking as well as container host networking changes, depending on your environment. Refer to the HCP Terraform IP Ranges documentation for more details on the IP ranges.

Additionally, the agent must also be able to communicate with any services required by the Terraform code it is executing. This includes the Terraform releases distribution service, releases.hashicorp.com, as well as any provider APIs. The following services run on these IP ranges: