content/operate/kubernetes/re-databases/modules.md
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.
Before you begin, verify the following:
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.
| Module | Name | Description | Capabilities |
|---|---|---|---|
| [RediSearch]({{< relref "/develop/ai/search-and-query/" >}}) | search | Full-text search and secondary indexing | Query, aggregation, full-text search, vector similarity search |
| [RedisJSON]({{< relref "/develop/data-types/json" >}}) | ReJSON | JSON data type support | Store, update, and query JSON documents |
| [RedisTimeSeries]({{< relref "/develop/data-types/timeseries" >}}) | timeseries | Time series data structures | Ingest and query time series data with downsampling and aggregation |
| [RedisBloom]({{< relref "/develop/data-types/probabilistic" >}}) | bf | Probabilistic data structures | Bloom filters, Cuckoo filters, Count-Min Sketch, Top-K |
{{< note >}}
When configuring databases with modules, use the NAME field (for example, search or ReJSON) instead of the DISPLAY_NAME field.
{{< /note >}}
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.
{{<embed-md "rs-8-enabled-modules.md">}}
For databases using Redis versions earlier than 8, explicitly specify bundled modules in the spec.moduleList field when you create the database.
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.
The following table shows the key differences between bundled and user-defined modules:
| Aspect | Bundled modules | User-defined modules |
|---|---|---|
| Installation | Pre-installed with Redis Enterprise | Must be added to the REC spec |
| Availability | Immediately available | Available after you add them to the REC |
| Versions | Bundled with the Redis Enterprise version | Specified by URL in the REC spec |
| Examples | RediSearch, RedisJSON, RedisTimeSeries, RedisBloom | RedisGears, custom modules |
| Redis 8 and later behavior | Automatically enabled for compatible database types | Must be explicitly specified |
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.
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.
{{< warning >}} Add user-defined modules to the REC before you create any databases that use them. The admission controller validates that modules exist in the REC before allowing REDB creation. {{< /warning >}}
Edit your REC custom resource:
kubectl edit rec <cluster-name>
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"
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>
If you use [HashiCorp Vault integration]({{< relref "/operate/kubernetes/security/vault" >}}), store the module credentials in Vault instead of creating a Kubernetes secret. The credentialsSecret field will reference the secret name in Vault.
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.
{{< note >}} If the names don't match, the operator can't validate the module. This can lead to preventable errors during database creation or upgrades. {{< /note >}}
To modify the user-defined modules list, complete the following steps:
Edit the REC custom resource:
kubectl edit rec <cluster-name>
Update the userDefinedModules section:
url field for existing modules.credentialsSecret reference.Save your changes. The operator validates and applies the updates.
{{< warning >}} Don't remove modules that are currently in use by any database. The operator rejects the change and puts the REC into an error state. {{< /warning >}}
{{< note >}}
Changes to the userDefinedModules list trigger a rolling restart of the Redis Enterprise cluster pods. Plan module updates during a maintenance window to minimize potential impact on your databases.
{{< /note >}}
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.
The upgrade process differs depending on whether you use bundled modules or user-defined modules.
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.
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.
For databases using user-defined modules, you must take additional steps during cluster upgrades:
Set autoUpgradeRedisEnterprise to false in your REC spec before upgrading.
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.
After the cluster upgrade completes, you can re-enable autoUpgradeRedisEnterprise if desired.
For detailed upgrade instructions, see the following:
This section covers common issues you might encounter when working with user-defined modules.
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:
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:
Verify the module URL is accessible:
curl -I <module-url>
Check credentials secret exists and has correct values:
kubectl get secret <credentials-secret-name> -o yaml
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.
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 occur when the Redis Enterprise cluster fails to start due to module-related issues.
Symptoms:
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:
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>
Wait for the cluster to recover:
kubectl get rec <cluster-name> -w
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 occur when you try to create a database that uses a module that isn't defined in the REC.
Symptoms:
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:
Add the missing module to the REC:
See Add user-defined modules to the REC for detailed instructions.
Wait for the module to be validated:
kubectl describe rec <cluster-name>
Look for successful validation in the Events section.
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.