Upgrade Redis Software Cluster – Redis Knowledge Base

Upgrading a Redis Software cluster requires careful planning to ensure data integrity, cluster stability, and minimal downtime. Supported upgrade paths must be followed, prerequisites verified, and the correct method chosen based on environment size and availability requirements. This guide outlines Supported Upgrade Paths, Upgrade Prerequisites, Upgrade Methods (In-place and Rolling), Post-Upgrade Actions, and Troubleshooting Best Practices drawn from real-world support cases.

Supported Upgrade Paths

Direct upgrades are supported only between consecutive major versions (e.g., 6.2 → 7.0 → 7.2).
Skipping major versions is not supported.
If a direct upgrade isn’t supported, upgrade to an intermediate version first.
Always confirm compatibility with the Upgrade Paths Matrix before starting.

Review Release Notes – Understand new features, changes, and limitations.
Validate Supported Path – Confirm your current → target version is supported.
Database Compatibility – Upgrade databases to compatible versions first.
System Access – Ensure you can run:
```
rlcheck
rladmin
```
Check Cluster Health – Run:
```
rladmin status extra all
rladmin cluster running_actions
```
Do not proceed if any shard, node, or endpoint is not OK.
Identify Primary Node – Upgrade the primary (master) node first:
- In Cluster Manager UI (v7.2+)
- Using:
```
rladmin status nodes
```
- Or via the REST API:
```
GET /nodes/status
```

Note: Redis for Kubernetes has a separate support lifecycle. See Supported Kubernetes Distributions for details.

Best for: Simpler, smaller environments (short service interruption per node).

Validate Node:
```
rlcheck
rladmin status extra all
```
Download & Extract package from the Redis Download Center:
```
tar vxf <tarfile>
```
Install (must be root):
```
sudo ./install.sh
```
Verify Upgrade:
```
rlcheck
rladmin status
```
Repeat for each node, one at a time.

Best for: Production environments requiring high availability.

A. Extra Node Method

B. Replace Node Method

Rejoin the cluster:

rladmin cluster join nodes <cluster_member_ip_address> \
  username <username> password <password> replace_node <node_id>

Confirm all nodes are upgraded and healthy:
```
rladmin status extra all
```
Some features become available only after all nodes are upgraded.
For Active-Active deployments: upgrade all clusters before upgrading databases.

Upgrade each database:

rladmin upgrade db db:<DB ID> preserve_roles latest_with_modules

You no longer need to pre-upload module packages compiled for the target OS before upgrading nodes.
Instead, use the custom module management APIs to reapply or update modules post-upgrade.
For Active-Active (CRDB) deployments, after all instances have been upgraded, run the following to synchronize updated module configurations across clusters:

crdb-cli crdb update --crdb-guid <guid> --update-db-config-modules true

This ensures consistent module versions and configurations in all participating databases.

Issue	Resolution / Lesson
Background task stuck	Check rladmin cluster running_actions and clear tasks before proceeding.
Port conflict after upgrade	Fully stop Redis processes, ensure no rogue processes remain, then restart.
Buffer too small for dataset	Increase replication slave buffer size before upgrade.
Shard migration errors	Only migrate shards after nodes are on the same version.
Cluster hang after upgrading wrong node first	Always start with the primary/master node.
Change-master request fails with HTTP 406	Beginning in Redis Software 8.0.2-17, POST /v1/cluster/actions/change_master rejects requests to nodes that are still bootstrapping. Verify node readiness (rladmin status nodes) before issuing change-master commands.

Related to