SupportConsoleDevelopersStart a trialContact

Chapter 3. External Redis database configuration

Important

Red Hat supports 3scale configurations that use an external Redis database. However, does not officially support setting up Redis for zero downtime, or Redis database replication and sharding. The content is for reference only. Additionally, Redis Cluster mode is not supported in 3scale.

Note
  • Disclaimer: Links contained herein to external website(s) are provided for convenience only. Red Hat has not reviewed the links and is not responsible for the content or its availability. The inclusion of any link to an external website does not imply endorsement by Red Hat of the website or their entities, products or services. You agree that Red Hat is not responsible or liable for any loss or expenses that may result due to your use of (or reliance on) the external site or content.

3scale uses multiple Redis databases:

  • Backend storage database holds information about API services, application keys, metrics, limits, and usage data, including current usage and historical analytics. Utilization data is unique to the Backend storage database, while the database of the System component is the main source for other data, which you can recreate if needed.
  • Backend queues database temporarily stores background job queues for reporting API usage, based on Resque. The backend listener creates these jobs, and the backend worker processes them.
  • System Redis database is used for storage of data required by the System component, mainly for background job processing using Sidekiq, but also other internal purposes.

The OpenShift deployments that use Redis databases are: backend-listener, backend-worker, backend-cron, system-app, and system-sidekiq.

Starting from Red Hat 3scale API Management 2.16, all Redis databases must be provided by the user. The 3scale operator does not create or manage the Redis databases. The connection details for the Redis databases are set through OpenShift secrets backend-redis and system-redis, see Configuring Redis databases for details. The supported versions for the database can be consulted at Red Hat 3scale API Management Supported Configurations (3scale API Management 2.16 section).

Prerequisites

  • A 3scale account with an administrator role.

3.1. Configuring Redis databases
Copy link

This section provides information on how to configure the Redis databases used by 3scale API Management when deploying in an OpenShift Container Platform environment.

Redis databases are configured using the OpenShift secrets backend-redis and system-redis. The 3scale operator uses these secrets to set the environment variables in the corresponding Deployment resources for the Backend and System components. Each Deployment specification contains mappings from the secret fields to the environment variables used by the pods. For example, for the Backend Deployments: 

name: CONFIG_REDIS_SENTINEL_HOSTS
  valueFrom:
    secretKeyRef:
      key: REDIS_STORAGE_SENTINEL_HOSTS
      name: backend-redis

The complete mapping between the secret fields and the environment variables is described in the following sections.

3.1.1. backend-redis secret
Copy link

backend-redis secret contains the configuration for the Backend storage and Backend queues databases. The former is used both by Backend and System components, while the latter is only used by the Backend components.

The following table lists all the supported fields in the backend-redis secret and how the values set in those fields are used in the pods of the System (system-app, and system-sidekiq) and Backend (backend-listener, backend-worker, backend-cron) components. For the format and example values for the fields, see Format and example values for Redis configuration.

Expand
Table 3.1. backend-redis secret fields
backend-redis secret fieldDescriptionEnv var in BackendEnv var in System

REDIS_STORAGE_URL

Backend storage database URL. Required.

CONFIG_REDIS_PROXY

BACKEND_REDIS_URL

REDIS_STORAGE_USERNAME

Username for the backend storage database authentication (or Redis master, if Redis Sentinel is used).

CONFIG_REDIS_USERNAME

BACKEND_REDIS_USERNAME

REDIS_STORAGE_PASSWORD

Password for the backend storage database authentication (or Redis master, if Redis Sentinel is used).

CONFIG_REDIS_PASSWORD

BACKEND_REDIS_PASSWORD

REDIS_STORAGE_SENTINEL_HOSTS

Comma-separated list of sentinel URLs, for backend storage database.

CONFIG_REDIS_SENTINEL_HOSTS

BACKEND_REDIS_SENTINEL_HOSTS

REDIS_STORAGE_SENTINEL_ROLE

The role of the instance to connect to via Sentinel (master or slave), for backend storage database.

CONFIG_REDIS_SENTINEL_ROLE

BACKEND_REDIS_SENTINEL_ROLE

REDIS_STORAGE_SENTINEL_USERNAME

Username for the Redis sentinel authentication, for backend storage database.

CONFIG_REDIS_SENTINEL_USERNAME

BACKEND_REDIS_SENTINEL_USERNAME

REDIS_STORAGE_SENTINEL_PASSWORD

Password for the Redis sentinel authentication, for backend storage database.

CONFIG_REDIS_SENTINEL_PASSWORD

BACKEND_REDIS_SENTINEL_PASSWORD

REDIS_QUEUES_URL

Backend queues database URL. Required.

CONFIG_QUEUES_MASTER_NAME

 

REDIS_QUEUES_USERNAME

Username for the backend queues database authentication (or Redis master, if Redis Sentinel is used).

CONFIG_QUEUES_USERNAME

 

REDIS_QUEUES_PASSWORD

Password for the backend queues database authentication (or Redis master, if Redis Sentinel is used).

CONFIG_QUEUES_PASSWORD

 

REDIS_QUEUES_SENTINEL_HOSTS

Comma-separated list of sentinel URLs, for backend queues database.

CONFIG_QUEUES_SENTINEL_HOSTS

 

REDIS_QUEUES_SENTINEL_ROLE

The role of the instance to connect to via Sentinel (master or slave), for backend queues database.

CONFIG_QUEUES_SENTINEL_ROLE

 

REDIS_QUEUES_SENTINEL_USERNAME

Username for the Redis sentinel authentication, for backend queues database.

CONFIG_QUEUES_SENTINEL_USERNAME

 

REDIS_QUEUES_SENTINEL_PASSWORD

Password for the Redis sentinel authentication, for backend queues database.

CONFIG_QUEUES_SENTINEL_PASSWORD

 

REDIS_SSL_CA

Certificate Authority (CA) certificate for backend storage database.

CONFIG_REDIS_CA_FILE

REDIS_SSL_CERT

Client certificate for backend storage database.

CONFIG_REDIS_CERT

REDIS_SSL_KEY

Private key for the client certificate for backend storage database.

CONFIG_REDIS_PRIVATE_KEY

REDIS_SSL_QUEUES_CA

Certificate Authority (CA) certificate for backend queues database.

CONFIG_QUEUES_CA_FILE

REDIS_SSL_QUEUES_CERT

Client certificate for backend queues database.

CONFIG_QUEUES_CERT

REDIS_SSL_QUEUES_KEY

Example of the backend-redis secret

apiVersion: v1
kind: Secret
type: Opaque
metadata:
  name: backend-redis
stringData:
  REDIS_STORAGE_URL: redis://myuser:mypassword@backend-redis-external.3scale-databases.svc.cluster.local/0
  REDIS_QUEUES_URL: redis://myuser:mypassword@backend-redis-external.3scale-databases.svc.cluster.local/1

3.1.2. system-redis secret
Copy link

system-redis secret contains the configuration for the Redis databases used by the System components of 3scale.

The following table lists all the supported fields in the system-redis secret and how the values set in those fields are used in the pods of the System components (system-app and system-sidekiq).

Expand
Table 3.2. system-redis secret fields
system-redis secret fieldDescriptionEnv var in system

URL

System database URL. Required.

REDIS_URL

REDIS_USERNAME

Username for the system database authentication (or Redis master, if Redis Sentinel is used).

REDIS_USERNAME

REDIS_PASSWORD

Password for the system database authentication (or Redis master, if Redis Sentinel is used).

REDIS_PASSWORD

SENTINEL_HOSTS

Comma-separated list of sentinel URLs, for system database.

REDIS_SENTINEL_HOSTS

SENTINEL_ROLE

The role of the instance to connect to via Sentinel (master or slave), for system database.

REDIS_SENTINEL_ROLE

REDIS_SENTINEL_USERNAME

Username for the Redis sentinel authentication, for system database.

REDIS_SENTINEL_USERNAME

REDIS_SENTINEL_PASSWORD

Password for the Redis sentinel authentication, for system database.

REDIS_SENTINEL_PASSWORD

REDIS_SSL_CA

Redis Certificate Authority (CA) certificate.

REDIS_CA_FILE

REDIS_SSL_CERT

Redis client certificate.

REDIS_CLIENT_CERT

REDIS_SSL_KEY

Private key for the Redis client certificate.

REDIS_PRIVATE_KEY

Example of the system-redis secret

apiVersion: v1
kind: Secret
type: Opaque
metadata:
  name: system-redis
stringData:
  SENTINEL_HOSTS: ""
  SENTINEL_ROLE: ""
  URL: redis://myuser:mypassword@system-redis-external.3scale-databases.svc.cluster.local

The following sections describe the format and provide example values for the fields in the backend-redis and system-redis secrets.

3.1.3.1. URL fields
Copy link

The fields REDIS_STORAGE_URL, REDIS_QUEUES_URL in backend-redis secret, and URL in system-redis secret accept values in the following format: 

redis[s]://[[username][:password]@]host-or-ip[:port][/db-number]
  • Square brackets ([ ]) indicate an optional parameter sequence.
  • host-or-ip can be a hostname or an IP address, when using a single Redis instance.
  • When using Redis Sentinel, host-or-ip refers to the Redis master group name.
  • db-number is an integer value representing the logical database number to connect to. If not specified, it defaults to 0. Note that some Redis providers do not support logical databases, in which case this part should be omitted.
  • When rediss:// scheme is used, the connection to Redis is made over TLS/SSL. If TLS mode is used, the corresponding fields in the secrets must be set for SSL CA, SSL Cert, and SSL Key (REDIS_SSL_(CA|CERT|KEY) or REDIS_SSL_QUEUES_(CA|CERT|KEY)).
  • The credentials (username and password) can also be provided through their respective fields in the secrets (REDIS_STORAGE_USERNAME, REDIS_QUEUES_PASSWORD, etc.). If the credentials are provided both the URL and the through the corresponding secret fields, the ones in the URL take precedence.
  • If port is omitted, it defaults to 6379.

Example values:

redis://system-redis.3scale-databases.svc.cluster.local:6379

redis://myuser:mypassword@myredis.example.com/2

rediss://backend-storage-master-group-name

redis://:mypassword@172.20.45.10:6380/5

3.1.3.2. SENTINEL_HOSTS fields
Copy link

The fields REDIS_STORAGE_SENTINEL_HOSTS and REDIS_QUEUES_SENTINEL_HOSTS in backend-redis secret, and SENTINEL_HOSTS in system-redis secret accept a comma-separated list of sentinel connection strings in the following format: 

[redis[s]://][[username][:password]@]sentinel-hostname-or-ip:[port]
  • Square brackets ([ ]) indicate an optional parameter sequence.
  • Specifying the scheme (redis:// or rediss://) is optional.
  • When rediss:// scheme is used, the connection to Redis Sentinel is made over TLS/SSL. If TLS mode is used, the corresponding fields in the secrets must be set for SSL CA, SSL Cert, and SSL Key (REDIS_SSL_(CA|CERT|KEY) or REDIS_SSL_QUEUES_(CA|CERT|KEY)).
  • sentinel-hostname-or-ip can be a hostname or an IP address.
  • Normally, there should be at least three Sentinel instances for high availability.
  • The credentials (username and password) can also be provided through their respective fields in the secrets (REDIS_STORAGE_SENTINEL_USERNAME, REDIS_QUEUES_SENTINEL_PASSWORD, REDIS_SENTINEL_USERNAME, etc.). If the credentials are provided both the URL and the through the corresponding secret fields, the ones in the URL take precedence.
  • If the credentials (username and password) are provided through the URL, all sentinels in the list must use the same credentials. If different credentials are provided for different sentinels, the credentials of the first sentinel in the list are used.
  • If port is omitted, it defaults to 26379.

Example values:

redis://sentinel-user:sentinel-pass@sentinel1.example.com,redis://sentinel-user:sentinel-pass@sentinel2.example.com,redis://sentinel-user:sentinel-pass@sentinel3.example.com

sentinel1.3scale-databases.svc.cluster.local:26379,sentinel2.3scale-databases.svc.cluster.local:26379,sentinel2.3scale-databases.svc.cluster.local:26379

rediss://:mypass@10.119.4.45:16379,rediss://:mypass@10.119.8.252:16380,rediss://:mypass@10.119.7.48:16381

3.1.4. Enabling TLS for Redis connections
Copy link

To enable TLS connections for system and/or backend components, the following configuration must be applied.

3.1.4.1. System Redis
Copy link

To enable TLS connections for System Redis database:

  1. Set spec.system.systemRedisTLSEnabled to true in the APIManager custom resource. Example: 

    apiVersion: apps.3scale.net/v1alpha1
kind: APIManager
spec:
  system:
    systemRedisTLSEnabled: true

  2. Add the following fields to the system-redis secret (see the expected format):

    • REDIS_SSL_CA
    • REDIS_SSL_CERT
    • REDIS_SSL_KEY

When systemRedisTLSEnabled is set to true, and the SSL fields are set correctly in the system-redis secret, the operator updates the System component pods (system-app and system-sidekiq):

  • set the following environment variables:

    • REDIS_SSL=1
    • REDIS_CA_FILE=/tls/system-redis/system-redis-ca.crt
    • REDIS_CLIENT_CERT=/tls/system-redis/system-redis-client.crt
    • REDIS_PRIVATE_KEY=/tls/system-redis/system-redis-private.key
  • mount the system-redis secret fields REDIS_SSL_CA, REDIS_SSL_CERT, REDIS_SSL_KEY as volumes, so that the corresponding files on the pod contain the certificates.
Note

For one-way SSL connections, add all 3scale fields to system-redis secret, but leave REDIS_SSL_CERT and REDIS_SSL_KEY content empty.

3.1.4.2. Backend Redis
Copy link

3.1.4.2.1. Backend storage database
Copy link

To enable TLS connections for Backend storage database:

  1. Set spec.backend.backendRedisTLSEnabled to true in the APIManager custom resource. Example: 

    apiVersion: apps.3scale.net/v1alpha1
kind: APIManager
spec:
  backend:
    backendRedisTLSEnabled: true

  2. Add the following fields to the backend-redis secret (see the expected format):

    • REDIS_SSL_CA
    • REDIS_SSL_CERT
    • REDIS_SSL_KEY

When backendRedisTLSEnabled is set to true, and the SSL fields are set correctly in the backend-redis secret, the operator updates the System component pods (system-app and system-sidekiq) and the Backend component pods (backend-worker, backend-cron, and backend-listener):

  • set the following environment variables in System component pods:

    • BACKEND_REDIS_SSL=1
    • BACKEND_REDIS_CA_FILE=/tls/backend-redis/backend-redis-ca.crt
    • BACKEND_REDIS_CLIENT_CERT=/tls/backend-redis/backend-redis-client.crt
    • BACKEND_REDIS_PRIVATE_KEY=/tls/backend-redis/backend-redis-private.key

  • set the following environment variables in Backend component pods:

    • CONFIG_REDIS_SSL=1
    • CONFIG_REDIS_CA_FILE=/tls/backend-redis/backend-redis-ca.crt
    • CONFIG_REDIS_CERT=/tls/backend-redis/backend-redis-client.crt
    • CONFIG_REDIS_PRIVATE_KEY=/tls/backend-redis/backend-redis-private.key
  • mount the backend-redis secret fields REDIS_SSL_CA, REDIS_SSL_CERT, REDIS_SSL_KEY as volumes on the System and Backend component pods, so that the corresponding files on the pod contain the certificates (the paths are as specified above).
3.1.4.2.2. Backend queues database
Copy link

To enable TLS connections for Backend queues database:

  1. Set spec.backend.queuesRedisTLSEnabled to true in the APIManager custom resource. Example: 

    apiVersion: apps.3scale.net/v1alpha1
kind: APIManager
spec:
  backend:
    queuesRedisTLSEnabled: true

  2. Add the following fields to the backend-redis secret (see the expected format):

    • REDIS_SSL_QUEUES_CA
    • REDIS_SSL_QUEUES_CERT
    • REDIS_SSL_QUEUES_KEY

When queuesRedisTLSEnabled is set to true, and the SSL fields are set correctly in the backend-redis secret, the operator updates the Backend component pods backend-worker, backend-cron, and backend-listener:

  • set the following environment variables:

    • CONFIG_QUEUES_SSL=1
    • CONFIG_QUEUES_CA_FILE=/tls/queues/config-queues-ca.crt
    • CONFIG_QUEUES_CERT=/tls/queues/config-queues-client.crt
    • CONFIG_QUEUES_PRIVATE_KEY=/tls/queues/config-queues-private.key
  • mount the backend-redis secret fields REDIS_SSL_QUEUES_CA, REDIS_SSL_QUEUES_CERT, REDIS_SSL_QUEUES_KEY as volumes, so that the corresponding files on the pod contain the certificates.
Note

For one-way SSL connections, add all 3 fields to backend-redis secret, but leave REDIS_SSL_QUEUES_CERT and REDIS_SSL_QUEUES_KEY content empty.

3.1.4.3. Format of the SSL fields in the secrets
Copy link

When configuring the secrets system-redis and backend-redis, the SSL-related fields must contain certificates in PEM format. For example ([…​] indicates an omitted part): 

apiVersion: v1
kind: Secret
type: Opaque
metadata:
  name: system-redis
stringData:
  SENTINEL_HOSTS: ""
  SENTINEL_ROLE: ""
  URL: rediss://system-redis.example.com:6380
  REDIS_SSL_CA: |
    -----BEGIN CERTIFICATE-----
    MIIFkzCCA3ugAwIBAgIUAc92l4sImRI0Nktx1FYmDDFM0BowDQYJKoZIhvcNAQEL
    [...]
    Np+qxpIYONtIlOBkLufWHHFoIwhRgml81Qzw2369BuemKecYtNaC
    -----END CERTIFICATE-----
  REDIS_SSL_CERT: |
    -----BEGIN CERTIFICATE-----
    MIIFfzCCA2egAwIBAgIUMware32HDI2wJlGgX//kMIaFUWEwDQYJKoZIhvcNAQEL
    [...]
    12ZCEH8adSckCflpBKgruSAtOQ==
    -----END CERTIFICATE-----
  REDIS_SSL_KEY: |
    -----BEGIN PRIVATE KEY-----
    MIIJQwIBADANBgkqhkiG9w0BAQEFAASCCS0wggkpAgEAAoICAQDJvzBzCvU+zL5Y
    [...]
    pdalfrg+aI3dSMpubjKwbnyMQC8OgRs=
    -----END PRIVATE KEY-----

Note that the fields REDIS_SSL_CA and REDIS_SSL_QUEUES_CA are only required if the client certificates are issued by a Certificate Authority (CA) that is not contained in to the list of CAs trusted on the system in the corresponding pod images, as in case of self-signed certificates.

3.1.4.4. Using TLS with sentinels
Copy link

If TLS is enabled (backendRedisTLSEnabled, queuesRedisTLSEnabled or systemRedisTLSEnabled fields are set to true in the APIManager custom resource), Sentinels must also use TLS communication. All connection URLS (in SENTINEL_HOSTS, REDIS_STORAGE_SENTINEL_HOSTS or/and REDIS_QUEUES_SENTINEL_HOSTS fields in the secrets) must use the secure schema rediss://.

3.2. Setting up Redis for zero downtime
Copy link

High availability is provided for most components of 3scale by the OpenShift Container Platform (OCP). The different components can be deployed in multiple replicas across different OpenShift nodes, so if one node goes down, the other nodes can continue to serve traffic.

In order to provide high availability (HA) for 3scale, it is important that the underlying databases, including the Redis databases, also work in high availability (HA) mode.

For the Redis database, it is not possible to provide high availability using simple OpenShift deployments (for example, Deployment or StatefulSet resources) alone. If the Redis pod comes to a stop, or if the OpenShift Container Platform stops it, a new pod is automatically created. Persistent storage will restore the data so the pod continues to work. In these scenarios, there will be a small amount of downtime while the new pod starts. You can reduce downtime by preinstalling the Redis images onto all nodes that have Redis deployed to them. This will speed up the pod restart time, however does not eliminate downtime completely.

To achieve high availability (HA) for Redis databases, more complex Redis configurations or managed cloud solutions are required. Example solutions include:

Note
  • Red Hat does not provide support for the above mentioned services. The mention of any such services does not imply endorsement by Red Hat of the products or services. You agree that Red Hat is not responsible or liable for any loss or expenses that may result due to your use of (or reliance on) any external content.
  • Ensure that the version provided by these services is compatible with 3scale. For more details, see Red Hat 3scale API Management Supported Configurations.
  • Ensure that the Redis solution you choose does not use Redis Cluster topology, or sharding, as they are not supported by 3scale.
  • Some Redis services do not support logical database separation (multiple databases in a single Redis instance). In such cases, you must use a different Redis instance for each database used by 3scale.

You can configure Backend Redis databases, System Redis database, or both, to work in high availability (HA) mode. Backend Redis databases are more critical to run in HA mode, as they are used for authorizing the API requests, and a downtime in these databases will lead to downtime of the API services managed by 3scale. The System Redis database is mainly used for background job processing, and a downtime in this database will not lead to downtime of the API services, however it will affect some functionality of the 3scale application.

To configure Redis (not Redis Sentinel), you need to update the backend-redis and system-redis secrets with the connection details of the Redis instances. It is recommended to use a different Redis instance for each database. Update the URL field of the system-redis secret, and the fields REDIS_QUEUES_URL and REDIS_STORAGE_URL of the backend-redis secret with the connection strings of the Redis instances. If needed, you can also provide authentication details (username and/or password) by either adding them to the Redis connection string, or by setting the corresponding fields in the secrets, see Configuring Redis databases for details about the available fields.

3.2.1.1. Redis Sentinel configuration
Copy link

To configure Redis Sentinel with 3scale, you need to update the backend-redis and system-redis secrets with the following connection details:

  • REDIS_STORAGE_SENTINEL_HOSTS, REDIS_QUEUES_SENTINEL_HOSTS in backend-redis secret and SENTINEL_HOSTS in system-redis secret must contain a comma-separated list of Redis Sentinel hosts and ports.
  • REDIS_STORAGE_SENTINEL_ROLE, REDIS_QUEUES_SENTINEL_ROLE in backend-redis secret and SENTINEL_ROLE in system-redis secret must contain the role of the Redis instance to connect to via Sentinel. Accepted values: master or slave.
  • REDIS_STORAGE_URL, REDIS_QUEUES_URL in backend-redis secret and URL in system-redis secret must contain the name of the redis master group configured in Redis Sentinel.
  • Optionally, provide authentication details (username and/or password) by either adding them to the Redis connection string, or by setting the corresponding fields in the secrets.
  • Refer to see Configuring Redis databases for details about the available fields and their formats.

Example of the backend-redis secret using Redis Sentinel

apiVersion: v1
kind: Secret
type: Opaque
metadata:
  name: backend-redis
stringData:
  REDIS_STORAGE_URL: "redis://backend-redis-storage"
  REDIS_STORAGE_SENTINEL_HOSTS: "sentinel-0.example.com:26379,sentinel-1.example.com:26379,sentinel-2.example.com:26379"
  REDIS_STORAGE_SENTINEL_ROLE: "master"
  REDIS_STORAGE_SENTINEL_USERNAME: "myuser"
  REDIS_STORAGE_SENTINEL_PASSWORD: "mypassword"
  REDIS_QUEUES_URL: "redis://backend-redis-queues"
  REDIS_QUEUES_SENTINEL_HOSTS: "sentinel-0.example.com:26379,sentinel-1.example.com:26379, sentinel-2.example.com:26379"
  REDIS_QUEUES_SENTINEL_USERNAME: "myuser"
  REDIS_QUEUES_SENTINEL_PASSWORD: "mypassword"

Example of the system-redis secret using Redis Sentinel

apiVersion: v1
kind: Secret
type: Opaque
metadata:
  name: system-redis
stringData:
  URL: "redis://system-redis"
  SENTINEL_HOSTS: "sentinel-0.example.com:26379,sentinel-1.example.com:26379,sentinel-2.example.com:26379"
  SENTINEL_ROLE: "master"
  REDIS_SENTINEL_USERNAME: "myuser"
  REDIS_SENTINEL_PASSWORD: "mypassword"

3.3. Additional information
Copy link

Red Hat logoGithubredditYoutubeTwitter

Learn

Try, buy, & sell

Communities

About Red Hat

We deliver hardened solutions that make it easier for enterprises to work across platforms and environments, from the core datacenter to the network edge.

Making open source more inclusive

Red Hat is committed to replacing problematic language in our code, documentation, and web properties. For more details, see the Red Hat Blog.

About Red Hat Documentation

We help Red Hat users innovate and achieve their goals with our products and services with content they can trust. Explore our recent updates.

Legal Notice

Theme

© 2026 Red HatBack to top