From 0032974cf1b746bd8a77a6255f93e3f40987b354 Mon Sep 17 00:00:00 2001 From: Kaitlyn Michael Date: Tue, 9 Dec 2025 11:32:48 -0600 Subject: [PATCH 01/16] page improvements --- .../operate/kubernetes/upgrade/upgrade-redis-cluster.md | 9 ++++----- 1 file changed, 4 insertions(+), 5 deletions(-) diff --git a/content/operate/kubernetes/upgrade/upgrade-redis-cluster.md b/content/operate/kubernetes/upgrade/upgrade-redis-cluster.md index abf87c8a4e..c035ae5683 100644 --- a/content/operate/kubernetes/upgrade/upgrade-redis-cluster.md +++ b/content/operate/kubernetes/upgrade/upgrade-redis-cluster.md @@ -164,11 +164,10 @@ Before beginning the upgrade of the Redis Enterprise cluster, check the [Redis E After the operator upgrade is complete, you can upgrade Redis Enterprise cluster (REC). -### Upgrade an REC with an Active-Active database +{{}} We recommend upgrading all participating clusters to the same operator version. - -If you are upgrading from a preview version of the Active-Active controller, you can remove the following environment variables: `ACTIVE_ACTIVE_DATABASE_CONTROLLER_ENABLED`, `REMOTE_CLUSTER_CONTROLLER_ENABLED`, and `ENABLE_ALPHA_FEATURES`. +{{}} ### Edit `redisEnterpriseImageSpec` in the REC spec @@ -214,7 +213,7 @@ To see the status of the current rolling upgrade, run: kubectl rollout status sts ``` -### Upgrade databases +## Upgrade databases After the cluster is upgraded, you can upgrade your databases. @@ -224,7 +223,7 @@ For Active-Active databases, the `redis.Version` change only needs to be applied If your REAADB uses supported modules, keep the existing `moduleList` version numbers unchanged when upgrading `redisVersion`. The database will automatically use the module versions that are bundled with the new Redis version, regardless of what versions are specified in `moduleList`. After the upgrade is complete, you can optionally change the old version numbers from `moduleList`, but this change has no functional impact. -#### General upgrade notes +### Upgrade policy Note that if your cluster [`redisUpgradePolicy`]({{}}) or your database [`redisVersion`]({{< relref "/operate/kubernetes/reference/api/redis_enterprise_database_api#redisversion" >}}) are set to `major`, you won't be able to upgrade those databases to minor versions. See [Redis upgrade policy]({{< relref "/operate/rs/installing-upgrading/upgrading#redis-upgrade-policy" >}}) for more details. From 1ffb689d869f3dee9990c0a3d3c16abae9b64846 Mon Sep 17 00:00:00 2001 From: Kaitlyn Michael Date: Tue, 9 Dec 2025 12:00:41 -0600 Subject: [PATCH 02/16] upgrade prereqs --- .../upgrade/upgrade-redis-cluster.md | 45 ++++++++++++------- 1 file changed, 28 insertions(+), 17 deletions(-) diff --git a/content/operate/kubernetes/upgrade/upgrade-redis-cluster.md b/content/operate/kubernetes/upgrade/upgrade-redis-cluster.md index c035ae5683..907bb43e73 100644 --- a/content/operate/kubernetes/upgrade/upgrade-redis-cluster.md +++ b/content/operate/kubernetes/upgrade/upgrade-redis-cluster.md @@ -35,23 +35,13 @@ Check the [Redis Enterprise for Kubernetes release notes]({{}}). -### Module compatibility +### User-defined modules -Some Redis Enterprise operator versions may require specific module versions or involve changes to the underlying operating system. If your databases use modules, check the release notes for your target version to determine if you need to manually install updated modules. +If your databases use user-defined modules (custom non-bundled modules): -To see which modules you have installed, run: - -```sh -curl -k -u : -X GET https://localhost:9443/v1/modules | jq -r 'map([.module_name, .semantic_version, (.platforms | keys)]) | .[] | .[0] as $name | .[1] as $version | .[2][] | $name + "-" + $version + "-" + .' | sort -``` - -To see which modules are currently in use, run: - -```sh -curl -k -u : -X GET https://localhost:9443/v1/bdbs | jq -r '.[].module_list | map(.module_name + "-" + .semantic_version) | .[]' -``` - -See [Upgrade modules]({{}}) for details on how to upgrade modules with the `rladmin` tool. +- Set `autoUpgradeRedisEnterprise: false` in the REC custom resource before upgrading the operator. +- Define the user-defined modules in the REC custom resource before upgrading the database. +See [user-defined modules](#user-defined-modules) for more details. ### Valid license @@ -164,9 +154,8 @@ Before beginning the upgrade of the Redis Enterprise cluster, check the [Redis E After the operator upgrade is complete, you can upgrade Redis Enterprise cluster (REC). - {{}} -We recommend upgrading all participating clusters to the same operator version. +For Active-Active databases, we recommend upgrading all participating clusters to the same operator version. {{}} ### Edit `redisEnterpriseImageSpec` in the REC spec @@ -187,6 +176,20 @@ We recommend upgrading all participating clusters to the same operator version. versionTag: ``` +1. Define any user-defined modules used by databases in the cluster. + + ```YAML + spec: + userDefinedModules: + - name: "custom-module" + source: + https: + url: "https://modules.company.com/search-v2.1.zip" + credentialsSecret: "module-repo-creds" + ``` + + The `name` field match the `display_name` or `module_name` that appears in the module manifest. This enables the operator to run validation on the user-defined module. If these names don't match, the operator can't run validation on the user-defined module and preventable errors may occur. + 1. Save the changes to apply. ### Reapply roles and role bindings @@ -217,12 +220,20 @@ kubectl rollout status sts After the cluster is upgraded, you can upgrade your databases. +### Upgrade REDB + To upgrade your REDB, specify your new database version in the `spec.redisVersion` field in the REDB or REAADB custom resources. Supported database versions for operator versions include "7.2", "7.4", "8.0", and "8.2" (note this value is a string). +### Upgrade REAADB + For Active-Active databases, the `redis.Version` change only needs to be applied on one participating cluster and will automatically propagate to all other participating clusters. All participating clusters must be running operator version 8.0.2-2 or later. If your REAADB uses supported modules, keep the existing `moduleList` version numbers unchanged when upgrading `redisVersion`. The database will automatically use the module versions that are bundled with the new Redis version, regardless of what versions are specified in `moduleList`. After the upgrade is complete, you can optionally change the old version numbers from `moduleList`, but this change has no functional impact. +### Upgrade with user-defined modules + +If a user-defined module is used by any database in the cluster, the module must be defined in the REC custom resource before upgrading the database. + ### Upgrade policy Note that if your cluster [`redisUpgradePolicy`]({{}}) or your database [`redisVersion`]({{< relref "/operate/kubernetes/reference/api/redis_enterprise_database_api#redisversion" >}}) are set to `major`, you won't be able to upgrade those databases to minor versions. See [Redis upgrade policy]({{< relref "/operate/rs/installing-upgrading/upgrading#redis-upgrade-policy" >}}) for more details. From e099c8ed0249cc0baa4f59010b419c2543bb228f Mon Sep 17 00:00:00 2001 From: Kaitlyn Michael Date: Tue, 9 Dec 2025 12:22:50 -0600 Subject: [PATCH 03/16] upgrade changes --- .../kubernetes/upgrade/openshift-cli.md | 30 +++++++++++++++++-- .../upgrade/upgrade-redis-cluster.md | 2 ++ 2 files changed, 30 insertions(+), 2 deletions(-) diff --git a/content/operate/kubernetes/upgrade/openshift-cli.md b/content/operate/kubernetes/upgrade/openshift-cli.md index aa895a6039..1d7ebfd135 100644 --- a/content/operate/kubernetes/upgrade/openshift-cli.md +++ b/content/operate/kubernetes/upgrade/openshift-cli.md @@ -35,6 +35,14 @@ Your Redis Enterprise clusters must be running version 7.4.2-2 or later before u Your Redis databases must be running version 7.2 or later before upgrading your cluster version. See [upgrade databases](#upgrade-databases) for detailed steps. You can find your database version in the [REDB `spec.redisVersion` field]({{}}). +#### User-defined modules + +If your databases use user-defined modules (custom non-bundled modules): + +- Set `autoUpgradeRedisEnterprise: false` in the REC custom resource before upgrading the operator. +- Define the user-defined modules in the REC custom resource before upgrading the database. +See [user-defined modules](#user-defined-modules) for more details. + #### RHEL9-compatible modules Upgrading to Redis operator versions 7.8.2-6 and later involves migrating your Redis Enterprise nodes to RHEL9 from either Ubuntu 18 or RHEL8. If your databases use modules, you need to manually install modules compatible with RHEL9. @@ -81,6 +89,8 @@ For detailed Helm upgrade instructions, see [Upgrade the chart]({{}}If your databases use user-defined modules, set `autoUpgradeRedisEnterprise: false` in the REC custom resource before upgrading the operator.{{}} + ### Download the bundle Make sure you pull the correct version of the bundle. You can find the version tags @@ -188,6 +198,20 @@ After the operator upgrade is complete, you can upgrade Redis Enterprise cluster versionTag: ``` +1. Define any user-defined modules used by databases in the cluster. + + ```YAML + spec: + userDefinedModules: + - name: "custom-module" + source: + https: + url: "https://modules.company.com/search-v2.1.zip" + credentialsSecret: "module-repo-creds" + ``` + + The `name` field match the `display_name` or `module_name` that appears in the module manifest. This enables the operator to run validation on the user-defined module. If these names don't match, the operator can't run validation on the user-defined module and preventable errors may occur. + 1. Save the changes to apply. ### Reapply roles and role bindings @@ -224,6 +248,10 @@ For Active-Active databases, the `redis.Version` change only needs to be applied If your REAADB uses supported modules, keep the existing `moduleList` version numbers unchanged when upgrading `redisVersion`. The database will automatically use the module versions that are bundled with the new Redis version, regardless of what versions are specified in `moduleList`. After the upgrade is complete, you can optionally change the old version numbers from `moduleList`, but this change has no functional impact. +#### Upgrade with user-defined modules + +If a user-defined module is used by any database in the cluster, the module must be defined in the REC custom resource before upgrading the database. + #### General upgrade notes Note that if your cluster [`redisUpgradePolicy`]({{}}) or your database [`redisVersion`]({{< relref "/operate/kubernetes/reference/api/redis_enterprise_database_api#redisversion" >}}) are set to `major`, you won't be able to upgrade those databases to minor versions. See [Redis upgrade policy]({{< relref "/operate/rs/installing-upgrading/upgrading#redis-upgrade-policy" >}}) for more details. @@ -251,5 +279,3 @@ curl -sfk -u : -X POST -H "Content-Type: application ``` After updating the database with the Redis Software API, update the REDB custom resource to reflect the change. - - diff --git a/content/operate/kubernetes/upgrade/upgrade-redis-cluster.md b/content/operate/kubernetes/upgrade/upgrade-redis-cluster.md index 907bb43e73..e1d450cafe 100644 --- a/content/operate/kubernetes/upgrade/upgrade-redis-cluster.md +++ b/content/operate/kubernetes/upgrade/upgrade-redis-cluster.md @@ -76,6 +76,8 @@ For detailed Helm upgrade instructions, see [Upgrade the chart]({{}}If your databases use user-defined modules, set `autoUpgradeRedisEnterprise: false` in the REC custom resource before upgrading the operator.{{}} + ### Download the bundle Make sure you pull the correct version of the bundle. You can find the version tags From eee37f1c63b93859f53374dcaa46c3459e3725dc Mon Sep 17 00:00:00 2001 From: Kaitlyn Michael Date: Tue, 9 Dec 2025 12:32:06 -0600 Subject: [PATCH 04/16] upgrade notes --- .../kubernetes/upgrade/openshift-cli.md | 2 +- .../operate/kubernetes/upgrade/upgrade-olm.md | 34 +++++++++++-------- .../upgrade/upgrade-redis-cluster.md | 2 +- 3 files changed, 21 insertions(+), 17 deletions(-) diff --git a/content/operate/kubernetes/upgrade/openshift-cli.md b/content/operate/kubernetes/upgrade/openshift-cli.md index 1d7ebfd135..aaab467511 100644 --- a/content/operate/kubernetes/upgrade/openshift-cli.md +++ b/content/operate/kubernetes/upgrade/openshift-cli.md @@ -210,7 +210,7 @@ After the operator upgrade is complete, you can upgrade Redis Enterprise cluster credentialsSecret: "module-repo-creds" ``` - The `name` field match the `display_name` or `module_name` that appears in the module manifest. This enables the operator to run validation on the user-defined module. If these names don't match, the operator can't run validation on the user-defined module and preventable errors may occur. + The `name` field match the `display_name` or `module_name` that appears in the module manifest (for example, "redisgears"). This enables the operator to run validation on the user-defined module. If these names don't match, the operator can't run validation on the user-defined module and preventable errors may occur. 1. Save the changes to apply. diff --git a/content/operate/kubernetes/upgrade/upgrade-olm.md b/content/operate/kubernetes/upgrade/upgrade-olm.md index d595170e76..d3fc9f93ca 100644 --- a/content/operate/kubernetes/upgrade/upgrade-olm.md +++ b/content/operate/kubernetes/upgrade/upgrade-olm.md @@ -35,23 +35,13 @@ Your Redis Enterprise clusters must be running version 7.4.2-2 or later before u Your Redis databases must be running version 7.2 or later before upgrading your cluster version. See [upgrade databases](#upgrade-databases) for detailed steps. You can find your database version in the [REDB `spec.redisVersion` field]({{}}). -#### RHEL9-compatible modules +### User-defined modules -Upgrading to Redis operator version 7.8.2-6 or later involves migrating your Redis Enterprise nodes to RHEL9 from either Ubuntu 18 or RHEL8. If your databases use modules, you need to manually install modules compatible with RHEL9. +If your databases use user-defined modules (custom non-bundled modules): -To see which modules you have installed, run: - -```sh -curl -k -u : -X GET https://localhost:9443/v1/modules | jq -r 'map([.module_name, .semantic_version, (.platforms | keys)]) | .[] | .[0] as $name | .[1] as $version | .[2][] | $name + "-" + $version + "-" + .' | sort -``` - -To see which modules are currently in use, run: - -```sh -curl -k -u : -X GET https://localhost:9443/v1/bdbs | jq -r '.[].module_list | map(.module_name + "-" + .semantic_version) | .[]' -``` - -See [Upgrade modules]({{}}) for details on how to upgrade modules with the `rladmin` tool. +- Set `autoUpgradeRedisEnterprise: false` in the REC custom resource before upgrading the operator. +- Define the user-defined modules in the REC custom resource before upgrading the database. +See [user-defined modules](#user-defined-modules) for more details. ### Valid license @@ -111,6 +101,20 @@ After the operator upgrade is complete, you can upgrade Redis Enterprise cluster versionTag: ``` +1. Define any user-defined modules used by databases in the cluster. + + ```YAML + spec: + userDefinedModules: + - name: "custom-module" + source: + https: + url: "https://modules.company.com/search-v2.1.zip" + credentialsSecret: "module-repo-creds" + ``` + + The `name` field match the `display_name` or `module_name` that appears in the module manifest (for example, "redisgears"). This enables the operator to run validation on the user-defined module. If these names don't match, the operator can't run validation on the user-defined module and preventable errors may occur. + 1. Save the changes to apply. ### Reapply roles and role bindings diff --git a/content/operate/kubernetes/upgrade/upgrade-redis-cluster.md b/content/operate/kubernetes/upgrade/upgrade-redis-cluster.md index e1d450cafe..784797f40b 100644 --- a/content/operate/kubernetes/upgrade/upgrade-redis-cluster.md +++ b/content/operate/kubernetes/upgrade/upgrade-redis-cluster.md @@ -190,7 +190,7 @@ For Active-Active databases, we recommend upgrading all participating clusters t credentialsSecret: "module-repo-creds" ``` - The `name` field match the `display_name` or `module_name` that appears in the module manifest. This enables the operator to run validation on the user-defined module. If these names don't match, the operator can't run validation on the user-defined module and preventable errors may occur. + The `name` field match the `display_name` or `module_name` that appears in the module manifest (for example, "redisgears"). This enables the operator to run validation on the user-defined module. If these names don't match, the operator can't run validation on the user-defined module and preventable errors may occur. 1. Save the changes to apply. From 1f216cc1ca581e93172cb3950b5437f47d7cf23f Mon Sep 17 00:00:00 2001 From: Kaitlyn Michael <76962844+kaitlynmichael@users.noreply.github.com> Date: Wed, 10 Dec 2025 07:56:00 -0600 Subject: [PATCH 05/16] Update content/operate/kubernetes/upgrade/openshift-cli.md Co-authored-by: David Dougherty --- content/operate/kubernetes/upgrade/openshift-cli.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/content/operate/kubernetes/upgrade/openshift-cli.md b/content/operate/kubernetes/upgrade/openshift-cli.md index aaab467511..6635bf2df1 100644 --- a/content/operate/kubernetes/upgrade/openshift-cli.md +++ b/content/operate/kubernetes/upgrade/openshift-cli.md @@ -210,7 +210,7 @@ After the operator upgrade is complete, you can upgrade Redis Enterprise cluster credentialsSecret: "module-repo-creds" ``` - The `name` field match the `display_name` or `module_name` that appears in the module manifest (for example, "redisgears"). This enables the operator to run validation on the user-defined module. If these names don't match, the operator can't run validation on the user-defined module and preventable errors may occur. + The `name` field must match the `display_name` or `module_name` that appears in the module manifest (for example, "redisgears"). This enables the operator to run validation on the user-defined module. If these names don't match, the operator can't run validation on the user-defined module and preventable errors may occur. 1. Save the changes to apply. From 9f930731a9349a5325bd192af5288f30c3f30612 Mon Sep 17 00:00:00 2001 From: Kaitlyn Michael <76962844+kaitlynmichael@users.noreply.github.com> Date: Wed, 10 Dec 2025 07:56:10 -0600 Subject: [PATCH 06/16] Update content/operate/kubernetes/upgrade/upgrade-olm.md Co-authored-by: David Dougherty --- content/operate/kubernetes/upgrade/upgrade-olm.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/content/operate/kubernetes/upgrade/upgrade-olm.md b/content/operate/kubernetes/upgrade/upgrade-olm.md index d3fc9f93ca..ca45459779 100644 --- a/content/operate/kubernetes/upgrade/upgrade-olm.md +++ b/content/operate/kubernetes/upgrade/upgrade-olm.md @@ -113,7 +113,7 @@ After the operator upgrade is complete, you can upgrade Redis Enterprise cluster credentialsSecret: "module-repo-creds" ``` - The `name` field match the `display_name` or `module_name` that appears in the module manifest (for example, "redisgears"). This enables the operator to run validation on the user-defined module. If these names don't match, the operator can't run validation on the user-defined module and preventable errors may occur. + The `name` field must match the `display_name` or `module_name` that appears in the module manifest (for example, "redisgears"). This enables the operator to run validation on the user-defined module. If these names don't match, the operator can't run validation on the user-defined module and preventable errors may occur. 1. Save the changes to apply. From 71bbdb55e68de0bd4aa13d066b1cec0a57b15c81 Mon Sep 17 00:00:00 2001 From: Kaitlyn Michael Date: Wed, 10 Dec 2025 08:58:35 -0600 Subject: [PATCH 07/16] fix links --- content/operate/kubernetes/upgrade/openshift-cli.md | 2 +- content/operate/kubernetes/upgrade/upgrade-olm.md | 2 +- content/operate/kubernetes/upgrade/upgrade-redis-cluster.md | 2 +- 3 files changed, 3 insertions(+), 3 deletions(-) diff --git a/content/operate/kubernetes/upgrade/openshift-cli.md b/content/operate/kubernetes/upgrade/openshift-cli.md index 6635bf2df1..99dd28102c 100644 --- a/content/operate/kubernetes/upgrade/openshift-cli.md +++ b/content/operate/kubernetes/upgrade/openshift-cli.md @@ -41,7 +41,7 @@ If your databases use user-defined modules (custom non-bundled modules): - Set `autoUpgradeRedisEnterprise: false` in the REC custom resource before upgrading the operator. - Define the user-defined modules in the REC custom resource before upgrading the database. -See [user-defined modules](#user-defined-modules) for more details. +- See [Edit `redisEnterpriseImageSpec`](#edit-redisenterpriseimagespec) for more details. #### RHEL9-compatible modules diff --git a/content/operate/kubernetes/upgrade/upgrade-olm.md b/content/operate/kubernetes/upgrade/upgrade-olm.md index ca45459779..82c0875ef5 100644 --- a/content/operate/kubernetes/upgrade/upgrade-olm.md +++ b/content/operate/kubernetes/upgrade/upgrade-olm.md @@ -41,7 +41,7 @@ If your databases use user-defined modules (custom non-bundled modules): - Set `autoUpgradeRedisEnterprise: false` in the REC custom resource before upgrading the operator. - Define the user-defined modules in the REC custom resource before upgrading the database. -See [user-defined modules](#user-defined-modules) for more details. +- See [Edit `redisEnterpriseImageSpec`](#edit-redisenterpriseimagespec) for more details. ### Valid license diff --git a/content/operate/kubernetes/upgrade/upgrade-redis-cluster.md b/content/operate/kubernetes/upgrade/upgrade-redis-cluster.md index 784797f40b..76c90c53ac 100644 --- a/content/operate/kubernetes/upgrade/upgrade-redis-cluster.md +++ b/content/operate/kubernetes/upgrade/upgrade-redis-cluster.md @@ -41,7 +41,7 @@ If your databases use user-defined modules (custom non-bundled modules): - Set `autoUpgradeRedisEnterprise: false` in the REC custom resource before upgrading the operator. - Define the user-defined modules in the REC custom resource before upgrading the database. -See [user-defined modules](#user-defined-modules) for more details. +- See [Edit `redisEnterpriseImageSpec`](#edit-redisenterpriseimagespec-in-the-rec-spec) for more details. ### Valid license From a1b0500be68bc74ca2311cfa1f88547879ef76f3 Mon Sep 17 00:00:00 2001 From: Kaitlyn Michael Date: Tue, 16 Dec 2025 10:25:56 -0600 Subject: [PATCH 08/16] install and modules page updates --- .../kubernetes/deployment/quick-start.md | 6 + .../kubernetes/re-databases/modules.md | 201 +++++++++++++----- 2 files changed, 157 insertions(+), 50 deletions(-) diff --git a/content/operate/kubernetes/deployment/quick-start.md b/content/operate/kubernetes/deployment/quick-start.md index 74d7fe557a..d2a21c0c3b 100644 --- a/content/operate/kubernetes/deployment/quick-start.md +++ b/content/operate/kubernetes/deployment/quick-start.md @@ -263,6 +263,12 @@ The operator bundle includes a webhook file. The webhook will intercept requests Error from server: error when creating "STDIN": admission webhook "redisenterprise.admission.redislabs" denied the request: eviction_policy: u'illegal' is not one of [u'volatile-lru', u'volatile-ttl', u'volatile-random', u'allkeys-lru', u'allkeys-random', u'noeviction', u'volatile-lfu', u'allkeys-lfu'] ``` +## Add user-defined modules (optional) + +If you plan to create databases that use user-defined modules (custom non-bundled modules), you must add them to the REC custom resource before creating the databases. + +See [User-defined modules]({{< relref "/operate/kubernetes/re-databases/modules#user-defined-modules" >}}) for detailed instructions on adding and configuring custom modules. + ## Create a Redis Enterprise Database (REDB) You can create multiple databases within the same namespace as your REC or in other namespaces. diff --git a/content/operate/kubernetes/re-databases/modules.md b/content/operate/kubernetes/re-databases/modules.md index 2e47ac19ac..4b382880dc 100644 --- a/content/operate/kubernetes/re-databases/modules.md +++ b/content/operate/kubernetes/re-databases/modules.md @@ -10,93 +10,194 @@ linkTitle: Configure modules weight: 15 --- -Redis Enterprise modules extend Redis functionality with additional data types, commands, and capabilities. The Redis Enterprise operator supports deploying databases with modules through the `RedisEnterpriseDatabase` (REDB) and `RedisEnterpriseActiveActiveDatabase` (REAADB) custom resources. +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 that you have: +Before you begin, verify the following: - [Redis Enterprise operator deployed]({{< relref "/operate/kubernetes/deployment/quick-start" >}}) in your Kubernetes cluster -- [Redis Enterprise Cluster (REC)]({{< relref "/operate/kubernetes/re-clusters" >}}) running and in a healthy state -- Modules uploaded to the Redis Enterprise cluster (see [Check available modules](#check-available-modules)) +- [Redis Enterprise cluster (REC)]({{< relref "/operate/kubernetes/re-clusters" >}}) running and in a healthy state -## Available modules +## Bundled modules -Redis Enterprise includes several built-in 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. -| Module | Name | Description | -|--------|------|-------------| -| **[RediSearch]({{< relref "/develop/ai/search-and-query/" >}})** | `search` | Full-text search and secondary indexing | -| **[RedisJSON]({{< relref "/develop/data-types/json" >}})** | `ReJSON` | JSON data type support | -| **[RedisTimeSeries]({{< relref "/develop/data-types/timeseries" >}})** | `timeseries` | Time series data structures | -| **[RedisBloom]({{< relref "/develop/data-types/probabilistic" >}})** | `bf` | Probabilistic data structures (Bloom filters, etc.) | +### Available bundled modules -### Check available modules +| 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 | -Before configuring databases with modules, check which modules are available in your cluster: +{{< note >}} +When configuring databases with modules, use the `NAME` field (for example, `search` or `ReJSON`) instead of the `DISPLAY_NAME` field. +{{< /note >}} + +### 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: ```bash kubectl get rec -o jsonpath='{.status.modules}' | jq ``` -This command shows the modules installed in the cluster along with their available versions. +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: + +| 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 + +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. + +### 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. + +{{< 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 >}} + +1. Edit your REC custom resource: + + ```sh + kubectl edit rec + ``` + +2. Add the `userDefinedModules` section to the `spec`: + + ```yaml + 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: + + ```sh + kubectl create secret generic module-repo-creds \ + --from-literal=username= \ + --from-literal=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: + +```json +{ + "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 >}} -Use the `NAME` field instead of the `DISPLAY_NAME` field when configuring databases with modules. +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 >}} -## Install additional modules +### Edit user-defined modules + +To modify the user-defined modules list, complete the following steps: -If you need to install additional modules or specific versions, upload them using the Redis Enterprise API. See [Upload module v2]({{< relref "/operate/rs/references/rest-api/requests/modules/#post-module-v2" >}}) for more information. +1. Edit the REC custom resource: -## Module configuration + ```sh + kubectl edit rec + ``` -Each module in the [`modulesList`]({{< relref "/operate/kubernetes/reference/api/redis_enterprise_database_api#specmoduleslist" >}}) supports the following fields: +1. 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. -- **name** (required): The module name (for example, "search", "ReJSON") -- **version** (optional): Specific module version. For Active-Active databases, if specified for one participating cluster, it must be specified for all participating clusters. If omitted, modules will auto-update. -- **config** (optional): Module-specific configuration parameters +1. Save your changes. The operator validates and applies the updates. -For detailed module configuration options and parameters, see [Redis modules]({{< relref "/develop/reference/modules" >}}). +{{< 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 >}} -## Upgrade considerations +### Verify user-defined modules -When upgrading Redis Enterprise clusters or the operator with modules, follow these guidelines: +After you add user-defined modules to the REC, verify that they're available: -#### Pre-upgrade planning +```sh +kubectl get rec -o jsonpath='{.spec.userDefinedModules}' | jq +``` -- **Check module compatibility**: Verify that your current module versions are compatible with the target Redis Enterprise version. Check each module's [`min_redis_version`](https://redis.io/docs/latest/operate/rs/references/rest-api/objects/module/) requirement. -- **Review module dependencies**: Some modules may have specific version requirements or dependencies -- **Document current configurations**: Record all module versions and configurations before upgrading -- **Test in non-production**: Always test module upgrades in a development or staging environment first +You can also check the REC status for validation errors: + +```sh +kubectl describe rec +``` -#### Module version management during upgrades +Look for events or status messages related to module validation in the output. -- **Upload required modules**: Ensure all necessary module versions are uploaded to the cluster before upgrading -- **Version consistency**: For Active-Active databases, ensure module versions are consistent across all participating clusters. If you specify a version for one cluster, specify the same version for all clusters. Omit versions to allow auto-updates. -- **Compatibility requirements**: Consult the Redis Enterprise documentation for module compatibility matrices and verify each module's [`min_redis_version`](https://redis.io/docs/latest/operate/rs/references/rest-api/objects/module/) requirement +## Upgrade with modules -#### Upgrade sequence +The upgrade process differs depending on whether you use bundled modules or user-defined modules. -1. **Upload new module versions** (if required) to the cluster before upgrading Redis Enterprise -2. **Upgrade the Redis Enterprise cluster** following standard upgrade procedures -3. **Verify module functionality** after the cluster upgrade completes -4. **Update database configurations** if new module versions require configuration changes +### Upgrade with bundled modules -#### Post-upgrade verification +For databases using bundled modules (RediSearch, RedisJSON, RedisTimeSeries, RedisBloom): -- **Check module status**: Verify all modules are loaded correctly: `kubectl get rec -o jsonpath='{.status.modules}'` -- **Test module functionality**: Validate that module-specific commands and features work as expected -- **Monitor performance**: Watch for any performance changes after the upgrade -- **Update documentation**: Record the new module versions and any configuration changes +- **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. -For detailed upgrade procedures, see [Upgrade Redis Enterprise clusters]({{< relref "/operate/kubernetes/upgrade/upgrade-redis-cluster" >}}). +- **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. + +### 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. + +1. Add or update the `userDefinedModules` list in the REC spec with the new module versions before or during the cluster upgrade. + +1. 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)]({{< relref "/operate/kubernetes/upgrade/upgrade-redis-cluster" >}}) +- [Upgrade Redis Enterprise on OpenShift]({{< relref "/operate/kubernetes/upgrade/openshift-cli" >}}) ## Related information -- [Database controller]({{< relref "/operate/kubernetes/re-databases/db-controller" >}}) - Learn how to create and manage Redis Enterprise databases -- [Active-Active databases]({{< relref "/operate/kubernetes/active-active" >}}) - Set up globally distributed Active-Active databases -- [Database connectivity]({{< relref "/operate/kubernetes/networking/database-connectivity" >}}) - Connect applications to your Redis Enterprise databases +- [Redis modules documentation]({{< relref "/develop/reference/modules" >}}) - Official Redis modules documentation - [REDB API reference]({{< relref "/operate/kubernetes/reference/api/redis_enterprise_database_api" >}}) - Complete API specification for REDB resources - [REAADB API reference]({{< relref "/operate/kubernetes/reference/api/redis_enterprise_active_active_database_api" >}}) - API reference for Active-Active databases -- [Redis modules documentation](https://redis.io/docs/latest/develop/reference/modules/) - Official Redis modules documentation + +### Redis Software documentation + +- [Add modules to a cluster]({{< relref "/operate/oss_and_stack/stack-with-enterprise/install/add-module-to-cluster" >}}) - Install module packages on Redis Enterprise Software clusters +- [Enable modules for a database]({{< relref "/operate/oss_and_stack/stack-with-enterprise/install/add-module-to-database" >}}) - Add modules to databases in Redis Enterprise Software +- [Upgrade modules]({{< relref "/operate/oss_and_stack/stack-with-enterprise/install/upgrade-module" >}}) - Upgrade module versions in Redis Enterprise Software +- [Module lifecycle]({{< relref "/operate/oss_and_stack/stack-with-enterprise/modules-lifecycle" >}}) - Module versioning and end-of-life schedule + From 9274c973a868da3626a17731be257db77cd9499d Mon Sep 17 00:00:00 2001 From: Kaitlyn Michael Date: Tue, 16 Dec 2025 10:32:36 -0600 Subject: [PATCH 09/16] rolling pod restart note --- content/operate/kubernetes/re-databases/modules.md | 5 ++++- content/operate/kubernetes/upgrade/openshift-cli.md | 4 ++++ content/operate/kubernetes/upgrade/upgrade-olm.md | 4 ++++ content/operate/kubernetes/upgrade/upgrade-redis-cluster.md | 4 ++++ 4 files changed, 16 insertions(+), 1 deletion(-) diff --git a/content/operate/kubernetes/re-databases/modules.md b/content/operate/kubernetes/re-databases/modules.md index 4b382880dc..c91541390a 100644 --- a/content/operate/kubernetes/re-databases/modules.md +++ b/content/operate/kubernetes/re-databases/modules.md @@ -145,6 +145,10 @@ To modify the user-defined modules list, complete the following steps: 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 >}} + ### Verify user-defined modules After you add user-defined modules to the REC, verify that they're available: @@ -200,4 +204,3 @@ For detailed upgrade instructions, see the following: - [Enable modules for a database]({{< relref "/operate/oss_and_stack/stack-with-enterprise/install/add-module-to-database" >}}) - Add modules to databases in Redis Enterprise Software - [Upgrade modules]({{< relref "/operate/oss_and_stack/stack-with-enterprise/install/upgrade-module" >}}) - Upgrade module versions in Redis Enterprise Software - [Module lifecycle]({{< relref "/operate/oss_and_stack/stack-with-enterprise/modules-lifecycle" >}}) - Module versioning and end-of-life schedule - diff --git a/content/operate/kubernetes/upgrade/openshift-cli.md b/content/operate/kubernetes/upgrade/openshift-cli.md index 99dd28102c..e875bc7f29 100644 --- a/content/operate/kubernetes/upgrade/openshift-cli.md +++ b/content/operate/kubernetes/upgrade/openshift-cli.md @@ -212,6 +212,10 @@ After the operator upgrade is complete, you can upgrade Redis Enterprise cluster The `name` field must match the `display_name` or `module_name` that appears in the module manifest (for example, "redisgears"). This enables the operator to run validation on the user-defined module. If these names don't match, the operator can't run validation on the user-defined module and preventable errors may occur. + {{< note >}} +Adding or modifying the `userDefinedModules` list triggers a rolling restart of the Redis Enterprise cluster pods in addition to the rolling upgrade for the version change. + {{< /note >}} + 1. Save the changes to apply. ### Reapply roles and role bindings diff --git a/content/operate/kubernetes/upgrade/upgrade-olm.md b/content/operate/kubernetes/upgrade/upgrade-olm.md index 82c0875ef5..8da7a770f4 100644 --- a/content/operate/kubernetes/upgrade/upgrade-olm.md +++ b/content/operate/kubernetes/upgrade/upgrade-olm.md @@ -115,6 +115,10 @@ After the operator upgrade is complete, you can upgrade Redis Enterprise cluster The `name` field must match the `display_name` or `module_name` that appears in the module manifest (for example, "redisgears"). This enables the operator to run validation on the user-defined module. If these names don't match, the operator can't run validation on the user-defined module and preventable errors may occur. + {{< note >}} +Adding or modifying the `userDefinedModules` list triggers a rolling restart of the Redis Enterprise cluster pods in addition to the rolling upgrade for the version change. + {{< /note >}} + 1. Save the changes to apply. ### Reapply roles and role bindings diff --git a/content/operate/kubernetes/upgrade/upgrade-redis-cluster.md b/content/operate/kubernetes/upgrade/upgrade-redis-cluster.md index 76c90c53ac..5fd93f7c90 100644 --- a/content/operate/kubernetes/upgrade/upgrade-redis-cluster.md +++ b/content/operate/kubernetes/upgrade/upgrade-redis-cluster.md @@ -192,6 +192,10 @@ For Active-Active databases, we recommend upgrading all participating clusters t The `name` field match the `display_name` or `module_name` that appears in the module manifest (for example, "redisgears"). This enables the operator to run validation on the user-defined module. If these names don't match, the operator can't run validation on the user-defined module and preventable errors may occur. + {{< note >}} +Adding or modifying the `userDefinedModules` list triggers a rolling restart of the Redis Enterprise cluster pods in addition to the rolling upgrade for the version change. + {{< /note >}} + 1. Save the changes to apply. ### Reapply roles and role bindings From f0b97bb9b52020caeff02690506042867c3baad2 Mon Sep 17 00:00:00 2001 From: Kaitlyn Michael Date: Tue, 16 Dec 2025 10:34:41 -0600 Subject: [PATCH 10/16] helm upgrade note --- content/operate/kubernetes/deployment/helm.md | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/content/operate/kubernetes/deployment/helm.md b/content/operate/kubernetes/deployment/helm.md index a1411d6bc2..0ce8d30aca 100644 --- a/content/operate/kubernetes/deployment/helm.md +++ b/content/operate/kubernetes/deployment/helm.md @@ -149,6 +149,10 @@ The upgrade process automatically updates the operator and its components, inclu After you upgrade the operator, you might need to upgrade your Redis Enterprise clusters, depending on the Redis software version bundled with the operator. For detailed information about the upgrade process, see [Redis Enterprise for Kubernetes upgrade documentation](https://redis.io/docs/latest/operate/kubernetes/upgrade/). +{{< note >}} +If your databases use user-defined modules (custom non-bundled modules), you must take additional steps during the upgrade process. See [Upgrade with user-defined modules]({{< relref "/operate/kubernetes/upgrade/upgrade-redis-cluster#user-defined-modules" >}}) for details. +{{< /note >}} + For more information and options when upgrading charts, see [helm upgrade](https://helm.sh/docs/helm/helm_upgrade/). ## Uninstall From 29e6afaa3516f9b23d56b74e5ef1f31f033df094 Mon Sep 17 00:00:00 2001 From: Kaitlyn Michael Date: Tue, 16 Dec 2025 10:38:31 -0600 Subject: [PATCH 11/16] cluster recovery --- content/operate/kubernetes/re-clusters/cluster-recovery.md | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/content/operate/kubernetes/re-clusters/cluster-recovery.md b/content/operate/kubernetes/re-clusters/cluster-recovery.md index baadfc25a4..de221fc32e 100644 --- a/content/operate/kubernetes/re-clusters/cluster-recovery.md +++ b/content/operate/kubernetes/re-clusters/cluster-recovery.md @@ -24,6 +24,10 @@ The Redis Enterprise for Kubernetes automates these recovery steps: {{}}Redis Enterprise for Kubernetes 7.2.4-2 introduces a new limitation. You cannot recover or upgrade your cluster if there are databases with old module versions or manually uploaded modules. See the [Redis Enterprise Software 7.2.4 known limitations]({{< relref "/operate/rs/release-notes/rs-7-2-4-releases/rs-7-2-4-52#cluster-recovery-with-manually-uploaded-modules" >}}) for more details.{{}} +{{< note >}} +If your cluster uses user-defined modules, the recovery process doesn't block on module validation errors (such as URL or credential issues). The cluster can recover successfully, and you can resolve any module configuration issues after recovery is complete. See [User-defined modules]({{< relref "/operate/kubernetes/re-databases/modules#user-defined-modules" >}}) for more information. +{{< /note >}} + ## Prerequisites - For cluster recovery, the cluster must be [deployed with persistence]({{< relref "/operate/kubernetes/recommendations/persistent-volumes" >}}). From 798a289958dea873dd12e4ff7838eae8cf5f7327 Mon Sep 17 00:00:00 2001 From: Kaitlyn Michael Date: Tue, 16 Dec 2025 10:42:11 -0600 Subject: [PATCH 12/16] upgrade troubleshooting --- .../upgrade/upgrade-redis-cluster.md | 24 +++++++++++++++++++ 1 file changed, 24 insertions(+) diff --git a/content/operate/kubernetes/upgrade/upgrade-redis-cluster.md b/content/operate/kubernetes/upgrade/upgrade-redis-cluster.md index 5fd93f7c90..ee29d86797 100644 --- a/content/operate/kubernetes/upgrade/upgrade-redis-cluster.md +++ b/content/operate/kubernetes/upgrade/upgrade-redis-cluster.md @@ -248,6 +248,30 @@ Note that if your cluster [`redisUpgradePolicy`]({{ -o jsonpath='{.spec.autoUpgradeRedisEnterprise}' + ``` + +1. **Verify modules are defined in the REC**: Ensure all user-defined modules are listed in the REC `userDefinedModules` section before upgrading. + + ```sh + kubectl get rec -o jsonpath='{.spec.userDefinedModules}' | jq + ``` + +1. **Check module validation errors**: Review the REC status for module validation errors. + + ```sh + kubectl describe rec + ``` + +For more information about user-defined modules, see [User-defined modules]({{< relref "/operate/kubernetes/re-databases/modules#user-defined-modules" >}}). + ### Invalid module version If the operator logs show an event related to an unsupported module, download the updated module locally, and install it using the `v2/modules` API endpoint. From 2f32d3b9c1ca11c8bd3129f95f9f61c322e80cd7 Mon Sep 17 00:00:00 2001 From: Kaitlyn Michael Date: Tue, 16 Dec 2025 10:47:00 -0600 Subject: [PATCH 13/16] AA and flash limitations --- content/operate/kubernetes/re-databases/modules.md | 10 ++++++++-- 1 file changed, 8 insertions(+), 2 deletions(-) diff --git a/content/operate/kubernetes/re-databases/modules.md b/content/operate/kubernetes/re-databases/modules.md index c91541390a..29b4961654 100644 --- a/content/operate/kubernetes/re-databases/modules.md +++ b/content/operate/kubernetes/re-databases/modules.md @@ -70,7 +70,13 @@ The following table shows the key differences between bundled and user-defined m 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. -### Add user-defined modules to the REC +### 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. @@ -124,7 +130,7 @@ You can use either `"rg"` or `"RedisGears"` as the `name` value in your REC spec 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 >}} -### Edit user-defined modules +## Edit user-defined modules To modify the user-defined modules list, complete the following steps: From d3155b92fe550673ffbe8bc33e773465957471cd Mon Sep 17 00:00:00 2001 From: Kaitlyn Michael Date: Tue, 16 Dec 2025 10:51:07 -0600 Subject: [PATCH 14/16] links --- content/operate/kubernetes/upgrade/openshift-cli.md | 4 +++- content/operate/kubernetes/upgrade/upgrade-olm.md | 2 ++ content/operate/kubernetes/upgrade/upgrade-redis-cluster.md | 4 +++- 3 files changed, 8 insertions(+), 2 deletions(-) diff --git a/content/operate/kubernetes/upgrade/openshift-cli.md b/content/operate/kubernetes/upgrade/openshift-cli.md index e875bc7f29..8474ff8857 100644 --- a/content/operate/kubernetes/upgrade/openshift-cli.md +++ b/content/operate/kubernetes/upgrade/openshift-cli.md @@ -43,6 +43,8 @@ If your databases use user-defined modules (custom non-bundled modules): - Define the user-defined modules in the REC custom resource before upgrading the database. - See [Edit `redisEnterpriseImageSpec`](#edit-redisenterpriseimagespec) for more details. +For more information about user-defined modules, see [User-defined modules]({{< relref "/operate/kubernetes/re-databases/modules#user-defined-modules" >}}). + #### RHEL9-compatible modules Upgrading to Redis operator versions 7.8.2-6 and later involves migrating your Redis Enterprise nodes to RHEL9 from either Ubuntu 18 or RHEL8. If your databases use modules, you need to manually install modules compatible with RHEL9. @@ -254,7 +256,7 @@ If your REAADB uses supported modules, keep the existing `moduleList` version nu #### Upgrade with user-defined modules -If a user-defined module is used by any database in the cluster, the module must be defined in the REC custom resource before upgrading the database. +If a user-defined module is used by any database in the cluster, the module must be defined in the REC custom resource before upgrading the database. See [Add user-defined modules to the REC]({{< relref "/operate/kubernetes/re-databases/modules#add-user-defined-modules-to-the-rec" >}}) for detailed instructions. #### General upgrade notes diff --git a/content/operate/kubernetes/upgrade/upgrade-olm.md b/content/operate/kubernetes/upgrade/upgrade-olm.md index 8da7a770f4..6ad6ac3ec4 100644 --- a/content/operate/kubernetes/upgrade/upgrade-olm.md +++ b/content/operate/kubernetes/upgrade/upgrade-olm.md @@ -43,6 +43,8 @@ If your databases use user-defined modules (custom non-bundled modules): - Define the user-defined modules in the REC custom resource before upgrading the database. - See [Edit `redisEnterpriseImageSpec`](#edit-redisenterpriseimagespec) for more details. +For more information about user-defined modules, see [User-defined modules]({{< relref "/operate/kubernetes/re-databases/modules#user-defined-modules" >}}). + ### Valid license Use `kubectl get rec` and verify the `LICENSE STATE` is valid on your REC before you start the upgrade process. diff --git a/content/operate/kubernetes/upgrade/upgrade-redis-cluster.md b/content/operate/kubernetes/upgrade/upgrade-redis-cluster.md index ee29d86797..b2d7575c4f 100644 --- a/content/operate/kubernetes/upgrade/upgrade-redis-cluster.md +++ b/content/operate/kubernetes/upgrade/upgrade-redis-cluster.md @@ -43,6 +43,8 @@ If your databases use user-defined modules (custom non-bundled modules): - Define the user-defined modules in the REC custom resource before upgrading the database. - See [Edit `redisEnterpriseImageSpec`](#edit-redisenterpriseimagespec-in-the-rec-spec) for more details. +For more information about user-defined modules, see [User-defined modules]({{< relref "/operate/kubernetes/re-databases/modules#user-defined-modules" >}}). + ### Valid license Use `kubectl get rec` and verify the `LICENSE STATE` is valid on your REC before you start the upgrade process. @@ -238,7 +240,7 @@ If your REAADB uses supported modules, keep the existing `moduleList` version nu ### Upgrade with user-defined modules -If a user-defined module is used by any database in the cluster, the module must be defined in the REC custom resource before upgrading the database. +If a user-defined module is used by any database in the cluster, the module must be defined in the REC custom resource before upgrading the database. See [Add user-defined modules to the REC]({{< relref "/operate/kubernetes/re-databases/modules#add-user-defined-modules-to-the-rec" >}}) for detailed instructions. ### Upgrade policy From 4e8014d4fc6c1d2c8208457c76eb45b079b4c102 Mon Sep 17 00:00:00 2001 From: Kaitlyn Michael Date: Tue, 16 Dec 2025 11:11:25 -0600 Subject: [PATCH 15/16] add troubleshooting --- .../kubernetes/re-databases/modules.md | 138 +++++++++++++++++- 1 file changed, 135 insertions(+), 3 deletions(-) diff --git a/content/operate/kubernetes/re-databases/modules.md b/content/operate/kubernetes/re-databases/modules.md index 29b4961654..d412d90842 100644 --- a/content/operate/kubernetes/re-databases/modules.md +++ b/content/operate/kubernetes/re-databases/modules.md @@ -70,13 +70,13 @@ The following table shows the key differences between bundled and user-defined m 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 +**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 +### 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. @@ -130,7 +130,7 @@ You can use either `"rg"` or `"RedisGears"` as the `name` value in your REC spec 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 >}} -## Edit user-defined modules +### Edit user-defined modules To modify the user-defined modules list, complete the following steps: @@ -198,6 +198,138 @@ For detailed upgrade instructions, see the following: - [Upgrade a Redis Enterprise cluster (REC)]({{< relref "/operate/kubernetes/upgrade/upgrade-redis-cluster" >}}) - [Upgrade Redis Enterprise on OpenShift]({{< relref "/operate/kubernetes/upgrade/openshift-cli" >}}) +## 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: + +```sh +kubectl describe rec +``` + +Look for error messages related to modules in the Events section. + +**Resolution:** + +1. **Verify the module URL is accessible:** + + ```sh + curl -I + ``` + +2. **Check credentials secret exists and has correct values:** + + ```sh + kubectl get secret -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 `min_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](#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: + +```sh +kubectl logs -l name=redis-enterprise-operator -n +``` + +Check the REC pod logs: + +```sh +kubectl logs -n +``` + +**Resolution:** + +1. **Remove problematic modules from the REC spec:** + + Edit the REC and remove or comment out the problematic module from the `userDefinedModules` list: + + ```sh + kubectl edit rec + ``` + +2. **Wait for the cluster to recover:** + + ```sh + kubectl get rec -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: + +```sh +kubectl describe redb +``` + +Verify which modules are defined in the REC: + +```sh +kubectl get rec -o jsonpath='{.spec.userDefinedModules}' | jq +``` + +**Resolution:** + +1. **Add the missing module to the REC:** + + See [Add user-defined modules to the REC](#add-user-defined-modules-to-the-rec) for detailed instructions. + +2. **Wait for the module to be validated:** + + ```sh + kubectl describe rec + ``` + + 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]({{< relref "/develop/reference/modules" >}}) - Official Redis modules documentation From 73e17a6339657473ca86ba1a99d9ad6b40416e39 Mon Sep 17 00:00:00 2001 From: Kaitlyn Michael Date: Tue, 16 Dec 2025 11:22:17 -0600 Subject: [PATCH 16/16] copy edits --- content/operate/kubernetes/upgrade/upgrade-redis-cluster.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/content/operate/kubernetes/upgrade/upgrade-redis-cluster.md b/content/operate/kubernetes/upgrade/upgrade-redis-cluster.md index b2d7575c4f..30b2363ec5 100644 --- a/content/operate/kubernetes/upgrade/upgrade-redis-cluster.md +++ b/content/operate/kubernetes/upgrade/upgrade-redis-cluster.md @@ -192,7 +192,7 @@ For Active-Active databases, we recommend upgrading all participating clusters t credentialsSecret: "module-repo-creds" ``` - The `name` field match the `display_name` or `module_name` that appears in the module manifest (for example, "redisgears"). This enables the operator to run validation on the user-defined module. If these names don't match, the operator can't run validation on the user-defined module and preventable errors may occur. + The `name` field must match the `display_name` or `module_name` that appears in the module manifest (for example, "redisgears"). This enables the operator to run validation on the user-defined module. If these names don't match, the operator can't run validation on the user-defined module and preventable errors may occur. {{< note >}} Adding or modifying the `userDefinedModules` list triggers a rolling restart of the Redis Enterprise cluster pods in addition to the rolling upgrade for the version change.