Performing Upgrades to Terraform Enterprise on Installations Running Multiple Nodes

Upgrade Warning

The Replicated deployment option is limited to customers who purchased Terraform Enterprise before January 2024. Terraform Enterprise now supports new deployment options and will end support for the Replicated Native Scheduler option. The final Replicated release of Terraform Enterprise will be in November 2024. HashiCorp will support this release until April 1, 2026.

Scenario

When upgrading a Terraform Enterprise installation with multiple nodes, it is crucial to attempt the upgrade with only one instance running before scaling back up to the usual number of instances. The upgrade process updates the application’s database through a process called “migrations,” which also updates a sequence number indicating the version of the database schema.

The following is an example of a database schema version in a log file.

Current version: 20230725220632.

The database updates occur during the application's first launch after the upgrade. These updates are typically logged in the stdout log for a process named migrations. If the database version and installation version do not match, the application will not start, and the database will require a rollback before you can attempt a new upgrade.

Recommendation

When upgrading Terraform Enterprise, it is important to stop the application after waiting for all in-flight runs to finish before starting the upgrade. The upgrade process differs depending on your chosen deployment option.

Approach 1: Flexible Deployment Options

For a multi-node setup using Flexible Deployment Options, you must scale down to a single node before stopping the application and installing updates. You can find detailed instructions in the upgrade guide for Flexible Deployments.

Approach 2: Replicated Deployments

Upgrading a Terraform Enterprise deployment with multiple Active/Active nodes requires a specific approach. Before beginning, review the following documentation:

• Multi-node Active/Active deployment guide
• Automated install guide
• Best practices for deployment
• Admin CLI guide

The primary requirements include an auto scaling group (ASG) or equivalent with a single instance running Terraform Enterprise, placed behind a load balancer. We recommend that the installation be completely automated to allow scaling to zero and back to one without intervention. The safest method to perform an upgrade is to shut down all node instances, rebuild one node to validate a successful upgrade, and then scale to additional nodes (maximum of 5).

Additional Information

Additional documentation regarding the database changes made during migrations is available in the PostgreSQL requirements documentation. The key requirements are:

• The rails, vault, registry, and task_worker PostgreSQL schemas must be created on the database. These schemas will be automatically created if they do not already exist.
• A PostgreSQL user must be created with specific permissions on the database.

Note: Introduced in v202309-1, Terraform Enterprise supports flexible deployment options, such as Docker Engine and Kubernetes. If you are using Replicated today and want to migrate your Terraform Enterprise installation to an alternate deployment option, refer to our migration guide.