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 and 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 and 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. Unlike MOVED, the slot table must not be updated — the redirect is temporary.

Python developers leveraging redis-py must configure the cluster client to handle these redirects transparently:

from redis.cluster import RedisCluster
from redis.retry import Retry
from redis.backoff import ExponentialBackoff

# 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 and Rebalancing

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

  1. Destination first: CLUSTER SETSLOT <slot> IMPORTING <source_node_id> — the target must be ready to accept redirected requests before the source begins sending them.
  2. Source second: CLUSTER SETSLOT <slot> MIGRATING <dest_node_id>
  3. Data transfer: MIGRATE <dest_ip> <dest_port> "" 0 <timeout> KEYS <key1> <key2> ... — pass REPLACE to overwrite any stale copy on the destination; omit COPY so keys are deleted from the source after a successful transfer.
  4. Finalize: CLUSTER SETSLOT <slot> NODE <dest_node_id> on the destination and source nodes. This commits permanent ownership and triggers gossip propagation.

Note: CLUSTER SETSLOT <slot> STABLE only cancels an in-progress migration state (clears IMPORTING/MIGRATING flags) — it does not transfer ownership and should only be used to abort a stalled migration.

The MIGRATE command is atomic per key; batching keys in groups of 1,000–5,000 prevents blocking the source node's event loop. Use CLUSTER GETKEYSINSLOT <slot> <count> to retrieve keys belonging to a slot in batches.

Observability, Skew Detection, and 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; use this to alert on missing slot coverage.
  • redis_cluster_slots_ok: Validates slot health and replication status.
  • redis_cluster_known_nodes: Tracks gossip membership stability.

PromQL alert for missing slot coverage:

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.

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