HashiTalks 2025 Learn about unique use cases, homelab setups, and best practices at scale at our 24-hour virtual knowledge sharing event. Register
Terraform
Terraform Home

HCP Terraform agents for Terraform Enterprise

This topic describes HCP Terraform agent behavior when connected to Terraform Enterprise.

Introduction

HCP Terraform agents allow Terraform Enterprise to communicate with isolated, private, or on-premises infrastructure. By deploying lightweight agents within a specific network segment, you can establish a simple connection between your environment and Terraform Enterprise which allows for provisioning operations and management.

Refer to HCP Terraform agents for additional information about HCP Terraform agents

Requirements

Terraform Enterprise v202109-1 or later is required to connect to HCP Terraform agents.

Agents on HCP Terraform and Terraform Enterprise

The following list describes the differences between connecting agents to Terraform Enterprise and connecting to agents on HCP Terraform, which is the software-as-a-service edition of Terraform Enterprise:

  • No restriction on Agent Count: Terraform Enterprise does not place a limitation on the number of Agents that can be registered per organization.

  • Hostname Registration: HCP Terraform agents registering with a Terraform Enterprise instance must define the Terraform Enterprise hostname via the -address CLI flag or TFC_ADDRESS environment variable when running tfc-agent. By default, tfc-agent will attempt to connect to HCP Terraform, so this value must be explicitly defined when registering with a Terraform Enterprise instance.

  • Custom Bundle Support: HCP Terraform agents on Terraform Enterprise support custom Terraform bundles. Custom bundles are created and defined within the Terraform Enterprise application; Agents will download the custom bundle based on the Terraform version information. See using a custom Terraform bundle for more detail on custom bundles in Terraform Enterprise.

  • Network Access Requirements: HCP Terraform agents on Terraform Enterprise must be able to communicate with the Terraform Enterprise instance via HTTPS. 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 the Terraform provider registry. Agents executing in a workspace that leverage a Terraform version that provides a custom Terraform bundle with pre-existing provider binaries do not need access to these resources.

  • Agent Version Compatibility: Terraform Enterprise places restrictions on what versions of HCP Terraform agents can be registered. This is to prevent an incompatible agent from registering with a Terraform Enterprise instance and attempting to execute a Terraform operation in an undefined way. Compatible versions of HCP Terraform agents on Terraform Enterprise will vary based on the specific Terraform Enterprise release sequence; any changes to compatible HCP Terraform agents versions will be noted in the Terraform Enterprise release notes.