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 is 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

You can connect to either a Redis standalone instance, or a Redis Enterprise instance in non-clustering mode. The redis authentication can be configured for all Redis configurations.

Authentication

You can configure Redis to use the default user and require a password.

requirepass <your password>

In that case you would configure Terraform Enterprise

    TFE_REDIS_USE_AUTH: true
    TFE_REDIS_PASSWORD: <your password>

You can also configure Redis with ACL since Redis 6.

user <your user> on ><your password> ~* &* +@all

Warning

If you use a Redis user, it is crucial that they have sufficient permissions. In our testing, we used the following permissions `~* &* +@all`.

In that case, you would configure Terraform Enterprise with the following environment variables:

    TFE_REDIS_USE_AUTH: true
    TFE_REDIS_USER: <your user>
    TFE_REDIS_PASSWORD: <your password>

Redis Standalone

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_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_PASSWORD variable to the password for the user.

Redis Sentinel

Warning

Redis Sentinel is not supported for Terraform Enterprise on Replicated.

Terraform Enterprise can use Redis Sentinel as a highly available Redis service. Read more about highly available Redis services with Redis Sentinel in the Redis Sentinel documentation.

Terraform Enterprise queries Redis Sentinel instances to determine which Redis instance is active master. Terraform Enterprise performs queries while Redis replicates transaction data to other replicas.

You cannot use Redis Sentinel and Redis Enterprise in the same Terraform Enterprise deployment.

Use the following settings in your Terraform Enterprise configuration to use Redis Sentinel. Refer to the Configuration reference for information about all configuration settings:

Set the TFE_REDIS_SENTINEL_ENABLED variable to true in order to use Redis Sentinel.
Set the TFE_REDIS_SENTINEL_HOSTS variable to a comma separated list of the locations of Redis Sentinel hosts. Format the locations as HOST[:PORT],HOST[:PORT],..., for example redis-sentinel-1.example.com,redis-sentinel-2.example.com:26379.
Set the TFE_REDIS_SENTINEL_LEADER_NAME variable to the name of a service, such as main. Terraform Enterprise queries Redis Sentinel for the service to discover an active Redis host. This name should return a valid Redis service location when issuing a SENTINEL GET-MASTER-ADDR-BY-NAME <TFE_REDIS_SENTINEL_LEADER_NAME> command to Redis Sentinel.
Set the TFE_REDIS_SENTINEL_USERNAME variable to the username for the Redis Sentinel user. This setting is optional and is used to authenticate with Redis Sentinel instances.
Set the TFE_REDIS_SENTINEL_PASSWORD variable to the password for the Redis Sentinel user. This setting is optional and is used to authenticate with Redis Sentinel instances.
Set the TFE_REDIS_USER variable to the username for the Redis user. This setting is optional and is used to authenticate with Redis instances.
Set the TFE_REDIS_PASSWORD variable to the password for the Redis Sentinel user. This setting is optional and is used to authenticate with Redis instances.

Failover benchmarks for Redis Sentinel

We tested failover performance for a Terraform Enterprise deployment connected to a Redis Sentinel cluster. The cluster consisted of three Sentinel instances and three Redis instances. We observed the following outcomes:

Failover events that were manually triggered through Redis Sentinel showed no observable down time in Terraform Enterprise. This suggests a high degree of safety in planned maintenance operations.
The recovery time objective (RTO) during manually triggered failover events ranged from 47s to 2m10s.
The average RTO was 1m16s across successful failovers.
One out of 16 failovers experienced issues that required Terraform Enterprise node restarts to resolve continued run failures.

Terraform Enterprise performance when using Redis Sentinel depends on how Redis Sentinel is configured to monitor and recover from Redis instance problems.