{
  "id": "modules",
  "title": "Configure modules",
  "url": "https://redis.io/docs/latest/operate/kubernetes/8.0/re-databases/modules/",
  "summary": "Deploy Redis Enterprise databases with modules using the Redis Enterprise operator for Kubernetes.",
  "content": "\nRedis 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.\n\n## Prerequisites\n\nBefore you begin, verify the following:\n\n- [Redis Enterprise operator deployed](https://redis.io/docs/latest/operate/kubernetes/deployment/quick-start) in your Kubernetes cluster\n- [Redis Enterprise cluster (REC)](https://redis.io/docs/latest/operate/kubernetes/re-clusters) running and in a healthy state\n\n## Bundled modules\n\nRedis 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.\n\n### Available bundled modules\n\n| Module | Name | Description | Capabilities |\n|--------|------|-------------|--------------|\n| **[RediSearch](https://redis.io/docs/latest/develop/ai/search-and-query/)** | `search` | Full-text search and secondary indexing | Query, aggregation, full-text search, vector similarity search |\n| **[RedisJSON](https://redis.io/docs/latest/develop/data-types/json)** | `ReJSON` | JSON data type support | Store, update, and query JSON documents |\n| **[RedisTimeSeries](https://redis.io/docs/latest/develop/data-types/timeseries)** | `timeseries` | Time series data structures | Ingest and query time series data with downsampling and aggregation |\n| **[RedisBloom](https://redis.io/docs/latest/develop/data-types/probabilistic)** | `bf` | Probabilistic data structures | Bloom filters, Cuckoo filters, Count-Min Sketch, Top-K |\n\n\nWhen configuring databases with modules, use the `NAME` field (for example, `search` or `ReJSON`) instead of the `DISPLAY_NAME` field.\n\n\n### Automatic enablement in Redis 8 and later\n\nFor 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.\n\n| Database type | Automatically enabled capabilities |\n|---------------|------------------------------------|\n| RAM-only | [Search and query](https://redis.io/docs/latest/operate/oss_and_stack/stack-with-enterprise/search)\u003cbr /\u003e[JSON](https://redis.io/docs/latest/operate/oss_and_stack/stack-with-enterprise/json)\u003cbr /\u003e[Time series](https://redis.io/docs/latest/operate/oss_and_stack/stack-with-enterprise/timeseries)\u003cbr /\u003e[Probabilistic](https://redis.io/docs/latest/operate/oss_and_stack/stack-with-enterprise/bloom)  |\n| Flash-enabled ([Redis Flex](https://redis.io/docs/latest/operate/rs/databases/flash)) | [JSON](https://redis.io/docs/latest/operate/oss_and_stack/stack-with-enterprise/json)\u003cbr /\u003e[Probabilistic](https://redis.io/docs/latest/operate/oss_and_stack/stack-with-enterprise/bloom) |\n| [Active-Active](https://redis.io/docs/latest/operate/rs/databases/active-active)\u003csup\u003e[1](#enabled-modules-table-note-1)\u003c/sup\u003e | [Search and query](https://redis.io/docs/latest/operate/oss_and_stack/stack-with-enterprise/search/search-active-active)\u003cbr /\u003e[JSON](https://redis.io/docs/latest/operate/oss_and_stack/stack-with-enterprise/json) |\n\n1. \u003ca name=\"enabled-modules-table-note-1\"\u003e\u003c/a\u003eUpgrading existing Active-Active databases to Redis version 8 does not automatically enable these capabilities. Only new Active-Active databases created with Redis version 8 enable these capabilities by default.\n\nFor databases using Redis versions earlier than 8, explicitly specify bundled modules in the `spec.moduleList` field when you create the database.\n\n### Check available module versions\n\nTo see which bundled module versions are available in your cluster, run the following command:\n\n```bash\nkubectl get rec \u003ccluster-name\u003e -o jsonpath='{.status.modules}' | jq\n```\n\nThis command displays all modules (both bundled and user-defined) installed in the cluster and their available versions.\n\n### Bundled vs. user-defined modules\n\nThe following table shows the key differences between bundled and user-defined modules:\n\n| Aspect | Bundled modules | User-defined modules |\n|--------|----------------|---------------------|\n| **Installation** | Pre-installed with Redis Enterprise | Must be added to the REC spec |\n| **Availability** | Immediately available | Available after you add them to the REC |\n| **Versions** | Bundled with the Redis Enterprise version | Specified by URL in the REC spec |\n| **Examples** | RediSearch, RedisJSON, RedisTimeSeries, RedisBloom | RedisGears, custom modules |\n| **Redis 8 and later behavior** | Automatically enabled for compatible database types | Must be explicitly specified |\n\n## User-defined modules\n\nUser-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.\n\n**Limitations:**\n\n- **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.\n\n- **Redis on Flash**: User-defined modules are fully supported with Redis on Flash databases.\n\n### Add user-defined modules to the REC\n\nTo 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.\n\n\nAdd 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.\n\n\n1. Edit your REC custom resource:\n\n    ```sh\n    kubectl edit rec \u003ccluster-name\u003e\n    ```\n\n2. Add the `userDefinedModules` section to the `spec`:\n\n    ```yaml\n    spec:\n      userDefinedModules:\n        - name: \"custom-module\"\n          source:\n            https:\n              url: \"https://modules.company.com/custom-module-v1.0.zip\"\n              credentialsSecret: \"module-repo-creds\"\n    ```\n\n3. If your module repository requires authentication, create a secret with your credentials:\n\n    ```sh\n    kubectl create secret generic module-repo-creds \\\n      --from-literal=username=\u003cyour-username\u003e \\\n      --from-literal=password=\u003cyour-password\u003e\n    ```\n\nIf you use [HashiCorp Vault integration](https://redis.io/docs/latest/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.\n\n### Module naming requirements\n\nThe `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.\n\nFor example, if your module manifest contains the following:\n\n```json\n{\n  \"module_name\": \"rg\",\n  \"display_name\": \"RedisGears\",\n  \"semantic_version\": \"1.2.5\"\n}\n```\n\nYou can use either `\"rg\"` or `\"RedisGears\"` as the `name` value in your REC spec.\n\n\nIf the names don't match, the operator can't validate the module. This can lead to preventable errors during database creation or upgrades.\n\n\n### Edit user-defined modules\n\nTo modify the user-defined modules list, complete the following steps:\n\n1. Edit the REC custom resource:\n\n    ```sh\n    kubectl edit rec \u003ccluster-name\u003e\n    ```\n\n1. Update the `userDefinedModules` section:\n   - **Add new modules**: Append them to the list.\n   - **Update module URLs**: Change the `url` field for existing modules.\n   - **Update credentials**: Change the `credentialsSecret` reference.\n\n1. Save your changes. The operator validates and applies the updates.\n\n\nDon't remove modules that are currently in use by any database. The operator rejects the change and puts the REC into an error state.\n\n\n\nChanges 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.\n\n\n### Verify user-defined modules\n\nAfter you add user-defined modules to the REC, verify that they're available:\n\n```sh\nkubectl get rec \u003ccluster-name\u003e -o jsonpath='{.spec.userDefinedModules}' | jq\n```\n\nYou can also check the REC status for validation errors:\n\n```sh\nkubectl describe rec \u003ccluster-name\u003e\n```\n\nLook for events or status messages related to module validation in the output.\n\n## Upgrade with modules\n\nThe upgrade process differs depending on whether you use bundled modules or user-defined modules.\n\n### Module version selection\n\nWhen 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.\n\nFor 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.\n\n### Upgrade with bundled modules\n\nFor databases using bundled modules (RediSearch, RedisJSON, RedisTimeSeries, RedisBloom):\n\n- **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.\n\n- **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.\n\n### Upgrade with user-defined modules\n\nFor databases using user-defined modules, you must take additional steps during cluster upgrades:\n\n1. Set `autoUpgradeRedisEnterprise` to `false` in your REC spec before upgrading.\n\n1. 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.\n\n1. After the cluster upgrade completes, you can re-enable `autoUpgradeRedisEnterprise` if desired.\n\nFor detailed upgrade instructions, see the following:\n\n- [Upgrade a Redis Enterprise cluster (REC)](https://redis.io/docs/latest/operate/kubernetes/upgrade/upgrade-redis-cluster)\n- [Upgrade Redis Enterprise on OpenShift](https://redis.io/docs/latest/operate/kubernetes/upgrade/openshift-cli)\n\n## Troubleshooting\n\nThis section covers common issues you might encounter when working with user-defined modules.\n\n### Module validation errors\n\nModule validation errors occur when the operator can't validate a user-defined module. Common causes include incorrect URLs, authentication failures, or invalid module manifests.\n\n**Symptoms:**\n\n- REC status shows validation errors\n- Events indicate module download or validation failures\n- Databases fail to create with module-related errors\n\n**Diagnosis:**\n\nCheck the REC status for validation errors:\n\n```sh\nkubectl describe rec \u003ccluster-name\u003e\n```\n\nLook for error messages related to modules in the Events section.\n\n**Resolution:**\n\n1. **Verify the module URL is accessible:**\n\n    ```sh\n    curl -I \u003cmodule-url\u003e\n    ```\n\n2. **Check credentials secret exists and has correct values:**\n\n    ```sh\n    kubectl get secret \u003ccredentials-secret-name\u003e -o yaml\n    ```\n\n3. **Verify the module manifest (`module.json`) is valid:**\n\n    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`.\n\n4. **Ensure the `name` field in the REC spec matches the module manifest:**\n\n    The `name` must match either `module_name` or `display_name` from the module's `module.json` file. See [Module naming requirements](#module-naming-requirements) for details.\n\n### Bootstrap failures\n\nBootstrap failures occur when the Redis Enterprise cluster fails to start due to module-related issues.\n\n**Symptoms:**\n\n- REC pods fail to reach Running state\n- Operator logs show module-related errors during bootstrap\n- Cluster remains in a non-ready state\n\n**Diagnosis:**\n\nCheck the operator logs:\n\n```sh\nkubectl logs -l name=redis-enterprise-operator -n \u003cnamespace\u003e\n```\n\nCheck the REC pod logs:\n\n```sh\nkubectl logs \u003crec-pod-name\u003e -n \u003cnamespace\u003e\n```\n\n**Resolution:**\n\n1. **Remove problematic modules from the REC spec:**\n\n    Edit the REC and remove or comment out the problematic module from the `userDefinedModules` list:\n\n    ```sh\n    kubectl edit rec \u003ccluster-name\u003e\n    ```\n\n2. **Wait for the cluster to recover:**\n\n    ```sh\n    kubectl get rec \u003ccluster-name\u003e -w\n    ```\n\n3. **Fix the module configuration and re-add it:**\n\n    After the cluster is running, correct the module URL, credentials, or manifest issues, then add the module back to the REC spec.\n\n### Module not found errors\n\nModule not found errors occur when you try to create a database that uses a module that isn't defined in the REC.\n\n**Symptoms:**\n\n- REDB creation fails with admission webhook errors\n- Error message indicates the module is not found in the REC\n- Database remains in a pending or failed state\n\n**Diagnosis:**\n\nCheck the REDB creation error:\n\n```sh\nkubectl describe redb \u003cdatabase-name\u003e\n```\n\nVerify which modules are defined in the REC:\n\n```sh\nkubectl get rec \u003ccluster-name\u003e -o jsonpath='{.spec.userDefinedModules}' | jq\n```\n\n**Resolution:**\n\n1. **Add the missing module to the REC:**\n\n    See [Add user-defined modules to the REC](#add-user-defined-modules-to-the-rec) for detailed instructions.\n\n2. **Wait for the module to be validated:**\n\n    ```sh\n    kubectl describe rec \u003ccluster-name\u003e\n    ```\n\n    Look for successful validation in the Events section.\n\n3. **Retry database creation:**\n\n    After the module is available in the REC, the database creation should succeed automatically, or you can delete and recreate the REDB.\n\n## Related information\n\n- [Redis modules documentation](https://redis.io/docs/latest/develop/reference/modules) - Official Redis modules documentation\n- [REDB API reference](https://redis.io/docs/latest/operate/kubernetes/reference/api/redis_enterprise_database_api) - Complete API specification for REDB resources\n- [REAADB API reference](https://redis.io/docs/latest/operate/kubernetes/reference/api/redis_enterprise_active_active_database_api) - API reference for Active-Active databases\n\n### Redis Software documentation\n\n- [Add modules to a cluster](https://redis.io/docs/latest/operate/oss_and_stack/stack-with-enterprise/install/add-module-to-cluster) - Install module packages on Redis Enterprise Software clusters\n- [Enable modules for a database](https://redis.io/docs/latest/operate/oss_and_stack/stack-with-enterprise/install/add-module-to-database) - Add modules to databases in Redis Enterprise Software\n- [Upgrade modules](https://redis.io/docs/latest/operate/oss_and_stack/stack-with-enterprise/install/upgrade-module) - Upgrade module versions in Redis Enterprise Software\n- [Module lifecycle](https://redis.io/docs/latest/operate/oss_and_stack/stack-with-enterprise/modules-lifecycle) - Module versioning and end-of-life schedule\n",
  "tags": ["docs","operate","kubernetes"],
  "last_updated": "2026-06-04T14:49:57+01:00"
}