How to Rotate TFE TLS Certificates on Kubernetes – HashiCorp Help Center

Introduction

When Terraform Enterprise (TFE) is running on Kubernetes, you can update TLS certificates by either modifying the Helm chart configuration or by directly patching Kubernetes secrets using kubectl. This guide provides a walkthrough of both methods.

During the initial TFE deployment on Kubernetes, the TLS configuration values tls.certData, tls.keyData, and tls.caCertData from the values.yaml file are saved in the Kubernetes secret store.

Expected Outcome

Successfully rotate the TFE TLS certificate and private key in a Kubernetes environment with minimal disruption.

Prerequisites

The TFE application is running and healthy on Kubernetes.
You have a new set of valid TLS certificates (certificate, private key, and CA bundle).

Use Case

You should rotate TFE TLS certificates under the following conditions:

The current certificates have expired.
The current certificates have been compromised.
You need to change the Certificate Authority (CA).
You need to comply with internal security policies.

Procedure

First, identify the existing secrets in your TFE namespace. The CA bundle is stored in the terraform-enterprise-ca-certificates secret, while the site certificate and its private key are stored in the terraform-enterprise-certificates secret.

List the existing secrets in the TFE namespace.

$ kubectl get secret --namespace tfe

Example output shows the relevant secrets.

##...omitted for brevity
NAME                                  TYPE                                  DATA   AGE
terraform-enterprise                  kubernetes.io/dockerconfigjson        1      61d
terraform-enterprise-ca-certificates  Opaque                                1      59d
terraform-enterprise-certificates     kubernetes.io/tls                     2      59d
terraform-enterprise-env-secrets      Opaque                                3      59d
##...omitted for brevity

Solutions

This article presents two methods for rotating the certificates.

Solution 1: Using Helm Upgrade

Use this method to manage TFE configuration through Helm, which aligns the TLS certificate update with other scheduled deployment changes.

Update the following values under the tls block in your values.yaml file with the new Base64-encoded certificate data.

tls:
  certData: "<Base64 New Certificate>"
  keyData: "<Base64 New Private Key>"
  caCertData: "<Base64 New CA Bundle>"

Apply the deployment changes using the updated values.yaml file.

$ helm upgrade terraform-enterprise hashicorp/terraform-enterprise \
  --namespace tfe \
  --values values.yaml

Note: This command applies all changes from the values.yaml file. Review the file carefully to avoid unintended modifications to your TFE configuration.

Solution 2: Using kubectl

Use this method to update the Kubernetes secrets directly with kubectl without modifying the original Helm configuration.

View the current terraform-enterprise-certificates secret to confirm its contents. The output will show the Base64-encoded certificate (tls.crt) and private key (tls.key).
```
$ kubectl get secret terraform-enterprise-certificates --namespace tfe -o yaml
```

Run the following kubectl command to replace the tls.crt and tls.key data with your new certificate and key files.

$ kubectl create secret tls terraform-enterprise-certificates \
  --namespace=tfe \
  --cert=./cert.pem \
  --key=./key.pem \
  --dry-run=client -o yaml | kubectl apply -f -

Restart the TFE deployment to apply the changes.

$ kubectl rollout restart deployment terraform-enterprise --namespace tfe

Additional Information