How-to replace TLS Certificate and Private Key for Terraform Enterprise using CLI

Introduction

This guide explains how to replace the TLS certificate and private key for a Terraform Enterprise instance using the command line. This method is suitable for manual updates or for integration into an automated CI/CD workflow.

Prerequisites

Before you begin, ensure you have the following:

• Administrative access to the Terraform Enterprise instance's underlying host.
• The new PEM-encoded TLS certificate and private key files available on the instance.

Use Case

You may need to replace the TLS certificate and private key for the following reasons:

• The current TLS certificate is expiring and needs to be updated.
• The current TLS private key needs to be rotated to comply with security policies.
• The TLS certificate details, such as the Common Name, require an update.

Procedure

Follow these steps to replace the TLS certificate and private key.

1. Stop the Terraform Enterprise application. This command may take a few moments to complete.

   # replicatedctl app stop

2. Confirm that the application has stopped. You may need to run this command several times until the State shows stopped.

   # replicatedctl app status

   The expected output shows the application in a stopped state.

   [{
     "AppID": "e037a702be084ad052c3fbde252dfdb6",
     "Sequence": 550,
     "PatchSequence": 0,
     "State": "stopped",
     "DesiredState": "stopped",
     "Error": "",
     "IsCancellable": false,
     "IsTransitioning": false,
     "LastModifiedAt": "2021-07-21T09:46:39Z"
   }]

3. Set the new certificate and key using the replicated command. Note that this command uses replicated, not replicatedctl.

   # replicated console cert set <hostname> /path/to/new.key /path/to/new.cert

   Note: The path to the new TLS certificate and private key files must be different from the path of the existing files. At a minimum, the filenames must be different.

4. Start the Terraform Enterprise application.

   # replicatedctl app start

5. Wait for the Terraform Enterprise application to fully start before resuming normal operations.

Load Balancer Considerations

If your Terraform Enterprise instance is behind a load balancer, you must also replace the certificate on the load balancer with the updated version to ensure uninterrupted service.

Additional Information

• On some RedHat-based systems, you may need to use the full path for the commands, such as /usr/local/bin/replicatedctl and /usr/local/bin/replicated.