Upgrade Replicated deployment overview

This topic provides an overview of how to upgrade Terraform Enterprise deployments that run on the Replicated platform. For instructions on upgrading Terraform Enterprise deployed to other runtimes, refer Upgrade Terraform Enterprise.

Workflows

We recommend contacting HashiCorp support or your account team before starting on an upgrade journey if you have any questions or concerns. Complete the following steps to upgrade Terraform Enterprise:

1. Plan your upgrade: There are several preparatory actions you should take to plan your upgrade. For example, you should review release notes for versions along your upgrade path so that you are aware of required releases and new or deprecated features and other updates may affect your existing workflows. Refer to Plan your upgrade for details.
2. Perform the upgrade steps: Verify that you meet the requirements and follow the instructions for upgrading an Internet-connected or air-gapped deployment. Refer to Upgrade your Replicated deployment upgrade for details.

Upgrade duration

You can expect an upgrade for a single Terraform Enterprise instance to last 15-30 minutes. In rare cases, a release may include synchronous database migrations that could extend the upgrade duration for large-scale deployments.

To help you prepare for an extended upgrade, refer to the release notes for the version you are upgrading to. For example, the following release notes describe potential extended upgrades:

• v202406-1 release notes: The upgrade appears to stall when the data directory contains 1 TB or more of data and Terraform Enterprise is in disk mode.
• v202210-1 release notes: The migration may add two minutes per 5,000 organizations.

When skipping releases, be sure to review release notes for all skipped releases for a cumulative list of all breaking changes, known issues, fixes, and features added between your current and target version.

Releases

Refer to the releases documentation for details about new releases. We update the releases documentation every time we release a new version.

Unless a release is delayed or pushed up due to unseen circumstances, we release a new version of Terraform Enterprise once a month. The target release date for the next version appears at the top of the release page. You can also monitor our forum for release updates.

The first release of each month has a -1 at the end of the version number. The release usually includes application changes, such as new functionality, bug fixes, and performance enhancements. We increment the number at the end of the version as we release subsequent versions. These versions are generally patches that resolve a moderate to high severity issue. Some months do not include a patch release.

Required releases

You cannot skip a release that contains critical updates, such as an upgrade or breaking change to an internal dependency. For example, if your current release is v202206-1 and you want to upgrade to v202210-1, but v202207-2* is required, you must first upgrade to v202207-2* before performing another upgrade from v202207-2* to v202210-1.

We denote required releases with an asterisk next to the version number in the releases documentation, for example, v202207-2*. Releases without an asterisk are optional and you can skip them when jumping multiple releases. We mark releases as required if they contain changes that require a full application startup before proceeding to a further release.

Terraform Enterprise environment

Upgrading may require a change to the stack of technologies that supports your Terraform Enterprise deployment. The environment may include the following components:

• Cloud or platform provider the host is running on, such as AWS or VMware
• Host, such as the EC2 instance
• Operating system, such as RHEL 7.6
• Postgres version
• Redis version