Upgrade Terraform Enterprise deployed to Replicated

This topic describes how to upgrade Terraform Enterprise deployed to the Replicated platform. For instructions on upgrading Terraform Enterprise deployed to other runtimes, refer Upgrade Terraform Enterprise.

Note

The Replicated deployment option is limited to customers who purchased Terraform Enterprise before January 2024. Terraform Enterprise 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.

To ensure you continue to receive the latest features and fixes, please plan to migrate to a new deployment option by November 2024. For more information, refer to Terraform Enterprise deployment overview or contact your HashiCorp account representative.

Overview

Complete the following steps to upgrade your Terraform Enterprise deployment:

Creata a backup of your application settings so that you can restore if an issue appears during the upgrade.
Prune dangling resources to clear space on the host for the upgraded images.
Use either the Replicated console or CLI to perform the upgrade. The instructions for either mechanism depends on whether Terraform Enterprise has Internet connectivity or is air-gapped.
You can track upgrade progress from the Replicated admin console or using the Replicated CLI. If you experience issues during the upgrade, refer to the troubleshooting instructions.
Complete any post-upgrade tasks.

Do not manually restart the application during the upgrade. Doing so will cause upgrade failure and loss of logs required to diagnose potential upgrade issues.

Multi-node deployments

This topic describes upgrading single-node deployment of Terraform Enterprise in external mode. Refer to the following topics for information about upgrading multi-node deployments in active-active:

Requirements

Complete the steps described in Prepare your environment for a version upgrade before beginning the upgrade process.
Review the following Terraform Enterprise requirements to ensure that your environment is supported:
Review the upgrading and patching information for your Terraform Enterprise active/active architecture.
Create a backup copy of the storage prior to upgrading your instance. Backup and restore responsibility varies depending on your Terraform Enterprise operation mode.

Back up your application settings

Connect to the Terraform Enterprise host machine using SSH and run the following command to export a copy of current application settings:

$ replicatedctl app-config export --hidden > backup_settings.json

Prune dangling resources

Run the following command to manually prune dangling Docker resources to clear space for upgraded images.

docker container prune -f
docker volume prune -f

Upgrade Internet-connected deployments

Open the installer dashboard at https://<TFE HOSTNAME>:8800/dashboard in your browser.
Click Check Now. Terraform recognizes the new version.
Click View Update.
Review the release notes and then click Install Update.

Connect to the Terraform Enterprise host machine using SSH.
Fetch the versions of Terraform Enterprise.
```
$ replicatedctl app-release ls --fetch
```
Upgrade to the latest version of Terraform Enterprise.
```
$ replicatedctl app-release apply
```
Alternatively, upgrade to a specific version of Terraform Enterprise.
```
$ replicatedctl app-release apply --sequence "504"
```

Upgrade air-gapped deployments

Open the installer dashboard at https://<TFE HOSTNAME>:8800/dashboard in your browser.
Check the Update Path field in the console settings for you instance to determine the update path where the installer should look for new .airgap packages.
Download the new .airgap package to the instance and place it at the location specified in the Update Path field.
From the installer dashboard, click Check Now. Terraform recognizes the new version.
Click View Update.
Review the release notes and then click Install Update.

Connect to the Terraform Enterprise host machine using SSH.

Print the AirgapPackagePath.

$ replicatedctl params export --template '{{.AirgapPackagePath}}'

On the Terraform Enterprise host machine, upload the desired airgap packages into the AirgapPackagePath.
Fetch the versions of Terraform Enterprise from the uploaded airgap packages.
```
$ replicatedctl app-release ls --fetch
```
List the available versions of airgap packages for the upgrade.
```
$ replicatedctl app-release ls
```
Upgrade to the latest version of the available airgap packages.
```
$ replicatedctl app-release apply
```
Alternatively, upgrade to a specific version, using one of the options listed in the output of the previous step.
```
$ replicatedctl app-release apply --sequence "504"
```

Track upgrade progress

To track progress from the UI, check the Status widget on the Replicated admin console. The Status widget is not available for deployments in active-active mode.

Run the replicatedctl app status command to track progress from the CLI.

Post-upgrade tasks

Complete the following tasks if you are stopping at a required release:

Fully start the application before proceeding to your next release.
Run the tfe-admin health-check command to verify that service connectivity has successfully re-established.
Run the tfe-admin background-migration-status-required command to verity database migrations are complete.

Troubleshooting

This section describes potential causes of issues during or after an upgrade.

Upgrade fails to proceed

If you suspect your upgrade is stuck, check log messages in tfe-migrations. Migrations can take longer than usual and extend the upgrade window.

If there are no migrations in progress and the upgrade is still not completed in a timely manner, contact support.

Do not manually restart the application during the upgrade. Doing so will cause upgrade failure and loss of logs required to diagnose potential upgrade issues.

Missing or improper functionality

The functionality may have been deprecated in a version in your upgrade path. The functionality may also be related to deprecated or removed support for an operating system, Postgres version, or other dependency. Refer to the release notes for information about deprecated, removed, or replaced functionality and for potential workarounds.

Once a functionality is removed or a dependency dropped, Terraform Enterprise no longer officially supports it. As a result, the functionality or dependency is no longer covered in the release regression testing suite. If the removed feature or dependency is the cause of issues related to upgrades or operability, you may be required to migrate off the feature or dependency to get help from HashiCorp support.