Configure modules

Deploy Redis Enterprise databases with modules using the Redis Enterprise operator for Kubernetes.

Redis Enterprise modules extend Redis functionality with additional data types, commands, and capabilities. Redis Enterprise versions 8.0.2 and later include several bundled modules that are automatically enabled for compatible database types. You can also add user-defined modules for additional functionality.

Prerequisites

Before you begin, verify the following:

• Redis Enterprise operator deployed in your Kubernetes cluster
• Redis Enterprise cluster (REC) running and in a healthy state

Bundled modules

Redis Enterprise includes several bundled modules that extend Redis functionality with additional data types, commands, and capabilities. Starting with Redis Enterprise version 8.0.2, these modules are automatically included and immediately available for use.

Available bundled modules

Automatic enablement in Redis 8 and later

For databases created with or upgraded to Redis version 8 or later, bundled modules are automatically enabled based on the database type. You don't need to specify them in the spec.moduleList field unless you want to use a specific version.

For databases using Redis versions earlier than 8, explicitly specify bundled modules in the spec.moduleList field when you create the database.

Check available module versions

To see which bundled module versions are available in your cluster, run the following command:

kubectl get rec <cluster-name> -o jsonpath='{.status.modules}' | jq

This command displays all modules (both bundled and user-defined) installed in the cluster and their available versions.

Bundled vs. user-defined modules

The following table shows the key differences between bundled and user-defined modules:

User-defined modules

User-defined modules are custom Redis modules that extend Redis functionality beyond the bundled modules. User-defined modules can include third-party modules like RedisGears or custom in-house modules developed for specific use cases.

Limitations:

• Active-Active databases: User-defined modules are not supported with Active-Active databases. Only bundled modules (RediSearch, RedisJSON, RedisTimeSeries, RedisBloom) can be used with Active-Active databases.

• Redis on Flash: User-defined modules are fully supported with Redis on Flash databases.

Add user-defined modules to the REC

To use user-defined modules with your databases, first add them to the Redis Enterprise cluster (REC) custom resource. This enables the operator to validate the modules and make them available for database creation.

1. Edit your REC custom resource:

   kubectl edit rec <cluster-name>
   

2. Add the userDefinedModules section to the spec:

   spec:
     userDefinedModules:
       - name: "custom-module"
         source:
           https:
             url: "https://modules.company.com/custom-module-v1.0.zip"
             credentialsSecret: "module-repo-creds"
   

3. If your module repository requires authentication, create a secret with your credentials:

   kubectl create secret generic module-repo-creds \
     --from-literal=username=<your-username> \
     --from-literal=password=<your-password>
   

Module naming requirements

The name field in the REC spec must match either the module_name or display_name value from the module's manifest file (module.json inside the module zip file). This enables the operator to validate the module.

For example, if your module manifest contains the following:

{
  "module_name": "rg",
  "display_name": "RedisGears",
  "semantic_version": "1.2.5"
}

You can use either "rg" or "RedisGears" as the name value in your REC spec.

Edit user-defined modules

To modify the user-defined modules list, complete the following steps:

1. Edit the REC custom resource:

   kubectl edit rec <cluster-name>
   

2. Update the userDefinedModules section:

   • Add new modules: Append them to the list.
   • Update module URLs: Change the url field for existing modules.
   • Update credentials: Change the credentialsSecret reference.

3. Save your changes. The operator validates and applies the updates.

Verify user-defined modules

After you add user-defined modules to the REC, verify that they're available:

kubectl get rec <cluster-name> -o jsonpath='{.spec.userDefinedModules}' | jq

You can also check the REC status for validation errors:

kubectl describe rec <cluster-name>

Look for events or status messages related to module validation in the output.

Upgrade with modules

The upgrade process differs depending on whether you use bundled modules or user-defined modules.

Module version selection

When multiple versions of a module are available in the cluster, Redis Enterprise selects the appropriate version based on the compatible_redis_version field in the module's manifest file (module.json). This field must match the Redis OSS version that the database is using.

For example, if your database uses Redis 7.2, Redis Enterprise selects the module version whose compatible_redis_version is 7.2. If no matching version is found, the module cannot be loaded.

Upgrade with bundled modules

For databases using bundled modules (RediSearch, RedisJSON, RedisTimeSeries, RedisBloom):

• Redis 8 and later: Bundled modules are automatically enabled and upgraded when you upgrade the database to Redis version 8 or later. You don't need to take any additional action. The module version is automatically selected based on the database's Redis version.

• Redis versions earlier than 8: Bundled modules are upgraded automatically when you upgrade the Redis Enterprise cluster. The bundled module versions are tied to the Redis Enterprise version, and the appropriate version is selected based on the database's Redis version.

Upgrade with user-defined modules

For databases using user-defined modules, you must take additional steps during cluster upgrades:

1. Set autoUpgradeRedisEnterprise to false in your REC spec before upgrading.

2. Add or update the userDefinedModules list in the REC spec with the new module versions before or during the cluster upgrade. Ensure that the new module versions include a compatible_redis_version field that matches the Redis version your databases will use after the upgrade.

3. After the cluster upgrade completes, you can re-enable autoUpgradeRedisEnterprise if desired.

For detailed upgrade instructions, see the following:

• Upgrade a Redis Enterprise cluster (REC)
• Upgrade Redis Enterprise on OpenShift

Troubleshooting

This section covers common issues you might encounter when working with user-defined modules.

Module validation errors

Module validation errors occur when the operator can't validate a user-defined module. Common causes include incorrect URLs, authentication failures, or invalid module manifests.

Symptoms:

• REC status shows validation errors
• Events indicate module download or validation failures
• Databases fail to create with module-related errors

Diagnosis:

Check the REC status for validation errors:

kubectl describe rec <cluster-name>

Look for error messages related to modules in the Events section.

Resolution:

1. Verify the module URL is accessible:

   curl -I <module-url>
   

2. Check credentials secret exists and has correct values:

   kubectl get secret <credentials-secret-name> -o yaml
   

3. Verify the module manifest (module.json) is valid:

   Download the module zip file and check that it contains a valid module.json file with required fields: module_name, display_name, semantic_version, commands, and compatible_redis_version.

4. Ensure the name field in the REC spec matches the module manifest:

   The name must match either module_name or display_name from the module's module.json file. See Module naming requirements for details.

Bootstrap failures

Bootstrap failures occur when the Redis Enterprise cluster fails to start due to module-related issues.

Symptoms:

• REC pods fail to reach Running state
• Operator logs show module-related errors during bootstrap
• Cluster remains in a non-ready state

Diagnosis:

Check the operator logs:

kubectl logs -l name=redis-enterprise-operator -n <namespace>

Check the REC pod logs:

kubectl logs <rec-pod-name> -n <namespace>

Resolution:

1. Remove problematic modules from the REC spec:

   Edit the REC and remove or comment out the problematic module from the userDefinedModules list:

   kubectl edit rec <cluster-name>
   

2. Wait for the cluster to recover:

   kubectl get rec <cluster-name> -w
   

3. Fix the module configuration and re-add it:

   After the cluster is running, correct the module URL, credentials, or manifest issues, then add the module back to the REC spec.

Module not found errors

Module not found errors occur when you try to create a database that uses a module that isn't defined in the REC.

Symptoms:

• REDB creation fails with admission webhook errors
• Error message indicates the module is not found in the REC
• Database remains in a pending or failed state

Diagnosis:

Check the REDB creation error:

kubectl describe redb <database-name>

Verify which modules are defined in the REC:

kubectl get rec <cluster-name> -o jsonpath='{.spec.userDefinedModules}' | jq

Resolution:

1. Add the missing module to the REC:

   See Add user-defined modules to the REC for detailed instructions.

2. Wait for the module to be validated:

   kubectl describe rec <cluster-name>
   

   Look for successful validation in the Events section.

3. Retry database creation:

   After the module is available in the REC, the database creation should succeed automatically, or you can delete and recreate the REDB.

Related information

• Redis modules documentation - Official Redis modules documentation
• REDB API reference - Complete API specification for REDB resources
• REAADB API reference - API reference for Active-Active databases

Redis Software documentation

• Add modules to a cluster - Install module packages on Redis Enterprise Software clusters
• Enable modules for a database - Add modules to databases in Redis Enterprise Software
• Upgrade modules - Upgrade module versions in Redis Enterprise Software
• Module lifecycle - Module versioning and end-of-life schedule