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 to the required versions.

Note: This process will require application downtime

Expected Outcome

• Successfully upgrade TFE Active/Active instances

• Minimize downtime

Prerequisites 

• Verify compatibility of PostgreSQL and Docker versions before starting the upgrade.

• Review the Terraform Enterprise Releases page to:

  • Identify required intermediate releases (marked with *)

  • Determine the release sequence for your target version

Backup

Before starting the upgrade, ensure the following backups are taken:

• Database Backup

• Object Storage Backup

• Compose or Helm Values Files

Recommended Pattern:
Follow the Terraform Enterprise Backup - Recommended Pattern for best practices.

Upgrade Use Cases

1. Active-Active Docker Setup

Steps:

1. Backup

   • Take a backup of compose.yaml.

2. Stop Applications (Both Nodes)

   tfectl node drain

   This command allows current operations to complete and safely stops new plan/apply executions.

3. Shut Down Containers on Both Nodes

   docker compose down

   Ensure no application containers are running.

Upgrade Node 1:

1. Update compose.yaml:

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

2. Start the application:

   docker compose up --detach

3. Validate

   • Confirm the UI is accessible

   • Perform test Terraform runs

4. If issues occur:

   • Use the backup of compose.yaml to rollback

   • Redeploy the previous version

5. Stop Node 1 application again before upgrading Node 2

Upgrade Node 2:

1. Update compose.yaml:

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

2. Start the application:

   docker compose up --detach

• Do not start Node 2 with the old version if Node 1 upgrade fails.

• Rollback Node 1 first, then bring it back up before starting Node 2.

2. Active-Active Kubernetes Setup (Helm Chart)

Steps:

1. Backup Configuration

   • Backup overrides.yaml or values.yaml.

2. Access the Kubernetes Cluster (via Bastion or local machine)

3. Scale Down Application

   • Set replicas to 0 in the YAML file:

     replicaCount: 0

   • Apply the changes.

4. Update Image and Scale Up

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

5. Start Application

   • Deploy the updated Helm chart

6. Validate

   • Ensure application is fully up and functional

7. Scale As Needed

   • Increase replicaCount based on your requirements

8. Rollback (if needed)

   • Use the backup of your YAML file to redeploy the previous version

Additional Information

• Please refer this page