How to perform a manual upgrade of Active/Active instances – HashiCorp Help Center

Introduction

This guide outlines the manual process for upgrading multiple Terraform Enterprise Active/Active instances. This procedure is intended for environments where an upgrade cannot be performed using the preferred automated method, such as VMware on-premises installations that lack native auto-scaling, or in environments with restrictions on rebuilding instances.

Note: This process requires application downtime.

Expected Outcome

You will have successfully upgraded your Active/Active Terraform Enterprise instances to a target version, including any required intermediate versions.

Prerequisites

Before beginning the upgrade, complete the following preparatory steps.

1. Perform a Full Backup

As a standard practice, ensure that you have performed recent backups of your database and object storage. This is critical in the event a rollback is required.

For more information, refer to the Terraform Enterprise Backup - Recommended Pattern guide.

2. Identify the Upgrade Path

Check the Terraform Enterprise Releases page to identify any required intermediate releases and find the release sequence number for your target release. Required releases are denoted with an asterisk (*).

For this guide, the example required release sequence is 610 and the target release sequence is 636.

Airgap Considerations

Airgapped installations require additional steps to load the release packages onto the host machine before starting the upgrade.

Connect to the Terraform Enterprise host machine using SSH.

Identify the airgap package path.

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

Upload the desired airgap packages for all required and target releases into the directory identified in the previous step.
Fetch the versions from the uploaded airgap packages.
```
$ replicatedctl app-release ls --fetch
```

Procedure

Follow these steps to upgrade two Active/Active instances through a required version and then to the final target version.

Step 1: Prepare the Environment

If you have a health-checking process that may terminate or rebuild instances upon failure, disable it or increase its threshold to allow enough time for the upgrade to complete on both instances.
Stop the Terraform Enterprise application on both nodes. The tfe-admin node-drain command only affects the local host.
```
## Run on both nodes
# tfe-admin node-drain
# replicatedctl app stop
```
Verify the application is stopped on both nodes. The status should show stopped.
```
## Run on both nodes
# watch replicatedctl app status
```

Step 2: Upgrade to the Required Intermediate Release

First, upgrade both nodes to the required intermediate release (e.g., sequence 610).

On Node 1, set the release sequence to the required version and apply the release.

## For airgapped environments, run 'replicatedctl app-release ls --fetch' first
# replicatedctl params set ReleaseSequence --value 610
# replicatedctl app-release apply

Verify the application has started on Node 1.
```
# replicatedctl app status
```

Once started, drain and stop the application on Node 1.

# tfe-admin node-drain
# replicatedctl app stop
# watch replicatedctl app status

On Node 2, set the release sequence to the same required version and apply the release.

## For airgapped environments, run 'replicatedctl app-release ls --fetch' first
# replicatedctl params set ReleaseSequence --value 610
# replicatedctl app-release apply

Verify the application has started on Node 2.
```
# replicatedctl app status
```

Step 3: Upgrade to the Target Release

Next, upgrade both nodes from the intermediate release to your final target release (e.g., sequence 636).

On Node 2, drain and stop the application.

# tfe-admin node-drain
# replicatedctl app stop
# watch replicatedctl app status

On Node 1, set the release sequence to the target version and apply the release.

## For airgapped environments, run 'replicatedctl app-release ls --fetch' first
# replicatedctl params set ReleaseSequence --value 636
# replicatedctl app-release apply

Verify the application has started on Node 1.
```
# replicatedctl app status
```