Adding a Module to a Cluster
We are constantly working to improve the modules. To get the latest features and fixes for a module, you must upgrade the module in Redis.
- Modules are not supported in Redis Enterprise Software on RHEL/CentOS 6.x.
- We recommend that you test module upgrade commands in a test environment before you upgrade modules in a production environment. The module upgrade arguments are not validated during the upgrade process and incorrect arguments can cause unexpected downtime.
- Upgrading a cluster with a single node does not load the new modules that are bundled with the new cluster version.
- Before you upgrade a database with RediSearch Module to Redis 5.0, you must upgrade the RediSearch Module to version 1.4.2 or above.
Getting the packaged modules
- Redis Enterprise modules - To download the upgrades to the modules, go to the Redis Labs Download Center.
- Custom packaged modules - Either download the custom packaged module from the developer or package the module yourself.
Adding a module to a Redis Enterprise Software cluster
You can add a module to your cluster using:
- The REST API - For all modules, but modules with dependencies must use the
/v2/modules
endpoint. - The admin console - For modules without dependencies, such as RedisGraph.
Adding a module using the REST API
Modules that have dependencies can only be added from the REST API.
The module.json
file in the module package lists the dependencies for the module and the URL to download each dependency.
When you add the module, the master node downloads and installs the dependencies.
Then the other nodes in the cluster copy the dependencies from the master node.
- If your master node does not have connectivity to the internet, copy the dependencies to a local server and set the URLs in the
module.json
file to point to the local location. - To remove a module with dependencies from a cluster, you must use a DELETE action with the
/v2/modules
endpoint.
To add a module package to the cluster using the REST API:
-
Copy the module package to a node in the cluster, for example:
curl https://redismodules.s3.amazonaws.com/redisgears/redisgears.linux-bionic-x64.1.0.3.zip -o /tmp/redisgears.linux-bionic-x64.1.0.3.zip
-
POST the modules to the
/v2/modules
endpoint, for example:curl -k -u "admin@redislabs.com:<password>" -F "module=@/tmp/redisgears.linux-bionic-x64.1.0.3.zip" https://localhost:9443/v2/modules
The response includes an action ID that you can use with the
/v1/actions
endpoint to see the progress of the action, such as:$ curl -k -u "admin@redislabs.com:<password>" https://localhost:9443/v1/actions/d1b6d8c2-7a95-4a4d-8ce8-6e6b6f12308f {"action_uid":"d1b6d8c2-7a95-4a4d-8ce8-6e6b6f12308f","module_uid":"9f52147d8036b08903ca3a8bca87da00","name":"module_installation","progress":"100","status":"completed","task_id":"d1b6d8c2-7a95-4a4d-8ce8-6e6b6f12308f"}
Note:You can also use the/v1/modules
endpoint, but modules with dependencies are blocked from using that endpoint. -
When the action is complete, log into the cluster admin console and go to
settings
>redis modules
to see the module in the list.
Adding a module using the admin console
To add a module package to the cluster using the admin console:
-
In the Redis Enterprise admin console, go to the: settings
-
In redis modules, click Add Module.
-
Browse to the packaged module and upload it.
-
Note the version number of the new module version.
If you don’t see the updated module version, refresh the page.
Upgrading the module for the database
After you add and updated module to the cluster, go to the configuration of the databases that use the module. The database configuration shows that a new version of the module is available for the database.
To upgrade a module that is installed on a cluster:
-
Connect to the terminal of a node in the cluster
-
Run
rladmin status
to list the databases on the node. -
Copy the name of the database that uses the module that you want to upgrade.
-
Find the exact module name and version:
- Extract the module archive (zip) file.
- Open the JSON file.
- Find the module name and version number in the file.
An example of the JSON file for the RediSearch module is:
-
To see the versions of the modules on the cluster, run either:
rladmin status modules
- Shows the latest modules available on the cluster and the modules used by databases.rladmin status modules all
- Shows all of the modules available on the cluster and the modules used by databases.
-
To upgrade a database to the latest version of Redis and its modules to the latest version without changing the module arguments, run:
rladmin upgrade db < database_name | database_ID > latest_with_modules
- To upgrade the modules without upgrading the database to the latest Redis version, use
keep_redis_version
after you specify the database. - If you want to specify the modules to upgrade, use
and module module_name <module_name> version <new_module_version_number> module_args "<module arguments>" ]
for each module. For the modules arguments you can either use:module_args "<module_arguments>"
to replace the existing module arguments.module_args ""
without arguments to remove the existing module arguments.module_args keep_args
to use the existing module arguments.
- If you want to update multiple modules, use the
and module
parameter for each module.
- To upgrade the modules without upgrading the database to the latest Redis version, use
Examples
Here are some examples of module upgrades:
-
To upgrade keep the current version of Redis and use the latest version of the modules that are used by the database:
rladmin upgrade db shopping_cart keep_redis_version latest_with_modules
-
To upgrade the database to the latest Redis version and upgrade RediSearch to 1.6.7 with the specified arguments:
rladmin upgrade db shopping_cart and module db_name shopping_cart module_name ft version 10607 module_args "PARTITIONS AUTO"
-
To upgrade the database to the latest redis and upgrade RedisBloom to version 2.2.1 without arguments:
rladmin upgrade db db:3 and module db_name shopping_cart module_name bf version 20201 module_args ""
-
To upgrade RedisJSON to 1.0.4 with the existing arguments and RedisBloom to version 2.2.1 without arguments:
rladmin upgrade module db_name MyDB module_name ReJSON version 10004 module_args keep_args and module db_name MyDB module_name bf version 20201 module_args ""
-
To upgrade the database to use the latest version of Redis and use the latest version of the modules that are used by the database:
rladmin upgrade db shopping_cart latest_with_modules