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 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-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" >}}). diff --git a/content/operate/kubernetes/re-databases/modules.md b/content/operate/kubernetes/re-databases/modules.md index 2e47ac19ac..d412d90842 100644 --- a/content/operate/kubernetes/re-databases/modules.md +++ b/content/operate/kubernetes/re-databases/modules.md @@ -10,93 +10,335 @@ 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. + +**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. + +{{< 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 >}} +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 + +To modify the user-defined modules list, complete the following steps: + +1. Edit the REC custom resource: + + ```sh + kubectl edit rec + ``` + +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. + +1. Save your changes. The operator validates and applies the updates. + +{{< warning >}} +Don't remove modules that are currently in use by any database. The operator rejects the change and puts the REC into an error state. +{{< /warning >}} {{< note >}} -Use the `NAME` field instead of the `DISPLAY_NAME` field when configuring databases with modules. +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 >}} -## Install additional modules +### Verify user-defined modules + +After you add user-defined modules to the REC, verify that they're available: + +```sh +kubectl get rec -o jsonpath='{.spec.userDefinedModules}' | jq +``` + +You can also check the REC status for validation errors: + +```sh +kubectl describe rec +``` + +Look for events or status messages related to module validation in the output. + +## Upgrade with modules + +The upgrade process differs depending on whether you use bundled modules or user-defined modules. + +### Upgrade with bundled modules + +For databases using bundled modules (RediSearch, RedisJSON, RedisTimeSeries, RedisBloom): + +- **Redis 8 and later**: Bundled modules are automatically enabled and upgraded when you upgrade the database to Redis version 8 or later. You don't need to take any additional action. -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. +- **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. -## Module configuration +### Upgrade with user-defined modules -Each module in the [`modulesList`]({{< relref "/operate/kubernetes/reference/api/redis_enterprise_database_api#specmoduleslist" >}}) supports the following fields: +For databases using user-defined modules, you must take additional steps during cluster upgrades: -- **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. Set `autoUpgradeRedisEnterprise` to `false` in your REC spec before upgrading. -For detailed module configuration options and parameters, see [Redis modules]({{< relref "/develop/reference/modules" >}}). +1. Add or update the `userDefinedModules` list in the REC spec with the new module versions before or during the cluster upgrade. -## Upgrade considerations +1. After the cluster upgrade completes, you can re-enable `autoUpgradeRedisEnterprise` if desired. -When upgrading Redis Enterprise clusters or the operator with modules, follow these guidelines: +For detailed upgrade instructions, see the following: -#### Pre-upgrade planning +- [Upgrade a Redis Enterprise cluster (REC)]({{< relref "/operate/kubernetes/upgrade/upgrade-redis-cluster" >}}) +- [Upgrade Redis Enterprise on OpenShift]({{< relref "/operate/kubernetes/upgrade/openshift-cli" >}}) -- **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 +## Troubleshooting -#### Module version management during upgrades +This section covers common issues you might encounter when working with user-defined modules. -- **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 +### Module validation errors -#### Upgrade sequence +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. -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 +**Symptoms:** -#### Post-upgrade verification +- REC status shows validation errors +- Events indicate module download or validation failures +- Databases fail to create with module-related errors -- **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 +**Diagnosis:** -For detailed upgrade procedures, see [Upgrade Redis Enterprise clusters]({{< relref "/operate/kubernetes/upgrade/upgrade-redis-cluster" >}}). +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 -- [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 diff --git a/content/operate/kubernetes/upgrade/openshift-cli.md b/content/operate/kubernetes/upgrade/openshift-cli.md index aa895a6039..8474ff8857 100644 --- 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]({{}}). +#### 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]({{}}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 +200,24 @@ 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 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`]({{}}) 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 : -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 index d595170e76..6ad6ac3ec4 100644 --- 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]({{}}). -#### 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 : -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. +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: ``` +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 index abf87c8a4e..30b2363ec5 100644 --- 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]({{}}). -### 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 : -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. +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]({{}}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 @@ -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`. +{{}} +For Active-Active databases, we recommend upgrading all participating clusters to the same operator version. +{{}} ### 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: ``` +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,17 +224,25 @@ 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. +### 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`]({{}}) 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. @@ -232,6 +250,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.