How do I change the cluster mode for my ElastiCache for Valkey or ElastiCache for Redis OSS cluster?

Short description

Note: You can change cluster mode configuration only from cluster mode disabled to cluster mode enabled. After you make this change to the cluster mode, you can't revert your configuration.

Prerequisites:

• The cluster must have keys only in database 0.
• Applications must use a Valkey or Redis OSS client that can use cluster protocol and a configuration endpoint.
• For the cluster, you must turn on auto-failover and have at least 1 replica.
• For migration, your cluster must have an engine version of Valkey 7.2 and later, or Redis OSS 7.0 and later. For more information, see Modifying cluster mode.

To update your cluster mode from cluster mode disabled to cluster mode enabled, complete the following tasks:

1. Update the cluster mode from cluster mode disabled to Compatible.
2. Update the cluster mode from Compatible to cluster mode enabled.

Note: During this migration process, the cluster remains available.

Resolution

Before you move to Compatible mode, you must set the cluster-enabled parameter to yes. If you use a default parameter group, then ElastiCache for Valkey and ElastiCache for Redis OSS chooses the default parameter group. This default parameter group has the cluster-enabled configuration set to yes, and you don't have to take any action.

Note: If you use a custom parameter group, then choose a new parameter group when you modify the cluster. Or, create a new parameter group for the same engine family with the cluster-enabled parameter set to yes.

Update the cluster mode from cluster mode disabled to Compatible

Note: If you receive errors when you run AWS Command Line Interface (AWS CLI) commands, then see Troubleshooting errors for the AWS CLI. Also, make sure that you're using the most recent AWS CLI version.

In Compatible mode, ElastiCache deploys a single shard to work with the node. With this configuration, the client application can use either protocol to communicate with the cluster.

Complete the following steps:

1. Open the ElastiCache console.
2. In the navigation pane, choose your resource type, and then select your cluster.
3. Choose Modify.
4. Under Cluster mode, choose Compatible.
5. (Optional) Choose a custom parameter group with the parameter cluster-enabled set to yes.
   Note: If you use a default parameter group, then no action is needed.
6. Choose Preview changes, and then choose Save changes.

To use the AWS CLI to modify the cluster, run the modify-replication-group command and update the cluster-mode parameter to compatible.

Example:

aws elasticache modify-replication-group \
    --replication-group-id test-cluster \
    --cluster-mode compatible  \
    --apply-immediately

Note: In the preceding example, replace test-cluster with your cluster name. For more information, see Modifying a replication group.

After the cluster mode changes to Compatible, you can use the newly created configuration endpoint to test cluster mode enabled connectivity from the application. You can also use the primary and reader endpoints to service the existing cluster mode disabled connectivity for the cluster.

From Compatible mode, you can also revert to cluster mode disabled and preserve the original configurations.

Update the cluster mode from Compatible to cluster mode enabled

After you migrate all Valkey or Redis OSS clients to cluster mode enabled, the client application becomes cluster-aware. From this status, you can set the cluster mode parameter to enabled.

Complete the following steps:

1. Open the ElastiCache console.
2. In the navigation pane, choose your resource type, and then select your cluster.
3. Choose Modify.
4. Under Cluster mode, choose Enabled.
5. Choose Preview changes, and then choose Save changes.

To use the AWS CLI to modify the cluster, run the modify-replication-group command and update the cluster-mode parameter to enabled.

Example:

aws elasticache modify-replication-group \
    --replication-group-id test-cluster \
    --cluster-mode enabled  \
    --apply-immediately

Note: In the preceding example, replace test-cluster with your cluster name.

After the cluster mode changes complete, the cluster endpoints also change. Because there's no longer a primary or reader endpoint, make sure to update your applications with the new configuration endpoint.

Note: It's a best practice to review the documentation for your client to configure the client to support interaction with a (cluster mode enabled) cluster. For more information, see Cluster specification on the Valkey website.

Related information

Replication: Valkey and Redis OSS Cluster Mode Disabled vs. Enabled

Best practices: Redis clients and Amazon ElastiCache for Redis