CacheInvalidation.org

Redis Cluster Slot Allocation Basics

Redis Cluster partitions the keyspace into exactly 16,384 hash slots, bypassing traditional consistent hashing in favor of a deterministic modulo operation: CRC16(key) % 16384. This fixed-range architecture guarantees predictable routing, simplifies topology reconciliation, and eliminates the complex ring-walking logic required by older distributed caches. Each primary node is assigned a contiguous subset of these slots, and the authoritative mapping is persisted in the nodes.conf file (referenced via cluster-config-file). When a client executes a command, the routing layer computes the target slot, consults its cached topology map, and forwards the request to the owning primary.

flowchart LR
    KEY["key (or {hashtag})"] -->|CRC16 mod 16384| SLOT[slot 0..16383]
    SLOT --> MAP[(client slot-to-node map)]
    MAP --> NODE[Owning primary]
    NODE -. MOVED if the map is stale .-> MAP

Mastering this allocation model is a prerequisite for executing Redis Cluster Scaling, Sharding & Automation without introducing routing bottlenecks or risking partition-level data loss.

Topology Initialization & Critical Parameters

Initial slot distribution occurs during cluster bootstrap. Using redis-cli --cluster create, operators define primary-replica pairings and automatically distribute the 16,384 slots evenly across primaries. For infrastructure-as-code deployments, this step is typically wrapped in idempotent provisioning scripts that validate gossip convergence before marking nodes as production-ready. Every primary must hold at least one slot to own keyspace and accept write traffic; a primary with zero slots still participates in the gossip protocol but serves no data.

Configuration tuning directly impacts fault tolerance and split-brain resilience:

  • cluster-node-timeout: Set between 5,000ms and 15,000ms. Values below 5,000ms risk cascading failovers during transient network jitter; values above 15,000ms delay automatic failover during genuine outages.
  • cluster-migration-barrier: Defaults to 1. This dictates the minimum number of replicas a primary must retain before an orphaned primary can steal a replica. Adjusting this parameter is critical when automating Automated Node Provisioning & Removal in dynamic environments.

Validate topology health immediately after bootstrap:

redis-cli -c -h 10.0.1.10 -p 6379 CLUSTER NODES
redis-cli -c -h 10.0.1.10 -p 6379 CLUSTER SLOTS

Client-Side Routing & Redirect Semantics

Production clients maintain a local slot-to-node cache. When topology changes occur—due to scaling, failover, or manual rebalancing—the cache becomes stale. Redis handles this via two redirect responses:

  • MOVED <slot> <ip>:<port>: Indicates permanent ownership change. Clients must update their routing table and retry the command.
  • ASK <slot> <ip>:<port>: Indicates a slot is mid-migration. The client must send an ASKING command to the destination node before retrying the original operation.

Python developers leveraging redis-py must configure the cluster client to handle these redirects transparently. Enable timeout retries and exponential backoff to absorb transient routing churn:

from redis.cluster import RedisCluster
from redis.retry import Retry
from redis.backoff import ExponentialBackoff
from redis.exceptions import ConnectionError, TimeoutError

# Requires redis-py >= 4.2.0
retry_strategy = Retry(ExponentialBackoff(), 3)

client = RedisCluster(
    host="10.0.1.10",
    port=6379,
    retry=retry_strategy,
    retry_on_timeout=True,
    max_connections=200,
    read_from_replicas=True
)

# Automatic MOVED/ASK handling is built into the driver
client.set("user:1001:profile", "active_data")

Proper redirect handling is non-negotiable when executing Zero-Downtime Slot Migration during peak traffic windows.

Atomic Slot Migration & Rebalancing

Slot redistribution relies on the CLUSTER SETSLOT state machine and the MIGRATE command. The migration sequence follows a strict protocol:

  1. Destination node: CLUSTER SETSLOT <slot> IMPORTING <source_node_id> (prepare the target first)
  2. Source node: CLUSTER SETSLOT <slot> MIGRATING <dest_node_id>
  3. Data transfer: MIGRATE <dest_ip> <dest_port> "" 0 <timeout> KEYS <key1> <key2> ...
  4. Finalize: CLUSTER SETSLOT <slot> NODE <dest_node_id> on all nodes.

Critical operational rule: Always invoke MIGRATE without the COPY or REPLACE modifiers. Omitting COPY ensures keys are deleted from the source after successful transfer, preventing duplicate writes. Omitting REPLACE guarantees that if a key already exists on the destination, the migration aborts rather than silently overwriting newer data. The MIGRATE command is atomic per key; batching keys in groups of 1,000–5,000 prevents blocking the source node’s event loop.

Observability, Skew Detection & Tuning

Uniform slot distribution is a theoretical ideal. Real-world workloads introduce skew through hot keys, large hash structures, or sequential time-series patterns. A single overloaded slot can saturate CPU or memory on its owning node while leaving others idle.

Monitor cluster health via redis_exporter and Prometheus. Key metrics include:

  • redis_cluster_slots_assigned: Should equal 16,384 across the cluster.
  • redis_cluster_slots_ok: Validates slot health and replication status.
  • redis_cluster_known_nodes: Tracks gossip membership stability.

PromQL alert for slot imbalance:

# redis_cluster_slots_assigned is cluster-wide (always 16384), so use it to alert
# on missing coverage. Per-node ownership skew must be derived from CLUSTER NODES /
# CLUSTER SHARDS (e.g. exported via a recording rule), not from this metric.
redis_cluster_slots_assigned != 16384

To diagnose runtime skew, use redis-cli --cluster check or analyze INFO keyspace per node. Mitigation strategies include key tagging (hash tags {user_id}), migrating hot keys manually, or adjusting application-level sharding logic. Comprehensive guidance on these patterns is documented in Tuning Hash Slot Distribution for Skewed Data.

For authoritative reference on the cluster protocol specification and client implementation standards, consult the official Redis Cluster Specification and the redis-py Cluster Documentation.