How to Enable "hairpin_addressing" in Terraform Enterprise FDO Docker

Introduction

This guide explains how to enable hairpin addressing in a Terraform Enterprise Flexible Deployment Options (FDO) Docker installation. This is achieved by adding a host mapping to the main Terraform Enterprise container and to the agent containers that execute Terraform runs.

Expected Outcome

You will add a host mapping to the Terraform Enterprise container to resolve the TFE hostname to the private IP address of the instance.

Prerequisites

• A running Terraform Enterprise instance using the Flexible Deployment Options for Docker.

Use Case

This procedure is useful when migrating from a Replicated installation to an FDO Docker installation where you need to replicate the functionality of the hairpin_addressing Replicated setting.

Procedure

Follow these steps to configure the host mapping.

1. Edit the Docker Compose File

In your compose.yaml file, add the extra_hosts block to the tfe service definition with the hostname:IP mapping.

For example:

name: terraform-enterprise
services:
  tfe:
    # ... other configuration ...
    extra_hosts:
      - "tfe.example.net:162.242.195.82"

2. Restart Terraform Enterprise

If you have configured Terraform Enterprise to run as a systemd service, use that to restart the application. Refer to the Systemd installation documentation for details.

Otherwise, manually restart the containers from the directory containing your compose.yaml file.

Stop the containers.

$ docker compose down

Start the containers in detached mode.

$ docker compose up -d

3. Verify the Container Host Mapping

Confirm that the host mapping was applied to the main tfe container. Replace terraform-enterprise with your container name if you have customized it.

Inspect the container's host configuration.

$ docker inspect terraform-enterprise -f '{{.HostConfig.ExtraHosts}}'
## [tfe.example.net:162.242.195.82]

Check the /etc/hosts file inside the container.

$ docker exec -it terraform-enterprise bash -c 'egrep $TFE_HOSTNAME /etc/hosts'
## 162.242.195.82 tfe.example.net

4. Apply Host Mapping to Terraform Run Agents

The extra_hosts setting only applies to the main terraform-enterprise container. To enable hairpin addressing for Terraform runs, you must also apply this setting to the agent containers by setting the TFE_RUN_PIPELINE_DOCKER_EXTRA_HOSTS environment variable.

This variable should be set in your TFE configuration file (e.g., tfe.env) with the same hostname:IP mapping.

TFE_RUN_PIPELINE_DOCKER_EXTRA_HOSTS=tfe.example.net:162.242.195.82

After setting this variable, you must restart Terraform Enterprise again for the change to take effect.

Additional Information

• For more details on agent container settings, see the Docker Driver settings documentation.
• For more information on the extra_hosts setting, refer to the official Docker Compose file reference.