Attempts To Upgrade Terraform Enterprise Airgap Installation Result In Intermediate Version Error

Introduction

When upgrading a Terraform Enterprise airgapped installation, you may encounter an error indicating that an intermediate release is required before you can upgrade to your target version. This article explains the cause of this error and provides the procedure to resolve it.

Problem

When you attempt to upgrade Terraform Enterprise in an airgapped environment directly to a much newer version, the process fails with an error similar to the following message.

intermediate release $RELEASE_NUMBER is required, cannot upgrade from $CURRENT_RELEASE to $PREFFERED_RELEASE

For example, a specific error message may appear as follows.

intermediate release 519 is required, cannot upgrade from 416 to 523

Cause

Certain versions of Terraform Enterprise require you to install an intermediate version before upgrading to the latest version. This requirement may be due to critical bug fixes or data migrations and ensures a smooth transition between releases.

If you select a release that is newer than the required intermediate version, the installer downloads the .airgap package and you move it to the airgapped update path directory (configured in replicated.conf). The installer then detects the version mismatch and fails the upgrade, displaying the error message.

Solution

To resolve this issue, you must remove the incorrect release package from the update path and install the required intermediate release.

Procedure

Follow these steps to complete the upgrade.

1. Access the update directory: Connect to the Terraform Enterprise instance and navigate to the airgapped update directory. You can find this path in the Terraform Enterprise admin console by navigating to https://<TFE_HOSTNAME>:8800/console/settings and checking the Update Path field.
2. Remove the incorrect release file: From the update directory, remove the .airgap package for the release that caused the error. In the example error intermediate release 519 is required, cannot upgrade from 416 to 523, the file corresponding to release 523 is the incorrect one.
3. Download the intermediate release: In the admin console dashboard at https://<TFE_HOSTNAME>:8800/releases, check for updates and locate the required intermediate release version. The error message specifies which version you need. In the example, the required intermediate release is 519.
4. Install the intermediate release: After downloading the correct .airgap package, you can install it using one of two methods:
   • Admin Console: Follow the standard installation process through the admin console UI.

   • Command Line: Manually apply the update from the Terraform Enterprise instance using the replicatedctl command. Replace 519 with your required release sequence number.

     $ replicatedctl app-release apply --sequence 519

After successfully installing the intermediate release, you can proceed with upgrading to your final target version.

Additional Information

For more details on the upgrade process, refer to the official Terraform Enterprise airgapped upgrade documentation.