Updating Certificates in Terraform Enterprise (TFE) Docker Based Installation – HashiCorp Help Center

Introduction

This guide provides step-by-step instructions on how to update CA certificates in a Docker-based installation of Terraform Enterprise (TFE).

Prerequisites

Before you begin, ensure you have the following:

Access to the server running the Docker installation of TFE.
The new CA certificates ready to be installed.
Understanding of where certificates are referenced in your docker-compose.yml file.
A complete and recent backup of your TFE instance.

Procedure

Follow these steps to update the certificates for your TFE instance.

1. Stop the Terraform Enterprise Application

Before making any changes, stop the TFE application to prevent conflicts while updating the certificates. This command stops all running containers for the TFE application.

$ docker compose down

2. Update the Certificates

Locate the directory where your docker-compose.yml stores certificates. By default, this path may be ./certs/. Copy your new certificate and key files into this folder on the host machine.

Replace the old certificates with the new ones, ensuring the file names match the references in your docker-compose.yml file.

## Copy the new certificate, bundle, and key to the certs directory
$ cp /path/to/new-certificate.crt ./certs/cert.pem
$ cp /path/to/new-certificate.crt ./certs/bundle.pem
$ cp /path/to/new-private-key.key ./certs/key.pem

Note: If you are using a custom deployment, such as one based on HVD modules, your certificate paths may differ. For example, certificates might be located in /etc/tfe/tls, with the docker-compose.yml file in /etc/tfe. Adjust the paths accordingly for your specific setup.

3. Restart the Terraform Enterprise Application

After updating the certificate files, restart the application. This command re-creates the containers, which will load the new certificates.

$ docker compose up -d

It may take a few minutes for TFE to fully initialize. You can monitor the logs to ensure the application starts successfully.

$ docker compose logs -f

Look for messages indicating that the containers have started and services are running correctly.

Verification

Once the application has restarted, you can verify that the new certificates are active.

Access your TFE instance in a web browser and inspect the certificate details to confirm the new certificate is being served.
Alternatively, use the curl command from a terminal to check the certificate.

$ curl -v https://your-tfe-domain.com

Review the output to confirm the new certificate details are present.

Troubleshooting

Application fails to start: Check the Docker logs for errors. Ensure the certificates are correctly referenced in the docker-compose.yml file and that the file permissions are correct.
Certificate-related errors: Verify that the new certificates are valid and that both the certificate and key files are correctly placed and named in the ./certs/ directory or your custom path.

Additional Information

For more details on Docker-based deployments, refer to the Terraform Enterprise Docker Deployment Documentation.