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:

• Amazon ElastiCache for Redis
• Official Redis Docker container

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>

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.