{ "schema_version": 2, "id": "operate/kubernetes/upgrade/upgrade-redis-cluster", "title": "Upgrade Redis Enterprise for Kubernetes", "url": "https://redis.io/docs/latest/operate/kubernetes/upgrade/upgrade-redis-cluster/", "summary": "This task describes how to upgrade a Redis Enterprise cluster via the operator.", "tags": [ "docs", "operate", "kubernetes" ], "last_updated": "2026-10-13T20:31:34+05:30", "page_type": "content", "content_hash": "802f44295d6b8ab969617f4b11916a3dc02fb06794d5a64b88ba2f0c2d023e66", "sections": [ { "id": "overview", "title": "Overview", "role": "overview", "text": "Redis implements rolling updates for software upgrades in Kubernetes deployments. The upgrade process includes updating three components:\n\n 1. [Upgrade the Redis Enterprise operator](#upgrade-the-operator)\n 1. [Upgrade the Redis Enterprise cluster (REC)](#upgrade-the-redis-enterprise-cluster-rec)\n 1. [Upgrade Redis Enterprise databases (REDB)](#upgrade-databases)" }, { "id": "prerequisites", "title": "Prerequisites", "role": "content", "text": "Before upgrading, ensure you have the minimum versions of all components necessary for your target version. **Without these minimum versions, the upgrade may freeze and require manual recovery.**\n\nSee the [troubleshooting](#troubleshooting) section for details on recovering a failed upgrade." }, { "id": "kubernetes-version", "title": "Kubernetes version", "role": "content", "text": "Check [Supported Kubernetes distributions](https://redis.io/docs/latest/operate/kubernetes/reference/supported_k8s_distributions) to make sure your Kubernetes distribution is supported by your target Redis Enterprise operator version. If not, upgrade your Kubernetes distribution before upgrading the Redis operator." }, { "id": "redis-operator-version", "title": "Redis operator version", "role": "content", "text": "Check the [Redis Enterprise for Kubernetes release notes](https://redis.io/docs/latest/operate/kubernetes/release-notes) for the minimum operator version required for your target upgrade. Some versions may require intermediate upgrades." }, { "id": "redis-database-version", "title": "Redis database version", "role": "content", "text": "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](https://redis.io/docs/latest/operate/kubernetes/reference/api/redis_enterprise_database_api#spec)." }, { "id": "user-defined-modules", "title": "User-defined modules", "role": "content", "text": "If your databases use user-defined modules (custom non-bundled modules):\n\n- Set `spec.upgradeSpec.autoUpgradeRedisEnterprise: false` in the REC custom resource before upgrading the operator.\n- Define the user-defined modules in the REC custom resource before upgrading the database.\n- See [Edit `redisEnterpriseImageSpec`](#edit-redisenterpriseimagespec-in-the-rec-spec) for more details.\n\nFor more information about user-defined modules, see [User-defined modules](https://redis.io/docs/latest/operate/kubernetes/re-databases/modules#user-defined-modules)." }, { "id": "valid-license", "title": "Valid license", "role": "content", "text": "Use `kubectl get rec` and verify the `LICENSE STATE` is valid on your REC before you start the upgrade process." }, { "id": "upgrade-with-helm-charts", "title": "Upgrade with Helm charts", "role": "content", "text": "If you installed the Redis Enterprise operator using Helm charts, you can upgrade using Helm commands. This method automatically handles the operator upgrade and Custom Resource Definition (CRD) updates.\n\nTo upgrade using Helm:\n\n[code example]\n\nFor example:\n\n[code example]\n\nFor OpenShift installations, include the `openshift.mode=true` parameter:\n\n[code example]\n\nAfter the Helm upgrade completes, continue with [upgrading the Redis Enterprise cluster (REC)](#upgrade-the-redis-enterprise-cluster-rec) and [upgrading databases](#upgrade-databases).\n\nFor detailed Helm upgrade instructions, see [Upgrade the chart](https://redis.io/docs/latest/operate/kubernetes/deployment/helm#upgrade-the-chart)." }, { "id": "upgrade-the-operator", "title": "Upgrade the operator", "role": "content", "text": "> [!WARNING]\n> If your databases use user-defined modules, set `spec.upgradeSpec.autoUpgradeRedisEnterprise: false` in the REC custom resource before upgrading the operator." }, { "id": "download-the-bundle", "title": "Download the bundle", "role": "content", "text": "Make sure you pull the correct version of the bundle. You can find the version tags\nby checking the [operator releases on GitHub](https://github.com/RedisLabs/redis-enterprise-k8s-docs/releases)\nor by [using the GitHub API](https://docs.github.com/en/rest/reference/repos#releases).\n\nYou can download the bundle for the latest release with the following `curl` command:\n\n[code example]\n\nIf you need a different release, replace `VERSION` in the above with a specific release tag." }, { "id": "apply-the-bundle", "title": "Apply the bundle", "role": "content", "text": "Apply the bundle to deploy the new operator binary. This will also apply any changes in the new release to custom resource definitions, roles, role binding, or operator service accounts.\n\n> [!NOTE]\n> If you are not pulling images from Docker Hub, update the operator image spec to point to your private repository.\n> If you have made changes to the role, role binding, RBAC, or custom resource definition (CRD) in the previous version, merge them with the updated declarations in the new version files.\n\nUpgrade the bundle and operator with a single command, passing in the bundle YAML file:\n\n[code example]\n\nAfter running this command, you should see a result similar to this:\n\n[code example]" }, { "id": "reapply-webhook", "title": "Reapply the admission controller webhook", "role": "content", "text": "If you have the admission controller enabled, you need to manually reapply the `ValidatingWebhookConfiguration`.\n\n> [!NOTE]\n> [Versions 6.4.2 and later](https://redis.io/docs/latest/operate/kubernetes/release-notes/previous-releases/) uses a new `ValidatingWebhookConfiguration` resource to replace `redb-admission`. To use newer releases, delete the old webhook resource and apply the new file.\n\n1. Delete the existing `ValidatingWebhookConfiguration` on the Kubernetes cluster (named `redb-admission`).\n\n [code example]\n\n1. Apply the resource from the new file.\n\n [code example]\n \n\n1. Verify the `admission-tls` secret exists.\n\n [code example]\n \n The output should look similar to\n \n [code example]\n\n1. Save the certificate to a local environment variable.\n\n [code example]\n\n1. Create a Kubernetes validating webhook, replacing `` with the namespace where the REC was installed.\n\n The `webhook.yaml` template can be found in [redis-enterprise-k8s-docs/admission](https://github.com/RedisLabs/redis-enterprise-k8s-docs/tree/master/admission)\n\n [code example]\n\n1. Create a patch file for the Kubernetes validating webhook.\n\n [code example]\n\n1. Patch the webhook with the certificate.\n\n [code example]" }, { "id": "verify-the-operator-is-running", "title": "Verify the operator is running", "role": "content", "text": "You can check your deployment to verify the operator is running in your namespace.\n\n[code example]\n\nYou should see a result similar to this:\n\n[code example]\n\n> [!WARNING]\n> We recommend upgrading the REC as soon as possible after updating the operator. After the operator upgrade completes, the operator suspends the management of the REC and its associated REDBs, until the REC upgrade completes." }, { "id": "upgrade-the-redis-enterprise-cluster-rec", "title": "Upgrade the Redis Enterprise cluster (REC)", "role": "content", "text": "The Redis Enterprise cluster (REC) can be updated automatically or manually. To trigger automatic upgrade of the REC after the operator upgrade completes, set `spec.upgradeSpec.autoUpgradeRedisEnterprise: true` in your REC. If you don't have automatic upgrade enabled, follow the below steps for the manual upgrade.\n\n> [!WARNING]\n> Automatic upgrade is incompatible with image digest hashes. If you set a `digestHash` in any image spec (`redisEnterpriseImageSpec`, `redisEnterpriseServicesRiggerImageSpec`, `bootstrapperImageSpec`, or `usageMeter.callHomeClient.imageSpec`) while `autoUpgradeRedisEnterprise` is `true`, the operator invalidates the REC spec and publishes a Kubernetes warning event. Remove all `digestHash` values before you enable automatic upgrade, or upgrade the cluster [manually](#edit-redisenterpriseimagespec-in-the-rec-spec) instead.\n\nBefore beginning the upgrade of the Redis Enterprise cluster, check the [Redis Enterprise for Kubernetes release notes](https://redis.io/docs/latest/operate/kubernetes/release-notes) to find the Redis Enterprise image tag for your target version.\n\nAfter the operator upgrade is complete, you can upgrade Redis Enterprise cluster (REC).\n\n> [!NOTE]\n> For Active-Active databases, we recommend upgrading all participating clusters to the same operator version." }, { "id": "edit-redisenterpriseimagespec-in-the-rec-spec", "title": "Edit `redisEnterpriseImageSpec` in the REC spec", "role": "content", "text": "1. Edit the REC custom resource YAML file.\n\n [code example]\n\n1. Replace the `versionTag:` declaration under `redisEnterpriseImageSpec` with the new version tag.\n\n [code example]\n\n1. Define any user-defined modules used by databases in the cluster.\n\n [code example]\n\n 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.\n\n > [!NOTE]\n > 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.\n >\n\n1. Save the changes to apply." }, { "id": "reapply-roles-and-role-bindings", "title": "Reapply roles and role bindings", "role": "content", "text": "If your operator is monitoring multiple namespaces, you'll need to [reapply your role and role bindings](https://redis.io/docs/latest/operate/kubernetes/re-clusters/multi-namespace#create-role-and-role-binding-for-managed-namespaces) for each managed namespace. See [Manage databases in multiple namespaces](https://redis.io/docs/latest/operate/kubernetes/re-clusters/multi-namespace) for more details." }, { "id": "monitor-the-upgrade", "title": "Monitor the upgrade", "role": "content", "text": "You can view the state of the REC with `kubectl get rec`.\n\n During the upgrade, the state should be `Upgrade`.\n When the upgrade is complete and the cluster is ready to use, the state will change to `Running`.\n If the state is `InvalidUpgrade`, there is an error (usually relating to configuration) in the upgrade.\n\n[code example]\n\nTo see the status of the current rolling upgrade, run:\n\n[code example]" }, { "id": "upgrade-databases", "title": "Upgrade databases", "role": "content", "text": "After the cluster is upgraded, you can upgrade your databases." }, { "id": "upgrade-redb", "title": "Upgrade REDB", "role": "content", "text": "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)." }, { "id": "upgrade-reaadb", "title": "Upgrade REAADB", "role": "content", "text": "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.\n\nIf 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." }, { "id": "upgrade-with-user-defined-modules", "title": "Upgrade with user-defined modules", "role": "content", "text": "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](https://redis.io/docs/latest/operate/kubernetes/re-databases/modules#add-user-defined-modules-to-the-rec) for detailed instructions." }, { "id": "upgrade-policy", "title": "Upgrade policy", "role": "content", "text": "Note that if your cluster [`redisUpgradePolicy`](https://redis.io/docs/latest/operate/kubernetes/reference/api/redis_enterprise_cluster_api#spec) or your database [`redisVersion`](https://redis.io/docs/latest/operate/kubernetes/reference/api/redis_enterprise_database_api#spec) are set to `major`, you won't be able to upgrade those databases to minor versions. See [Redis upgrade policy](https://redis.io/docs/latest/operate/rs/installing-upgrading/upgrading#redis-upgrade-policy) for more details." }, { "id": "troubleshooting", "title": "Troubleshooting", "role": "errors", "text": "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." }, { "id": "user-defined-modules-1", "title": "User-defined modules", "role": "content", "text": "If your databases use user-defined modules and you encounter upgrade issues:\n\n1. **Verify `autoUpgradeRedisEnterprise` is set to `false`**: Check the REC spec to ensure automatic upgrades are disabled.\n\n [code example]\n\n1. **Verify modules are defined in the REC**: Ensure all user-defined modules are listed in the REC `userDefinedModules` section before upgrading.\n\n [code example]\n\n1. **Check module validation errors**: Review the REC status for module validation errors.\n\n [code example]\n\nFor more information about user-defined modules, see [User-defined modules](https://redis.io/docs/latest/operate/kubernetes/re-databases/modules#user-defined-modules)." }, { "id": "invalid-module-version", "title": "Invalid module version", "role": "content", "text": "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.\n\n[code example]\n\nAfter updating the database with the Redis Software API, update the REDB custom resource to reflect the change." }, { "id": "invalid-database-version", "title": "Invalid database version", "role": "content", "text": "If the operator logs show an event related to an incompatible database version, upgrade the database using the Redis Software API.\n\n[code example]\n\nAfter updating the modules with the Redis Software API, update the REDB custom resource to reflect the change." }, { "id": "auto-upgrade-blocked-by-image-digest-hashes", "title": "Auto-upgrade blocked by image digest hashes", "role": "content", "text": "If `autoUpgradeRedisEnterprise` is `true` and any image spec sets a `digestHash`, the operator invalidates the REC spec and blocks the upgrade until you remove the digest hashes. The REC enters the `InvalidUpgrade` state and the operator publishes a Kubernetes warning event describing the problem.\n\n1. **Check the REC events**: Review the event published on the REC.\n\n [code example]\n\n1. **Remove the digest hashes**: Delete the `digestHash` field from every image spec that sets it (`redisEnterpriseImageSpec`, `redisEnterpriseServicesRiggerImageSpec`, `bootstrapperImageSpec`, and `usageMeter.callHomeClient.imageSpec`). Once the spec no longer uses digest hashes, the operator revalidates it and the upgrade proceeds.\n\nAlternatively, set `spec.upgradeSpec.autoUpgradeRedisEnterprise: false` and [upgrade the cluster manually](#edit-redisenterpriseimagespec-in-the-rec-spec), which supports digest hashes." } ], "examples": [ { "id": "upgrade-with-helm-charts-ex0", "language": "sh", "code": "helm upgrade redis/redis-enterprise-operator --version ", "section_id": "upgrade-with-helm-charts" }, { "id": "upgrade-with-helm-charts-ex1", "language": "sh", "code": "helm upgrade my-redis-enterprise redis/redis-enterprise-operator --version ", "section_id": "upgrade-with-helm-charts" }, { "id": "upgrade-with-helm-charts-ex2", "language": "sh", "code": "helm upgrade redis/redis-enterprise-operator --version \\\n --set openshift.mode=true", "section_id": "upgrade-with-helm-charts" }, { "id": "download-the-bundle-ex0", "language": "sh", "code": "VERSION=`curl --silent https://api.github.com/repos/RedisLabs/redis-enterprise-k8s-docs/releases/latest | grep tag_name | awk -F'\"' '{print $4}'`\ncurl --silent -O https://raw.githubusercontent.com/RedisLabs/redis-enterprise-k8s-docs/$VERSION/bundle.yaml", "section_id": "download-the-bundle" }, { "id": "apply-the-bundle-ex0", "language": "sh", "code": "kubectl apply -f bundle.yaml", "section_id": "apply-the-bundle" }, { "id": "apply-the-bundle-ex1", "language": "sh", "code": "role.rbac.authorization.k8s.io/redis-enterprise-operator configured\nserviceaccount/redis-enterprise-operator configured\nrolebinding.rbac.authorization.k8s.io/redis-enterprise-operator configured\ncustomresourcedefinition.apiextensions.k8s.io/redisenterpriseclusters.app.redislabs.com configured\ncustomresourcedefinition.apiextensions.k8s.io/redisenterprisedatabases.app.redislabs.com configured\ndeployment.apps/redis-enterprise-operator configured", "section_id": "apply-the-bundle" }, { "id": "reapply-webhook-ex0", "language": "sh", "code": "kubectl delete ValidatingWebhookConfiguration redb-admission", "section_id": "reapply-webhook" }, { "id": "reapply-webhook-ex1", "language": "sh", "code": "kubectl apply -f deploy/admission/webhook.yaml", "section_id": "reapply-webhook" }, { "id": "reapply-webhook-ex2", "language": "sh", "code": "kubectl get secret admission-tls", "section_id": "reapply-webhook" }, { "id": "reapply-webhook-ex3", "language": "sh", "code": "NAME TYPE DATA AGE\n admission-tls Opaque 2 2m43s", "section_id": "reapply-webhook" }, { "id": "reapply-webhook-ex4", "language": "sh", "code": "CERT=`kubectl get secret admission-tls -o jsonpath='{.data.cert}'`", "section_id": "reapply-webhook" }, { "id": "reapply-webhook-ex5", "language": "sh", "code": "sed 's/OPERATOR_NAMESPACE//g' webhook.yaml | kubectl create -f -", "section_id": "reapply-webhook" }, { "id": "reapply-webhook-ex6", "language": "sh", "code": "cat > modified-webhook.yaml <", "section_id": "edit-redisenterpriseimagespec-in-the-rec-spec" }, { "id": "edit-redisenterpriseimagespec-in-the-rec-spec-ex1", "language": "YAML", "code": "spec:\n redisEnterpriseImageSpec:\n imagePullPolicy: IfNotPresent\n repository: redislabs/redis\n versionTag: ", "section_id": "edit-redisenterpriseimagespec-in-the-rec-spec" }, { "id": "edit-redisenterpriseimagespec-in-the-rec-spec-ex2", "language": "YAML", "code": "spec:\n userDefinedModules:\n - name: \"custom-module\"\n source:\n https:\n url: \"https://modules.company.com/search-v2.1.zip\"\n credentialsSecret: \"module-repo-creds\"", "section_id": "edit-redisenterpriseimagespec-in-the-rec-spec" }, { "id": "monitor-the-upgrade-ex0", "language": "sh", "code": "$ kubectl get rec\nNAME NODES VERSION STATE SPEC STATUS LICENSE STATE SHARDS LIMIT LICENSE EXPIRATION DATE AGE\nrec 3 8.0.2-17 Upgrade Valid Valid 4 2022-07-16T13:59:00Z 92m", "section_id": "monitor-the-upgrade" }, { "id": "monitor-the-upgrade-ex1", "language": "sh", "code": "kubectl rollout status sts ", "section_id": "monitor-the-upgrade" }, { "id": "user-defined-modules-1-ex0", "language": "sh", "code": "kubectl get rec -o jsonpath='{.spec.upgradeSpec.autoUpgradeRedisEnterprise}'", "section_id": "user-defined-modules-1" }, { "id": "user-defined-modules-1-ex1", "language": "sh", "code": "kubectl get rec -o jsonpath='{.spec.userDefinedModules}' | jq", "section_id": "user-defined-modules-1" }, { "id": "user-defined-modules-1-ex2", "language": "sh", "code": "kubectl describe rec ", "section_id": "user-defined-modules-1" }, { "id": "invalid-module-version-ex0", "language": "sh", "code": "curl -sfk -u : -X POST -F 'module=@' https://localhost:9443/v2/modules", "section_id": "invalid-module-version" }, { "id": "invalid-database-version-ex0", "language": "sh", "code": "curl -sfk -u : -X POST -H \"Content-Type: application/json\" -d '{\"redis_version\": }' https://localhost:9443/v1/bdbs//upgrade", "section_id": "invalid-database-version" }, { "id": "auto-upgrade-blocked-by-image-digest-hashes-ex0", "language": "sh", "code": "kubectl describe rec ", "section_id": "auto-upgrade-blocked-by-image-digest-hashes" } ] }