How to upgrade Terraform Enterprise version in FDO Active-Active setup

Introduction

This guide outlines the process of upgrading Active-Active Terraform Enterprise (TFE) instances.

Note: This process requires application downtime.

Expected Outcome

• Successfully upgrade TFE Active-Active instances.
• Minimize downtime during the upgrade process.

Prerequisites

Before starting the upgrade, you must complete the following checks:

• Verify compatibility of your PostgreSQL and Docker versions with the target TFE version.
• Review the Terraform Enterprise Releases page to identify any required intermediate releases (marked with *) and determine the correct upgrade sequence for your target version.

Backup

Before starting the upgrade, ensure you have created backups of the following components:

• Database
• Object Storage
• Compose (compose.yaml) or Helm (values.yaml) files

For best practices, follow the Terraform Enterprise Backup - Recommended Pattern.

Procedure

This section provides upgrade steps for both Docker and Kubernetes-based installations.

Option 1: Upgrade a Docker-based Installation

1. Create a backup of your compose.yaml file.

2. Stop the application on both nodes. This command allows current operations to complete before stopping new plan and apply executions.

   $ tfectl node drain

3. Shut down the application containers on both nodes.

   $ docker compose down

4. Verify that no application containers are running before proceeding.

5. On Node 1, update the image tag in your compose.yaml file to the target version.

   image: images.releases.hashicorp.com/hashicorp/terraform-enterprise:<vYYYYMM-#>

6. Start the application on Node 1.

   $ docker compose up --detach

7. Validate the upgrade on Node 1 by confirming the UI is accessible and performing test Terraform runs. If you encounter issues, use the backup of compose.yaml to roll back and redeploy the previous version. Stop the application on Node 1 again before proceeding with Node 2.
8. On Node 2, update the image tag in its compose.yaml file to the same target version.

9. Start the application on Node 2.

   $ docker compose up --detach

Note: If the Node 1 upgrade fails, do not start Node 2 with the old version. Roll back Node 1 first, bring it back up, and then start Node 2.

Option 2: Upgrade a Kubernetes-based Installation (Helm)

1. Create a backup of your overrides.yaml or values.yaml configuration file.
2. Access your Kubernetes cluster from a bastion host or local machine.

3. Scale down the application by setting the replica count to 0 in your configuration file.

   replicaCount: 0

4. Apply the change to scale down the pods.

5. Update your configuration file with the target image tag and set the replica count to 1 to begin the upgrade.

   replicaCount: 1
   image:
     repository: images.releases.hashicorp.com
     name: hashicorp/terraform-enterprise
     tag: <vYYYYMM-#>

6. Deploy the updated Helm chart to start the application.
7. Validate that the application is fully functional after the upgrade.
8. Scale the application as needed by increasing the replicaCount to meet your requirements.
9. If a rollback is necessary, use the backup of your configuration file to redeploy the previous version.

Additional Information

It is recommended to consult the official Terraform Enterprise upgrade documentation for further details.