Configure Redis data store connection

This topic describes how to configure Terraform Enterprise connection to an externally-managed Redis data store. This step is only necessary when operating Terraform Enterprise in an active-active operational mode. To allow Terraform Enterprise to self-manage Redis, configure Terraform Enterprise to run in disk operational mode on a compatible runtime platform, such as Docker or Podman. Refer to Configure operational mode for additional information.

Introduction

Terraform Enterprise uses Redis to cache and manage the background job scheduler queue across available hosts. Redis server configuration is required for any runtime platform configured to operate in active-active mode. You can operate Terraform Enterprise in active-active mode on the following runtime platforms:

Kubernetes
OpenShift
Nomad

Requirements

Before proceeding, ensure that your environment meets the following requirements:

Either a cloud-managed or self-hosted Redis server is required.
Terraform Enterprise supports Redis server 6 and 7. We recommend using version 7.
Redis Cluster and Redis Sentinel are not supported.

Example Redis servers:

Secure Redis servers

For secure Redis servers, create a user with read and write access.

TLS requirements

Verify that you meet the following requirements when TLS is required to connect to the Redis server:

A valid TLS certificate and key are configured on the Redis server.
The Redis server is properly configured to accept TLS connections.
The Terraform Enterprise client is configured to use TLS when connecting to Redis. Refer to the TLS configuration reference for additional information.

For detailed information on configuring TLS for Redis, refer to the official Redis documentation on encryption.

Specify Redis connection settings

Add the following settings to your Terraform Enterprise configuration:

Set the TFE_REDIS_HOST variable to the location of your Redis server. Format the location as HOST[:PORT], for example redis.example.com or redis.example.com:6379.
Set the TFE_REDIS_USE_TLS variable to true if your Redis server requires TLS. Defaults to false.
Set the TFE_REDIS_USE_AUTH variable to true if your Redis server requires authentication.
Set the TFE_REDIS_USER variable to the user name you want to use to access the database.
Set the TFE_REDIS_PASSWORD variable to the password for the user.

Refer to Redis settings in the configuration reference for additional information.

Redis Enterprise

Terraform Enterprise can use Redis Enterprise in non-clustering mode as it's Redis service. To do so, you must configure a separate Redis endpoint for sidekiq, an internal component. This requirement exists because sidekiq and other components that rely on Redis must be kept separate. In normal operation, this is accomplishing using numbered Redis databases, which are not supported in Redis Enterprise. By defining a separate endpoint for sidekiq usage, Terraform Enterprise will use the default database 0 while still maintaining separation between sidekiq and other components.

Add the following settings to your Terraform Enterprise configuration:

Set the TFE_REDIS_SIDEKIQ_HOST variable to the location of your Redis server. Format the location as HOST[:PORT], for example redis.example.com or redis.example.com:6379.
Set the TFE_REDIS_SIDEKIQ_USE_TLS variable to true if your Redis server requires TLS. Defaults to false.
Set the TFE_REDIS_SIDEKIQ_USE_AUTH variable to true if your Redis server requires authentication.
Set the TFE_REDIS_SIDEKIQ_USER variable to the user name you want to use to access the database.
Set the TFE_REDIS_SIDEKIQ_PASSWORD variable to the password for the user.