K8s: User-defined modules (Asgard release) (#2524)

kaitlynmichael · dwdougherty · web-flow · commit 6ebdbf54f098 · 2025-12-19T17:06:43.000-06:00
* page improvements

* upgrade prereqs

* upgrade changes

* upgrade notes

* Update content/operate/kubernetes/upgrade/openshift-cli.md

Co-authored-by: David Dougherty &lt;david.dougherty@redis.com&gt;

* Update content/operate/kubernetes/upgrade/upgrade-olm.md

Co-authored-by: David Dougherty &lt;david.dougherty@redis.com&gt;

* fix links

* install and modules page updates

* rolling pod restart note

* helm upgrade note

* cluster recovery

* upgrade troubleshooting

* AA and flash limitations

* links

* add troubleshooting

* copy edits

* review feedback changes

---------

Co-authored-by: David Dougherty &lt;david.dougherty@redis.com&gt;
diff --git 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
diff --git 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-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:
 
 {{<warning>}}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.{{</warning>}}
 
+{{< 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" >}}).
diff --git a/content/operate/kubernetes/re-databases/modules.md b/content/operate/kubernetes/re-databases/modules.md
diff --git a/content/operate/kubernetes/upgrade/openshift-cli.md b/content/operate/kubernetes/upgrade/openshift-cli.md
@@ -35,6 +35,16 @@ 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]({{<relref "/operate/kubernetes/reference/api/redis_enterprise_database_api#redisversion" >}}).
 
+#### 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 [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.
@@ -81,6 +91,8 @@ For detailed Helm upgrade instructions, see [Upgrade the chart]({{<relref "/oper
 
 ## Upgrade the operator
 
+{{<warning>}}If your databases use user-defined modules, set `autoUpgradeRedisEnterprise: false` in the REC custom resource before upgrading the operator.{{</warning>}}
+
 ### Download the bundle
 
 Make sure you pull the correct version of the bundle. You can find the version tags
@@ -188,6 +200,24 @@ After the operator upgrade is complete, you can upgrade Redis Enterprise cluster
         versionTag:       <new-version-tag>
     ```
 
+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 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
@@ -224,6 +254,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. 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
 
 Note that if your cluster [`redisUpgradePolicy`]({{<relref "/operate/kubernetes/reference/api/redis_enterprise_cluster_api#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 +285,3 @@ curl -sfk -u <rec_username>:<rec_password> -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-olm.md b/content/operate/kubernetes/upgrade/upgrade-olm.md
@@ -35,23 +35,15 @@ 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]({{<relref "/operate/kubernetes/reference/api/redis_enterprise_database_api#redisversion" >}}).
 
-#### 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:
+- 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 [Edit `redisEnterpriseImageSpec`](#edit-redisenterpriseimagespec) for more details.
 
-```sh
-curl -k -u <rec_username>:<rec_password> -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 <rec_username>:<rec_password> -X GET https://localhost:9443/v1/bdbs | jq -r '.[].module_list | map(.module_name + "-" + .semantic_version) | .[]'
-```
-
-See [Upgrade modules]({{<relref "/operate/oss_and_stack/stack-with-enterprise/install/upgrade-module">}}) for details on how to upgrade modules with the `rladmin` tool.
+For more information about user-defined modules, see [User-defined modules]({{< relref "/operate/kubernetes/re-databases/modules#user-defined-modules" >}}).
 
 ### Valid license
 
@@ -111,6 +103,24 @@ After the operator upgrade is complete, you can upgrade Redis Enterprise cluster
         versionTag:       <new-version-tag>
     ```
 
+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 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
@@ -35,23 +35,15 @@ Check the [Redis Enterprise for Kubernetes release notes]({{<relref "/operate/ku
 
 Check the release notes for your target version to determine the minimum Redis database version required. See [upgrade databases](#upgrade-databases) for detailed steps. You can find your database version in the [REDB `spec.redisVersion` field]({{<relref "/operate/kubernetes/reference/api/redis_enterprise_database_api#redisversion" >}}).
 
-### 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:
+- 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 [Edit `redisEnterpriseImageSpec`](#edit-redisenterpriseimagespec-in-the-rec-spec) for more details.
 
-```sh
-curl -k -u <rec_username>:<rec_password> -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 <rec_username>:<rec_password> -X GET https://localhost:9443/v1/bdbs | jq -r '.[].module_list | map(.module_name + "-" + .semantic_version) | .[]'
-```
-
-See [Upgrade modules]({{<relref "/operate/oss_and_stack/stack-with-enterprise/install/upgrade-module">}}) for details on how to upgrade modules with the `rladmin` tool.
+For more information about user-defined modules, see [User-defined modules]({{< relref "/operate/kubernetes/re-databases/modules#user-defined-modules" >}}).
 
 ### Valid license
 
@@ -86,6 +78,8 @@ For detailed Helm upgrade instructions, see [Upgrade the chart]({{<relref "/oper
 
 ## Upgrade the operator
 
+{{<warning>}}If your databases use user-defined modules, set `autoUpgradeRedisEnterprise: false` in the REC custom resource before upgrading the operator.{{</warning>}}
+
 ### Download the bundle
 
 Make sure you pull the correct version of the bundle. You can find the version tags
@@ -164,11 +158,9 @@ 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`.
+{{<note>}}
+For Active-Active databases, we recommend upgrading all participating clusters to the same operator version.
+{{</note>}}
 
 ### Edit `redisEnterpriseImageSpec` in the REC spec
 
@@ -188,6 +180,24 @@ If you are upgrading from a preview version of the Active-Active controller, you
         versionTag:       <new-version-tag>
     ```
 
+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 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
@@ -214,24 +224,56 @@ To see the status of the current rolling upgrade, run:
 kubectl rollout status sts <REC_name>
 ```
 
-### Upgrade databases
+## Upgrade databases
 
 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.
 
-#### General upgrade notes
+### 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. 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
 
 Note that if your cluster [`redisUpgradePolicy`]({{<relref "/operate/kubernetes/reference/api/redis_enterprise_cluster_api#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.
 
 ## Troubleshooting
 
 If you start an upgrade without meeting the [prerequisites](#prerequisites), the operator will freeze the upgrade. Check the operator logs for the source of the error. The REDB reconsilliation doesn't work during an upgrade, so you need to apply a manual fix with the Redis Software API (examples below). The updates will also need to be added to the REDB custom resource.
 
+### User-defined modules
+
+If your databases use user-defined modules and you encounter upgrade issues:
+
+1. **Verify `autoUpgradeRedisEnterprise` is set to `false`**: Check the REC spec to ensure automatic upgrades are disabled.
+
+    ```sh
+    kubectl get rec <cluster-name> -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 <cluster-name> -o jsonpath='{.spec.userDefinedModules}' | jq
+    ```
+
+1. **Check module validation errors**: Review the REC status for module validation errors.
+
+    ```sh
+    kubectl describe rec <cluster-name>
+    ```
+
+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.
