From ad500c348617490ed8f69b4d7f5d9c27073b89e2 Mon Sep 17 00:00:00 2001 From: Kaitlyn Michael Date: Tue, 2 Sep 2025 09:30:13 -0500 Subject: [PATCH 1/3] rough draft --- .../kubernetes/re-databases/modules.md | 257 ++++++++++++++++++ 1 file changed, 257 insertions(+) create mode 100644 content/operate/kubernetes/re-databases/modules.md diff --git a/content/operate/kubernetes/re-databases/modules.md b/content/operate/kubernetes/re-databases/modules.md new file mode 100644 index 0000000000..79ff2a62d4 --- /dev/null +++ b/content/operate/kubernetes/re-databases/modules.md @@ -0,0 +1,257 @@ +--- +Title: Redis modules on Kubernetes +alwaysopen: false +categories: +- docs +- operate +- kubernetes +description: Deploy Redis Enterprise databases with modules using the Redis Enterprise operator for Kubernetes. +linkTitle: Redis 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. + +## Prerequisites + +Before you begin, verify that you have: + +- Redis Enterprise operator deployed in your Kubernetes cluster +- Redis Enterprise Cluster (REC) running and in a healthy state +- Modules uploaded to the Redis Enterprise cluster (see [Check available modules](#check-available-modules)) + +## Available modules + +Redis Enterprise includes several built-in modules: + +- **RediSearch** (`search`) - Full-text search and secondary indexing +- **RedisJSON** (`ReJSON`) - JSON data type support +- **RedisTimeSeries** (`timeseries`) - Time series data structures +- **RedisBloom** (`bf`) - Probabilistic data structures (Bloom filters, etc.) +- **RedisGraph** (`graph`) - Graph database capabilities +- **RedisGears** (`rg`) - Programmable data processing engine + +## Check available modules + +Before configuring databases with modules, check which modules are available in your cluster: + +```bash +kubectl get rec -o jsonpath='{.status.modules}' | jq +``` + +This command shows the modules installed in the cluster along with their available versions. + +## Install additional modules + +If you need to install additional modules or specific versions, upload them using the Redis Enterprise API: + +1. Get cluster credentials: + + ```bash + kubectl get secret -o jsonpath='{.data.username}' | base64 -d + kubectl get secret -o jsonpath='{.data.password}' | base64 -d + ``` + +2. Port forward to the cluster API: + + ```bash + kubectl port-forward service/ 9443:9443 + ``` + +3. Upload the module: + + ```bash + curl -k -u : -X POST \ + -F 'module=@' \ + https://localhost:9443/v2/modules + ``` + +## Configure databases with modules + +### Basic database with modules + +The following example shows a `RedisEnterpriseDatabase` with modules: + +```yaml +apiVersion: app.redislabs.com/v1alpha1 +kind: RedisEnterpriseDatabase +metadata: + name: search-db + labels: + app: redis-enterprise +spec: + redisEnterpriseCluster: + name: rec + memorySize: 1GB + shardCount: 1 + replication: false + + # Configure modules + modulesList: + - name: search + config: "MAXSEARCHRESULTS 10000 MAXAGGREGATERESULTS 10000" + - name: ReJSON +``` + +### Database with multiple modules + +The following example shows a database configured with multiple modules: + +```yaml +apiVersion: app.redislabs.com/v1alpha1 +kind: RedisEnterpriseDatabase +metadata: + name: multi-module-db + labels: + app: redis-enterprise +spec: + redisEnterpriseCluster: + name: rec + memorySize: 2GB + shardCount: 2 + replication: true + + modulesList: + - name: search + config: "MAXSEARCHRESULTS 50000" + - name: ReJSON + - name: timeseries + config: "RETENTION_POLICY 86400000" + - name: bf +``` + +### Active-Active database with modules + +For Active-Active databases, you must specify modules with explicit versions: + +```yaml +apiVersion: app.redislabs.com/v1alpha1 +kind: RedisEnterpriseActiveActiveDatabase +metadata: + name: aa-search-db + labels: + app: redis-enterprise +spec: + participatingClusters: + - name: cluster-east + - name: cluster-west + + redisEnterpriseDatabase: + memorySize: 1GB + shardCount: 1 + replication: true + + modulesList: + - name: search + version: "2.8.4" + config: "MAXSEARCHRESULTS 10000" + - name: ReJSON + version: "2.6.6" +``` + +## Module configuration + +### Module parameters + +Each module in the `modulesList` supports the following fields: + +- **name** (required): The module name (for example, "search", "ReJSON") +- **version** (optional for REDB, required for REAADB): Specific module version +- **config** (optional): Module-specific configuration parameters + +### Common module configurations + +#### RediSearch + +```yaml +- name: search + config: "MAXSEARCHRESULTS 10000 MAXAGGREGATERESULTS 5000 TIMEOUT 500" +``` + +#### RedisTimeSeries + +```yaml +- name: timeseries + config: "RETENTION_POLICY 86400000 MAX_SAMPLE_PER_CHUNK 360" +``` + +#### RedisBloom + +```yaml +- name: bf + config: "ERROR_RATE 0.01 INITIAL_SIZE 1000" +``` + +## Best practices + +### Module version management + +- For production environments, specify explicit module versions in Active-Active databases +- Use the cluster's available modules list to ensure compatibility +- Test module upgrades in non-production environments first + +### Resource planning + +- Modules consume additional memory and CPU resources +- Plan cluster resources accordingly when using multiple modules +- Monitor module-specific metrics and performance + +### Configuration management + +- Use module configuration parameters to optimize performance +- Document module configurations for consistency across environments +- Consider module-specific backup and recovery requirements + +### Upgrade considerations + +- Ensure compatible module versions before cluster upgrades +- Upload required module versions before upgrading the cluster +- Review module compatibility matrices in Redis Enterprise documentation + +## Troubleshooting + +### Common issues + +1. **Module not available error:** + - Check if the module is installed: `kubectl get rec -o jsonpath='{.status.modules}'` + - Upload the module if missing using the API endpoint + +2. **Version compatibility issues:** + - Verify module version compatibility with your Redis Enterprise version + - Check the Redis Enterprise documentation for supported module versions + +3. **Configuration errors:** + - Validate module configuration parameters + - Check Redis Enterprise logs for specific error messages + +### Debugging commands + +```bash +# Check cluster status and available modules +kubectl get rec -o yaml + +# Check database status +kubectl get redb -o yaml + +# View operator logs +kubectl logs -l name=redis-enterprise-operator + +# Check cluster logs +kubectl logs +``` + +## Examples + +See the `deploy/examples/` directory for additional configuration examples: + +- Basic database: `deploy/examples/v1alpha1/redb.yaml` +- Active-Active database: `deploy/examples/v1alpha1/reaadb.yaml` + +## 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 +- [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 From 8edc6f7f51b7e70174ec903e3acdac63d4190c50 Mon Sep 17 00:00:00 2001 From: Kaitlyn Michael Date: Tue, 2 Sep 2025 09:42:01 -0500 Subject: [PATCH 2/3] add upgrade considerations --- .../kubernetes/re-databases/modules.md | 164 ++++++------------ 1 file changed, 52 insertions(+), 112 deletions(-) diff --git a/content/operate/kubernetes/re-databases/modules.md b/content/operate/kubernetes/re-databases/modules.md index 79ff2a62d4..84c5a5d0db 100644 --- a/content/operate/kubernetes/re-databases/modules.md +++ b/content/operate/kubernetes/re-databases/modules.md @@ -1,12 +1,12 @@ --- -Title: Redis modules on Kubernetes +Title: Configure modules alwaysopen: false categories: - docs - operate - kubernetes description: Deploy Redis Enterprise databases with modules using the Redis Enterprise operator for Kubernetes. -linkTitle: Redis modules +linkTitle: Configure modules weight: 15 --- @@ -31,7 +31,7 @@ Redis Enterprise includes several built-in modules: - **RedisGraph** (`graph`) - Graph database capabilities - **RedisGears** (`rg`) - Programmable data processing engine -## Check available modules +### Check available modules Before configuring databases with modules, check which modules are available in your cluster: @@ -66,151 +66,98 @@ If you need to install additional modules or specific versions, upload them usin https://localhost:9443/v2/modules ``` -## Configure databases with modules +## Module configuration -### Basic database with modules +#### Module parameters -The following example shows a `RedisEnterpriseDatabase` with modules: +Each module in the [`modulesList`]({{< relref "/operate/kubernetes/reference/api/redis_enterprise_database_api#specmoduleslist" >}}) supports the following fields: -```yaml -apiVersion: app.redislabs.com/v1alpha1 -kind: RedisEnterpriseDatabase -metadata: - name: search-db - labels: - app: redis-enterprise -spec: - redisEnterpriseCluster: - name: rec - memorySize: 1GB - shardCount: 1 - replication: false - - # Configure modules - modulesList: - - name: search - config: "MAXSEARCHRESULTS 10000 MAXAGGREGATERESULTS 10000" - - name: ReJSON -``` +- **name** (required): The module name (for example, "search", "ReJSON") +- **version** (optional for REDB, required for REAADB): Specific module version +- **config** (optional): Module-specific configuration parameters -### Database with multiple modules +#### Common module configurations -The following example shows a database configured with multiple modules: +##### RediSearch ```yaml -apiVersion: app.redislabs.com/v1alpha1 -kind: RedisEnterpriseDatabase -metadata: - name: multi-module-db - labels: - app: redis-enterprise -spec: - redisEnterpriseCluster: - name: rec - memorySize: 2GB - shardCount: 2 - replication: true - - modulesList: - - name: search - config: "MAXSEARCHRESULTS 50000" - - name: ReJSON - - name: timeseries - config: "RETENTION_POLICY 86400000" - - name: bf +modulesList: + - name: search + config: "MAXSEARCHRESULTS 10000 MAXAGGREGATERESULTS 5000 TIMEOUT 500" ``` -### Active-Active database with modules +##### RedisTimeSeries -For Active-Active databases, you must specify modules with explicit versions: +```yaml +modulesList: + - name: timeseries + config: "RETENTION_POLICY 86400000 MAX_SAMPLE_PER_CHUNK 360" +``` + +##### RedisBloom ```yaml -apiVersion: app.redislabs.com/v1alpha1 -kind: RedisEnterpriseActiveActiveDatabase -metadata: - name: aa-search-db - labels: - app: redis-enterprise -spec: - participatingClusters: - - name: cluster-east - - name: cluster-west - - redisEnterpriseDatabase: - memorySize: 1GB - shardCount: 1 - replication: true - - modulesList: - - name: search - version: "2.8.4" - config: "MAXSEARCHRESULTS 10000" - - name: ReJSON - version: "2.6.6" +modulesList: + - name: bf + config: "ERROR_RATE 0.01 INITIAL_SIZE 1000" ``` -## Module configuration +## Upgrade considerations -### Module parameters +When upgrading Redis Enterprise clusters or the operator with modules, follow these guidelines: -Each module in the `modulesList` supports the following fields: +#### Pre-upgrade planning -- **name** (required): The module name (for example, "search", "ReJSON") -- **version** (optional for REDB, required for REAADB): Specific module version -- **config** (optional): Module-specific configuration parameters +- **Check module compatibility**: Verify that your current module versions are compatible with the target Redis Enterprise version +- **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 -### Common module configurations +#### Module version management during upgrades -#### RediSearch +- **Upload required modules**: Ensure all necessary module versions are uploaded to the cluster before upgrading +- **Version pinning**: For Active-Active databases, explicitly specify module versions to prevent automatic updates +- **Compatibility matrices**: Consult the Redis Enterprise documentation for module compatibility matrices -```yaml -- name: search - config: "MAXSEARCHRESULTS 10000 MAXAGGREGATERESULTS 5000 TIMEOUT 500" -``` +#### Upgrade sequence -#### RedisTimeSeries +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 -```yaml -- name: timeseries - config: "RETENTION_POLICY 86400000 MAX_SAMPLE_PER_CHUNK 360" -``` +#### Post-upgrade verification -#### 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 -```yaml -- name: bf - config: "ERROR_RATE 0.01 INITIAL_SIZE 1000" -``` +For detailed upgrade procedures, see [Upgrade Redis Enterprise clusters]({{< relref "/operate/kubernetes/upgrade/upgrade-redis-cluster" >}}). ## Best practices -### Module version management +#### Module version management - For production environments, specify explicit module versions in Active-Active databases - Use the cluster's available modules list to ensure compatibility - Test module upgrades in non-production environments first -### Resource planning +#### Resource planning - Modules consume additional memory and CPU resources - Plan cluster resources accordingly when using multiple modules - Monitor module-specific metrics and performance -### Configuration management +#### Configuration management - Use module configuration parameters to optimize performance - Document module configurations for consistency across environments - Consider module-specific backup and recovery requirements -### Upgrade considerations - -- Ensure compatible module versions before cluster upgrades -- Upload required module versions before upgrading the cluster -- Review module compatibility matrices in Redis Enterprise documentation - ## Troubleshooting -### Common issues +#### Common issues 1. **Module not available error:** - Check if the module is installed: `kubectl get rec -o jsonpath='{.status.modules}'` @@ -224,7 +171,7 @@ Each module in the `modulesList` supports the following fields: - Validate module configuration parameters - Check Redis Enterprise logs for specific error messages -### Debugging commands +#### Debugging commands ```bash # Check cluster status and available modules @@ -240,13 +187,6 @@ kubectl logs -l name=redis-enterprise-operator kubectl logs ``` -## Examples - -See the `deploy/examples/` directory for additional configuration examples: - -- Basic database: `deploy/examples/v1alpha1/redb.yaml` -- Active-Active database: `deploy/examples/v1alpha1/reaadb.yaml` - ## Related information - [Database controller]({{< relref "/operate/kubernetes/re-databases/db-controller" >}}) - Learn how to create and manage Redis Enterprise databases From 74054d8757576e39a668d046e2b69c04e1646f9b Mon Sep 17 00:00:00 2001 From: Kaitlyn Michael Date: Tue, 2 Sep 2025 14:31:22 -0500 Subject: [PATCH 3/3] changes from SME meeting --- .../kubernetes/re-databases/modules.md | 131 +++--------------- 1 file changed, 18 insertions(+), 113 deletions(-) diff --git a/content/operate/kubernetes/re-databases/modules.md b/content/operate/kubernetes/re-databases/modules.md index 84c5a5d0db..91ab08f714 100644 --- a/content/operate/kubernetes/re-databases/modules.md +++ b/content/operate/kubernetes/re-databases/modules.md @@ -16,20 +16,20 @@ Redis Enterprise modules extend Redis functionality with additional data types, Before you begin, verify that you have: -- Redis Enterprise operator deployed in your Kubernetes cluster -- Redis Enterprise Cluster (REC) running and in a healthy state +- [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)) ## Available modules Redis Enterprise includes several built-in modules: -- **RediSearch** (`search`) - Full-text search and secondary indexing -- **RedisJSON** (`ReJSON`) - JSON data type support -- **RedisTimeSeries** (`timeseries`) - Time series data structures -- **RedisBloom** (`bf`) - Probabilistic data structures (Bloom filters, etc.) -- **RedisGraph** (`graph`) - Graph database capabilities -- **RedisGears** (`rg`) - Programmable data processing engine +| Module | Name | Description | +|--------|------|-------------| +| **[RediSearch]({{< relref "/develop/interact/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.) | ### Check available modules @@ -41,66 +41,23 @@ kubectl get rec -o jsonpath='{.status.modules}' | jq This command shows the modules installed in the cluster along with their available versions. -## Install additional modules - -If you need to install additional modules or specific versions, upload them using the Redis Enterprise API: - -1. Get cluster credentials: - - ```bash - kubectl get secret -o jsonpath='{.data.username}' | base64 -d - kubectl get secret -o jsonpath='{.data.password}' | base64 -d - ``` - -2. Port forward to the cluster API: +{{< note >}} +Use the `NAME` field instead of the `DISPLAY_NAME` field when configuring databases with modules. +{{< /note >}} - ```bash - kubectl port-forward service/ 9443:9443 - ``` - -3. Upload the module: +## Install additional modules - ```bash - curl -k -u : -X POST \ - -F 'module=@' \ - https://localhost:9443/v2/modules - ``` +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. ## Module configuration -#### Module parameters - Each module in the [`modulesList`]({{< relref "/operate/kubernetes/reference/api/redis_enterprise_database_api#specmoduleslist" >}}) supports the following fields: - **name** (required): The module name (for example, "search", "ReJSON") -- **version** (optional for REDB, required for REAADB): Specific module version +- **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 -#### Common module configurations - -##### RediSearch - -```yaml -modulesList: - - name: search - config: "MAXSEARCHRESULTS 10000 MAXAGGREGATERESULTS 5000 TIMEOUT 500" -``` - -##### RedisTimeSeries - -```yaml -modulesList: - - name: timeseries - config: "RETENTION_POLICY 86400000 MAX_SAMPLE_PER_CHUNK 360" -``` - -##### RedisBloom - -```yaml -modulesList: - - name: bf - config: "ERROR_RATE 0.01 INITIAL_SIZE 1000" -``` +For detailed module configuration options and parameters, see [Redis modules]({{< relref "/develop/reference/modules" >}}). ## Upgrade considerations @@ -108,7 +65,7 @@ When upgrading Redis Enterprise clusters or the operator with modules, follow th #### Pre-upgrade planning -- **Check module compatibility**: Verify that your current module versions are compatible with the target Redis Enterprise version +- **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 @@ -116,8 +73,8 @@ When upgrading Redis Enterprise clusters or the operator with modules, follow th #### Module version management during upgrades - **Upload required modules**: Ensure all necessary module versions are uploaded to the cluster before upgrading -- **Version pinning**: For Active-Active databases, explicitly specify module versions to prevent automatic updates -- **Compatibility matrices**: Consult the Redis Enterprise documentation for module compatibility matrices +- **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 sequence @@ -135,58 +92,6 @@ When upgrading Redis Enterprise clusters or the operator with modules, follow th For detailed upgrade procedures, see [Upgrade Redis Enterprise clusters]({{< relref "/operate/kubernetes/upgrade/upgrade-redis-cluster" >}}). -## Best practices - -#### Module version management - -- For production environments, specify explicit module versions in Active-Active databases -- Use the cluster's available modules list to ensure compatibility -- Test module upgrades in non-production environments first - -#### Resource planning - -- Modules consume additional memory and CPU resources -- Plan cluster resources accordingly when using multiple modules -- Monitor module-specific metrics and performance - -#### Configuration management - -- Use module configuration parameters to optimize performance -- Document module configurations for consistency across environments -- Consider module-specific backup and recovery requirements - -## Troubleshooting - -#### Common issues - -1. **Module not available error:** - - Check if the module is installed: `kubectl get rec -o jsonpath='{.status.modules}'` - - Upload the module if missing using the API endpoint - -2. **Version compatibility issues:** - - Verify module version compatibility with your Redis Enterprise version - - Check the Redis Enterprise documentation for supported module versions - -3. **Configuration errors:** - - Validate module configuration parameters - - Check Redis Enterprise logs for specific error messages - -#### Debugging commands - -```bash -# Check cluster status and available modules -kubectl get rec -o yaml - -# Check database status -kubectl get redb -o yaml - -# View operator logs -kubectl logs -l name=redis-enterprise-operator - -# Check cluster logs -kubectl logs -``` - ## Related information - [Database controller]({{< relref "/operate/kubernetes/re-databases/db-controller" >}}) - Learn how to create and manage Redis Enterprise databases