Best Practices for migration from Replicated to FDO docker

Introduction

Migrating Terraform Enterprise (TFE) from a Replicated-based installation to an FDO Docker-based deployment requires careful planning and configuration. This guide provides an overview of best practices, important checks, and key adjustments to help ensure a smooth migration process.

Scenario

Before initiating the migration, complete the following steps:

1. Environment Compatibility – Review your current infrastructure and confirm that your versions of Terraform Enterprise and Docker meet supported requirements. Refer to the Terraform Enterprise Release Compatibility Documentation for the latest details.

2. Obtain License – Request a TFE FDO license from your HashiCorp Account Manager.

3. Upgrade Replicated – Ensure your Replicated installation is upgraded to v202309-1 or later. Follow the HashiCorp upgrade guide.

4. Backups – Take complete backups (mounted disk, external services, or active-active setup) to safeguard rollback options.

5. Migration Strategy – Decide whether to perform the migration on the existing host or a new host.

Recommendation

• If your Replicated installation uses a proxy, explicitly define the following environment variables in your compose.yaml:

  http_proxy

  https_proxy

  no_proxy
  During upgrades, communication issues may occur if required addresses are missing in no_proxy.

• In Replicated installations, the tfe_terraform_isolation network is used. In FDO Docker installations, this is replaced with terraform-enterprise_default.
  Remove TFE_RUN_PIPELINE_DOCKER_NETWORK from your compose.yaml. Terraform Enterprise will automatically use the default Docker network.

• The encryption password configured in your Replicated installation must remain the same in the FDO Docker deployment. This ensures sensitive data can still be decrypted properly after migration.

• Stop and disable all Replicated services, then uninstall Replicated to prevent conflicts or unintended restarts. Always confirm backups are available before removing Replicated components.

• In Replicated, logs were often written to a tmpfs mount. In FDO Docker, logs are persisted in /var/log/terraform-enterprise via Docker volumes. This is the recommended configuration for log persistence in Docker deployments.

• Some workloads require hairpin addressing to function correctly. In Replicated, hairpin mode was enabled by default. In FDO Docker, you may need to enable it manually. Follow the guidance in this KB: How to Enable Hairpin Addressing in Terraform Enterprise FDO Docker

Additional Information

• https://developer.hashicorp.com/terraform/enterprise/deploy/replicated-migration