How To
Summary
The default Docker bridge network uses the 172.17.0.0/16 IP range, which can conflict with existing infrastructure networks such as VDI environments using the same range. For a Terraform Enterprise deployment, this conflict can prevent the Terraform Enterprise (TFE) host from routing traffic to addresses in the overlapping range and can cause run failures as TFE spawns ephemeral worker containers on the Docker host for every remote execution run. The resolution involves updating Docker configuration with a non-conflicting IP range, restarting the Docker daemon, and optionally recreating the run pipeline network. This requires a planned maintenance window as TFE must be fully stopped and restarted.
Objective
Problem
The Docker default bridge network IP range conflicts with an existing network on the infrastructure, preventing the TFE host from routing traffic to addresses in the overlapping range.
Symptom
Network connectivity failures from the TFE host to systems sitting in the 172.17.x.x range. Terraform runs may also fail if ephemeral worker containers cannot reach required endpoints due to the routing conflict.
Cause
Docker assigns the 172.17.0.0/16 range to its default bridge network (docker0) and allocates additional pools from the broader 172.x.x.x space if needed. If another network on the same infrastructure uses an overlapping range, the host treats those addresses as local to Docker instead of forwarding them to the physical network, causing routing failures.
Environment
- Terraform Enterprise — Flexible Deployment Options (FDO)
- Runtime: Docker / Docker Compose
- OS: Linux (systemd-based, e.g. Ubuntu, RHEL)
Steps
Confirm the new IP range with your network team before proceeding. Schedule a maintenance window — this process requires a full application and Docker restart.
Step 1 : Drain active runs
Ensure no plans or applies are in progress before proceeding otherwise active runs will be terminated.
tfectl node drain
Step 2 : Stop Terraform Enterprise Deployment
docker compose down
Step 3 : Update Docker configuration /etc/docker/daemon.json
Create or update the file with a non-conflicting range. The example below uses 10.10.x.x / 10.11.x.x — adjust to any range confirmed available by your network team.
{
"bip": "10.10.0.1/16",
"default-address-pools": [
{
"base": "10.11.0.0/16",
"size": 24
}
]
}
Note: bip must be a full address ending in .1 — Docker uses it as the bridge gateway IP. The remainder of the subnet is allocated to containers.
Step 4 : Restart the Docker daemon
sudo systemctl restart docker
Step 5 : Recreate the run pipeline network (if applicable)
If TFE_RUN_PIPELINE_DOCKER_NETWORK is explicitly set in your docker-compose.yml, Delete and recreate the network with a subnet in the new range:
docker network rm <your-pipeline-network>
docker network create <your-pipeline-network> --subnet=10.11.1.0/24
Skip this step if TFE_RUN_PIPELINE_DOCKER_NETWORK is not set — the default network is handled by the daemon.json change above.
Step 6 : Start Terraform Enterprise Deployment
docker compose up -d
Step 7 : Verification
- Confirm previously conflicting addresses (e.g. VDI range) are reachable from the TFE host.
- Trigger a test Terraform run and confirm it completes successfully.
- Run
docker network lsanddocker network inspect <network>to confirm networks are using the new ranges.
Additional Information
- Ephemeral worker containers are created for remote execution runs, but not agent execution runs. For every plan and apply, TFE spawns a short-lived worker container on the Docker host to execute the Terraform binary.
- Run pipeline network: If
TFE_RUN_PIPELINE_DOCKER_NETWORKis not set, the ephemeral worker containers will use the default Docker network and no manual network recreation is required.
Related Information
Document Location
Worldwide
Was this topic helpful?
Document Information
Modified date:
13 May 2026
UID
ibm17272153