How to Update the Terraform Enterprise License File in an FDO Deployment

Introduction

Terraform Enterprise (TFE) requires a valid license file to enable features and authenticate with the private image registry to pull necessary container images. In Flexible Deployment Options (FDO) deployments, if the license expires and the TFE instance restarts, it will fail to pull these images, causing service downtime.

This article provides the procedure to update the TFE license file in an FDO deployment, verify its status, and restart services safely.

Note: If the license expires, TFE will continue to operate until it is restarted. Upon restart, the application will fail to start because it cannot pull the required container images.

Prerequisites

• Access to the TFE instance host(s).
• A valid, unexpired TFE license file.
• Sufficient permissions to run docker and tfectl commands.

Procedure

Follow these steps to update your Terraform Enterprise license.

1. Gracefully Stop Terraform Enterprise

   First, drain all nodes to stop new work from being scheduled. This command should be run on one of the nodes.

   $ tfectl node drain --all

   Next, stop the TFE services on all nodes in your cluster.

   $ docker compose down

2. Back Up the Existing License File

   Before making changes, create a backup of your current license file. The location of this file is specified by the TFE_LICENSE_PATH variable in your docker-compose.yml or environment configuration.

   ## Replace /path/to/your/license.rli with the actual path
   $ cp /path/to/your/license.rli /path/to/your/license.rli.bak

3. Apply the New License File

   Update your configuration to use the new license. You can do this by either:

   • Replacing the old license file on disk at the path specified by TFE_LICENSE_PATH.
   • Updating the TFE_LICENSE environment variable with the base64-encoded content of the new license file.

4. Restart Terraform Enterprise

   Start the TFE services on all nodes.

   $ docker compose up -d

5. Verify the New License

   After the services have started, verify that the new license is active by checking its details.

   $ tfectl app license

   Confirm that the output displays the correct expiration date for the new license.

Additional Information

• Always renew your license before it expires to avoid potential downtime during a restart.
• Consider scheduling routine license checks as part of your maintenance schedule and creating monitoring alerts for impending license expiration.
• For more details on license configuration, refer to the official License Configuration documentation.