Introduction
Organizations using a standalone Terraform Enterprise installation may need to migrate to an Active/Active architecture to achieve greater reliability, redundancy, and scalability. This architecture uses multiple Terraform Enterprise nodes to improve availability and performance.
This guide outlines the prerequisites and procedures for migrating from a standalone to an Active/Active deployment.
Prerequisites
Before beginning the migration, ensure your environment meets the following requirements.
- Automated Installation: You must use an automated installation method for an Active/Active deployment. This ensures all nodes are configured consistently, which is critical for updates and upgrades. Manual installations are not supported for this architecture.
- Existing Infrastructure: Your existing PostgreSQL database and S3 bucket must be accessible to the new Active/Active nodes. The migration reuses these components, so no database migration is necessary beyond ensuring network connectivity.
- Redis Configuration: An external Redis instance is required. While two Redis servers are not strictly mandatory, a high-availability configuration using Redis Sentinel is recommended to manage failover. Note that Redis Cluster is not supported.
- Licensing and Security: You must have a valid Terraform Enterprise license and a TLS certificate to secure communication across all nodes.
- Network and Infrastructure: Your infrastructure must be configured to support multiple active nodes. This includes setting up a load balancer to distribute traffic and ensuring proper network configurations are in place. Some environments may require hairpinning.
Procedure
This migration follows the standard automated installation process, with configuration changes to enable Active/Active mode.
Step 1: Prepare for Migration
- Verify Package Compatibility: You can use the same Terraform Enterprise airgap package for both standalone and Active/Active installations. No separate package is required. The primary difference is in the configuration you provide during installation.
- Ensure Database Communication: Confirm that your network configuration allows the new Active/Active nodes to communicate with the existing PostgreSQL database. Reusing the database simplifies the migration significantly.
Step 2: Deploy and Configure New Nodes (or Reuse the existing TFE node, converting it to active-active (one node initially), then add the second node as needed.
Follow the official documentation for deploying Terraform Enterprise in an Active/Active topology. This process involves updating configuration files, such as replicated.conf, to enable Active/Active mode and define the multi-node setup.
For detailed, step-by-step instructions, refer to the Automated Installation - Active/Active guide.
Step 3: Address Log Forwarding
If you use the Fluent Bit container for log forwarding, no configuration changes are required on the Terraform Enterprise side. The existing setup will automatically handle logs from the new nodes. Ensure your log aggregation destination is prepared to receive logs from these additional sources.
Rollback Plan
If the migration to Active/Active fails, you can roll back to your previous setup using one of the following methods:
- Scale Down: Reduce the number of active nodes to a single node. This configuration is functionally equivalent to a standalone setup.
- Reinstall: Use your automated installation process to reinstall the previous standalone configuration. You may need to update the PostgreSQL database settings to match the original setup.
Additional Information
- For a complete guide on the installation process, refer to the official Terraform Enterprise Active/Active installation guide.