Red Hat Summit Red Hat SummitSupportConsoleDevelopersStart a trialContact

Chapter 3. External Redis database configuration for high availability support in 3scale API Management

Important

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

High availability (HA) is provided for most components by the OpenShift Container Platform (OCP).

Note

When you externalize databases from a Red Hat 3scale API Management deployment, this means to provide isolation from the application and resilience against service disruptions at the database level. The resilience to service disruptions depends on the service level agreements (SLAs) provided by the infrastructure or platform provider where you host the databases. This is not offered by 3scale. For more details on externalizing of databases offered by your chosen deployment, see the associated documentation.

The database components for HA in Red Hat 3scale API Management include:

  • backend-redis: used for statistics storage and temporary job storage.
  • system-redis: provides temporary storage for background jobs for 3scale and is also used as a message bus for Ruby processes of system-app pods.

Both backend-redis and system-redis work with supported Redis high availability variants for Redis Sentinel and Redis Enterprise.

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. This is due to a limitation in Redis that does not support a multi-master setup. 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.

Set up Redis for zero downtime and configure back-end components for 3scale:

Prerequisites

  • A 3scale account with an administrator role.

3.1. Setting up Redis for zero downtime
Copy link

As a 3scale administrator, configure Redis outside of OCP if you require zero downtime. There are several ways to set it up using the configuration options of 3scale pods:

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.

As a 3scale administrator, configure Redis HA (failover) for the back-end component environment variables in the following deployment configurations: backend-cron, backend-listener, and backend-worker. These configurations are necessary for Redis HA in 3scale.

Note

If you want to use Redis with sentinels, you must provide sentinel configuration in either backend-redis, system-redis, or both secrets.

Follow these steps to create backend-redis and system-redis secrets accordingly:

Procedure

  1. Create the backend-redis and system-redis secrets with the fields below:

    backend-redis

    REDIS_QUEUES_SENTINEL_HOSTS
REDIS_QUEUES_SENTINEL_ROLE
REDIS_QUEUES_URL
REDIS_STORAGE_SENTINEL_HOSTS
REDIS_STORAGE_SENTINEL_ROLE
REDIS_STORAGE_URL
    Copy to Clipboard Toggle word wrap

    system-redis

    NAMESPACE
SENTINEL_HOSTS
SENTINEL_ROLE
URL
    Copy to Clipboard Toggle word wrap

    • When configuring for Redis with sentinels, the corresponding URL fields in backend-redis and system-redis refer to the Redis group in the format redis://[:redis-password@]redis-group[/db], where [x] denotes optional element x and redis-password, redis-group, and db are variables to be replaced accordingly:

      Example

      redis://:redispwd@mymaster/5
      Copy to Clipboard Toggle word wrap

    • The SENTINEL_HOSTS fields are comma-separated lists of sentinel connection strings in the following format: 

      redis://:sentinel-password@sentinel-hostname-or-ip:port
      Copy to Clipboard Toggle word wrap

      • For each element of the list, [x] denotes optional element x and sentinel-password, sentinel-hostname-or-ip, and port are variables to be replaced accordingly:

        Example

        :sentinelpwd@123.45.67.009:2711,:sentinelpwd@other-sentinel:2722
        Copy to Clipboard Toggle word wrap

    • The SENTINEL_ROLE fields are either master or slave.

  2. Deploy 3scale as indicated in Deploying 3scale API Management using the operator.

    1. Ignore the errors due to backend-redis and system-redis already present.
  1. Edit the backend-redis and system-redis secrets with all fields as shown in Deploying a fresh installation of 3scale API Management for HA.

  2. Make sure the following backend-redis environment variables are defined in the YAML specification of the Deployments backend-listener, backend-worker and backend-cron. 

    name: CONFIG_REDIS_SENTINEL_HOSTS
  valueFrom:
    secretKeyRef:
      key: REDIS_STORAGE_SENTINEL_HOSTS
      name: backend-redis
name: CONFIG_REDIS_SENTINEL_ROLE
  valueFrom:
    secretKeyRef:
      key: REDIS_STORAGE_SENTINEL_ROLE
      name: backend-redis
    Copy to Clipboard Toggle word wrap

  3. Make sure the following system-redis environment variables are defined in the YAML specification of the Deployments system-app and system-sidekiq. 

    name: REDIS_SENTINEL_HOSTS
  valueFrom:
    secretKeyRef:
      key: SENTINEL_HOSTS
      name: system-redis
name: REDIS_SENTINEL_ROLE
  valueFrom:
    secretKeyRef:
      key: SENTINEL_ROLE
      name: system-redis
    Copy to Clipboard Toggle word wrap

You can choose between using Redis Enterprise or Redis Sentinel to ensure HA for 3scale API Management. Follow the steps in each subsection to configure and deploy the appropriate Redis setup for your environment.

3.2.4.1. Using Redis Enterprise
Copy link

To configure Redis Enterprise for 3scale API Management, update the backend-redis and system-redis secrets with the connection string of the Redis Enterprise instances. Use a different Redis Enterprise instance for each database.

  1. Edit system-redis secret:

    1. Update the URL field with the connection string of the system Redis database.

  2. Edit backend-redis secret:

    1. Update the REDIS_QUEUES_URL field with the connection string of the Redis database for back-end queues.
    2. Update the REDIS_STORAGE_URL field with the connection string of the Redis database for back-end statistics storage.

The configuration for 3scale API Management with Redis Enterprise differs from a standard Redis integration. Redis Enterprise does not support logical separation of databases, rendering the "/db_index" portion of the typical URL unnecessary. The essential parameters for the Redis connection string include: 

redis[s]://[username[:password]@]host[:port]
Copy to Clipboard Toggle word wrap

Square brackets ([ ]) indicate an optional parameter sequence. Example values for valid connection strings include: 

redis://default:some-password@redisdb1.example.com
redis://redisdb2.example.com:6379
Copy to Clipboard Toggle word wrap

3.2.4.2. Using Redis Sentinel
Copy link

Note

You can optionally apply Redis Sentinels to any of the databases. However, Red Hat recommends applying Redis Sentinels to all of them for HA.

  1. Backend redis for statistics: update backend-redis secret and provide values for:

    • REDIS_STORAGE_URL
    • REDIS_STORAGE_SENTINEL_ROLE
    • REDIS_STORAGE_SENTINEL_HOSTS

  2. Backend redis for queue: update backend-redis secret and provide values for:

    • REDIS_QUEUES_URL
    • REDIS_QUEUES_SENTINEL_ROLE
    • REDIS_QUEUES_SENTINEL_HOSTS

  3. Set REDIS_STORAGE_SENTINEL_HOSTS and REDIS_QUEUES_SENTINEL_HOSTS to a comma-separated list of Redis Sentinels hosts and ports.

    REDIS_STORAGE_SENTINEL_ROLE and REDIS_QUEUES_SENTINEL_ROLE accept either master or slave.

    REDIS_STORAGE_URL and REDIS_QUEUES_URL accept values in the following format: 

    redis://<master-group>/{db}
    Copy to Clipboard Toggle word wrap
    Important

    <master-group> must correspond to the group name configured in Redis Sentinel.

    Example content of backend-redis secret: 

    REDIS_QUEUES_SENTINEL_HOSTS=10.0.4.45:16387,10.0.8.252:16388,10.0.7.48:16389
REDIS_QUEUES_SENTINEL_ROLE=master
REDIS_QUEUES_URL=redis://redis-cluster/5
REDIS_STORAGE_SENTINEL_HOSTS=10.119.4.45:16379,10.119.8.252:16380,10.119.7.48:16381
REDIS_STORAGE_SENTINEL_ROLE=master
REDIS_STORAGE_URL=redis://redis-cluster/6
    Copy to Clipboard Toggle word wrap

    In this example, values are plain text. However, Openshift Container Platform (OCP) expects value fields to be Base64-encoded.

  4. System redis for data: update system-redis secret and provide values for:

    • NAMESPACE
    • SENTINEL_HOSTS
    • SENTINEL_ROLE

    • URL

      Set SENTINEL_HOSTS to a comma-separated list of sentinels hosts and ports, for example: :sentinelpwd@123.45.67.009:2711,:sentinelpwd@other-sentinel:2722

Notes

  • The system-app and system-sidekiq components connect directly to back-end Redis for retrieving statistics.

    • As of 3scale 2.7, these system components can also connect to back-end Redis (storage) when using sentinels.

  • The system-app and system-sidekiq components uses only backend-redis storage, not backend-redis queues.

    • Changes made to the system components support backend-redis storage with sentinels.

3.3. Additional information
Copy link

Back to top
Red Hat logoGithubredditYoutubeTwitter

Learn

Try, buy, & sell

Communities

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.

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

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

Theme

© 2025 Red Hat