Updating Terraform Enterprise License (Replicated)

Introduction

Terraform Enterprise requires a valid license to maintain normal operations. Because licenses have an expiration date, you must update them periodically. This guide provides instructions for checking your license status and applying an updated license for both online and air-gapped Terraform Enterprise installations using Replicated.

Prerequisites

• SSH access to the Terraform Enterprise host machine.
• A new license file (.rli) provided by HashiCorp, if performing a manual update.

Procedure

Step 1: Check the License Expiration Date

You can find the expiration date for your current license using either the Replicated console UI or the command-line interface.

Using the Replicated Console

1. Navigate to the Replicated console at https://<TFE_HOSTNAME>:8800.
2. Select the gear icon in the top-right corner.
3. Select View License. The license details, including the expiration date, appear on the screen.

Using the Command Line

1. Connect to the Terraform Enterprise host machine using SSH.
2. Run the replicatedctl license inspect command to view license information. The ExpirationTime value indicates the expiration date and time in UTC.

$ replicatedctl license inspect
[
  {
    "ID": "670bd320b95245325d80be703330f9b3",
    "Assignee": "Test Customer Name",
    "LegacyChannelName": "Stable",
    "ChannelID": "",
    "Channels": [],
    "ExpirationTime": "2021-06-30T00:00:00Z",
    ## ...
  }
]

Step 2: Update the License for an Online Installation

Automatic Updates

For online installations, you can configure Terraform Enterprise to check for an updated license periodically.

1. Navigate to the Replicated console at https://<TFE_HOSTNAME>:8800.
2. Select the gear icon in the top-right corner, then select Console Settings.
3. Scroll to the License Sync section and choose the desired check frequency.

Manual Update via Replicated Console

1. Navigate to the Replicated console at https://<TFE_HOSTNAME>:8800.
2. Select the gear icon in the top-right corner, then select View License.
3. Select Sync License to start the update.

Manual Update via Command Line

1. Obtain the new license file (.rli) from HashiCorp and copy it to the Terraform Enterprise host machine.
2. Connect to the host machine using SSH.
3. Run the following command to load the new license.

$ replicatedctl license-load < /path/to/license.rli

Step 3: Update the License for an Air-Gapped Installation

Using the Replicated Console

1. Navigate to the Replicated console at https://<TFE_HOSTNAME>:8800.
2. Select the gear icon in the top-right corner, then select Console Settings.
3. Select Airgapped Settings from the left-hand menu and upload the new license file.

Using the Command Line

1. Obtain the updated license file and air-gap package from HashiCorp and copy them to the Terraform Enterprise host.
2. Connect to the host machine using SSH.
3. Execute the following command, updating the file paths as needed.

$ replicatedctl license-load --airgap-package /path/to/bundle.airgap < /path/to/license.rli

Troubleshooting

Issue: License does not update after air-gapped installation

In an air-gapped installation, the license update may complete without error, but the license details do not change. This can occur if you used an incorrect license file.

To verify, connect to the Terraform Enterprise host and examine the Replicated logs for the following warning.

$ docker logs replicated

Log Output:

WARN 2021-02-22T01:40:00+00:00 tasks/app_tasksteps.go:113 Airgap license on disk does not match installed license

This message confirms that the license file is incorrect. Ensure you are using the correct .rli file provided for your installation.

Error: "Unsuccessful HTTP response" during license sync

This error can occur for two primary reasons.

1. Network Connectivity Issues: In an online installation, this error may indicate that network infrastructure changes are preventing Terraform Enterprise from reaching Replicated endpoints. Ensure that your environment meets the documented network requirements. The license sync operation requires access to api.replicated.com. You can find a list of specific IP addresses in the Replicated GitHub repository.
2. Mismatched Customer Name: In an air-gapped installation, this can happen if a trial license was issued with one customer name and the new paid license was issued with a different name.

Error: "Failed to start the app: license has expired"

If Terraform Enterprise fails to restart, your license may have expired. Connect to the host machine and check the Replicated logs for the following message.

$ docker logs replicated

Log Output:

Failed to start the app: license has expired

This message confirms the license has expired. You must apply a new license to resolve the issue.

Error: "installed app release ... does not match the airgap package"

This error indicates that the air-gap package version is incorrect for the installed version of Terraform Enterprise.

Log Output:

installed app release (325b33bf0ad539c994644423128cad5e:502) does not match the airgap package

You can identify the correct version of an air-gap file by referencing the download page, which displays the Terraform Enterprise versions and their corresponding SHA256 checksums.

Error: "Error while saving console settings: snapshot schedule..."

This error may appear in the Replicated console when you upload a license.

Error Message:

Error while saving console settings: snapshot schedule: make spec: unknown schedule type ""

To resolve this, temporarily disable snapshots by unchecking Enable Automatic Scheduled Snapshots in the console settings.