Prepare your environment for a version upgrade

This topic describes how to prepare your Terraform Enterprise environment for a version upgrade when deployed to the Replicated platform. For instructions on upgrading Terraform Enterprise deployed to other runtimes, refer Upgrade Terraform Enterprise.

Overview

You should create a plan for upgrading your Terraform Enterprise deployment to minimize potential issues. Complete the following steps to prepare for your upgrade:

1. Thoroughly review release information: The release notes contain critical information about each release, including required versions along the upgrade path and breaking changes. When skipping releases, be sure to review release notes for all skipped releases for a cumulative list of all breaking changes, known issues, fixes, and features added between your current and target version.
2. Verify your Replicated license: You must have an active license to complete the upgrade.
3. Configure log forwarding: If the upgrade fails, forwarding logs to a persistent storage system can help you diagnose the problem.
4. Back up your system: Create backups of stateful data, configuration files, and other artifacts so that you are prepared in case you experience issues during the upgrade.
5. Test against a dev/test environment: Create a mirror of your production environment so that you can safely test your upgrade path. Test environments do not count against your Terraform Enterprise license.

Pre-upgrade checklist

Use the following checklist to help you prepare for upgrading your Terraform Enterprise deployment:

• OS version is supported at my target version.
• Postgres version is supported at my target version.
• Redis version is supported at my target version if running in active-active mode.
• Docker version is supported at my target version.
• I know the required releases between my current and target version.
• I understand that I will have to fully start the application at each required release between my current and target version
• I have reviewed the breaking changes in all releases between my current and target version and have planned accordingly.
• I have reviewed the deprecated features in all releases between my current and target version and planned accordingly.
• I have configured Terraform Enterprise to forward logs from my installation so that they are still available if the installation restarts.
• I have tested my upgrade path in a test environment that mimics my production environment.
• I have created a backup of my Terraform Enterprise data.
• I have created a backup of my Terraform Enterprise configuration. Store the Terraform Enterprise configuration in a settings.json file. You can use the Replicated snapshot feature to create the backup.
• I have created a backup of my Replicated configuration. Store the Replicated configuration in a replicated.conf file. You can use the Replicated snapshot feature to create the backup.

Review release information

Refer to the releases documentation for details about new releases. Focus on the following aspects of the releases in your upgrade path:

Updates to functionality

The Highlights, Features, and Improvements sections in the release notes describe information about changes between your current release and the target release so that you can adjust workflows accordingly.

Required releases

Note any required releases between your current release and the target release. The release notes denote required releases with an asterisk.

You must include required releases as part of the upgrade path to your target version. You must also start the application after upgrading to a required version before proceeding with the upgrade.

Refer to the releases overview page and click the Replicated tab for additional details.

Breaking changes

Check the release notes for all versions along your upgrade path for breaking changes. Failing to take action associated with a breaking change may cause upgrade failures or disruptions to core application workflows.

The release documentation describes breaking changes, if any, for each release. For example, the v202210-1 release includes a breaking change for customers on Postgres v10.

Verify the Replicated license

An expired Replicated license can cause an installation to fail. Before upgrading, ensure your license is valid. If your license is expired, contact your HashiCorp account manager. Refer to the licensing documentation for details.

Configure log forwarding

We recommend configuring Terraform Enterprise to forward logs to a persistent storage system. Log forwarding prevents you from losing log information if an error occurs during an upgrade and the system restarts. If you do not have your own log forwarding toolstack, you can use the embedded Fluentbit feature.

Refer to the following topics for instructions on how to enable log forwarding with Fluentbit:

• Terraform Enterprise Log Forwarding
• Forward Terraform Enterprise logs to Datadog

Back up your system

We recommend regularly backing up all stateful services and configuration files, as well as external services, such as Postgres, object storage, replicated.conf, and settings.json so that you can recover in the unlikely event that Terraform Enterprise encounters an edge case issue.

Refer to the following topics for instructions:

• Terraform Enterprise backup - recommended pattern tutorial
• Terraform Enterprise Backups and Restores

Test your upgrade plan

We strongly recommend that you create a dedicated test environment for testing your upgrade plan before scheduling an upgrade in production. You can use the same Terraform Enterprise license in your test environment as your production environment. Test environments do not count against your workspace allowance.

The following components and configuration in your test environment should match your production environment as closely as possible:

• Environment dependencies:
  • Cloud platform, for example AWS
  • Host type, such as EC2 instance with the same resource allocations
  • Operating system version
  • Postgres version
  • Redis version if Terraform Enterprise is in active/activemode
  • Docker version
• Installed Terraform Enterprise version
• Terraform Enterprise configuration files:
  • replicated.conf
  • settings.json
• Replicated version

Dev/test environments should not share external services with your production environment, including Postgres, object storage, and Redis.