Hash Slots verstehen: wie Redis Cluster Daten verteilt

1. Was Hash Slots sind und warum Redis Cluster sie braucht

Redis Cluster verteilt Daten nicht anhand von Server-Namen oder einem Hash-Ring mit virtuellen Knoten, sondern über ein festes Konzept namens Hash Slots. Jeder Key im gesamten Cluster wird deterministisch genau einem von 16384 Hash Slots zugeordnet, und jeder Knoten im Cluster ist für eine bestimmte Teilmenge dieser Slots verantwortlich. Dieses Modell ist die Grundlage dafür, dass ein Client mit jedem beliebigen Knoten sprechen kann und trotzdem zuverlässig lernt, wohin ein bestimmter Key tatsächlich gehört.

Ohne Hash Slots müsste jeder Client eine vollständige Zuordnungstabelle von Millionen Keys zu Knoten pflegen oder bei jeder Anfrage einen zentralen Koordinator befragen, der schnell zum Flaschenhals würde. Das feste Raster aus 16384 Slots reduziert dieses Problem auf eine kompakte, cachebare Tabelle: Statt einzelne Keys zu verfolgen, muss ein Client nur wissen, welcher Knoten welchen Slot-Bereich besitzt. Das macht horizontale Skalierung praktikabel, ohne dass jede Leseoperation über einen zusätzlichen Proxy laufen muss.

2. Das 16384-Slot-Modell im Detail

Die Zahl 16384, also 2 hoch 14, ist keine Zufallswahl. Sie balanciert zwei gegensätzliche Anforderungen: Die Slot-Bitmap, die jeder Knoten per Gossip-Protokoll an die anderen Cluster-Mitglieder verschickt, muss klein genug bleiben, um den Heartbeat-Traffic nicht zu sprengen, aber groß genug, um bei tausenden Knoten noch eine feine Verteilung zu erlauben. Mit 16384 Bits ergibt das exakt 2048 Byte pro Bitmap, ein Wert, den die Redis-Entwickler bewusst gewählt haben, um Cluster mit bis zu etwa 1000 Knoten praktikabel zu halten.

Jeder der 16384 Hash Slots wird also einem Redis-Knoten fest zugewiesen, wobei die Summe aller zugewiesenen Slots in einem gesunden Cluster immer genau 16384 ergeben muss. Fehlt auch nur ein Slot in der Zuordnung, meldet sich der Cluster standardmäßig als degraded und verweigert Schreiboperationen, sofern die Einstellung cluster-require-full-coverage aktiv ist. Diese Vollständigkeitsprüfung verhindert, dass Daten für einen nicht zugewiesenen Slot-Bereich unbemerkt verloren gehen.

3. CLUSTER KEYSLOT: Slot-Berechnung nachvollziehen

Redis berechnet den Hash Slot eines Keys über die Formel CRC16(key) mod 16384. Der CRC16-Algorithmus ist deterministisch und schnell, sodass jeder Client und jeder Knoten unabhängig zum selben Ergebnis kommt, ohne Rücksprache zu benötigen. Mit dem Befehl CLUSTER KEYSLOT lässt sich dieser Wert direkt über redis-cli abfragen, was beim Debugging von Verteilungsproblemen und beim Design von Key-Schemata unverzichtbar ist.

In der Praxis reicht es fast nie, die CRC16-Formel manuell nachzurechnen. Stattdessen fragt man im laufenden Betrieb einfach nach: CLUSTER KEYSLOT user:1000 liefert sofort den zuständigen Slot. Das ist besonders hilfreich, um zu verstehen, warum zwei fachlich zusammengehörige Keys wie order:1 und order:2 vollständig unterschiedlichen Knoten zugeordnet sein können, obwohl sie inhaltlich verwandt sind.

# Slot-Berechnung für einzelne Keys nachvollziehen
redis-cli -c -h node1.cluster.internal -p 6379 CLUSTER KEYSLOT user:1000
# (integer) 5474

redis-cli -c CLUSTER KEYSLOT order:1
# (integer) 15871

redis-cli -c CLUSTER KEYSLOT order:2
# (integer) 3300

# Beide Keys landen auf unterschiedlichen Slots -> unterschiedliche Knoten moeglich
# Mit Hash Tag erzwingen wir denselben Slot (siehe Abschnitt 6)
redis-cli -c CLUSTER KEYSLOT "order:{42}:items"
# (integer) 9689
redis-cli -c CLUSTER KEYSLOT "order:{42}:status"
# (integer) 9689

4. Slot-Zuweisung an Knoten: CLUSTER NODES und CLUSTER SLOTS

Wer wissen will, welcher Knoten für welchen Slot-Bereich zuständig ist, nutzt CLUSTER NODES oder CLUSTER SLOTS. CLUSTER NODES liefert eine Zeile pro Knoten mit ID, Adresse, Rolle als Master oder Replica, Verbindungsstatus und den zugewiesenen Hash Slots als Von-Bis-Paare. CLUSTER SLOTS liefert dieselbe Information strukturiert für Clients, die programmatisch Routing-Tabellen aufbauen wollen, etwa moderne Redis-Clientbibliotheken mit eigenem Cluster-Support.

Diese Slot-Zuweisung ist nicht statisch für die Lebensdauer des Clusters. Sie kann jederzeit über CLUSTER SETSLOT verändert werden, etwa beim Hinzufügen eines neuen Knotens oder beim gezielten Rebalancing. Wichtig dabei: Jeder Client, der eine veraltete Zuordnung gecacht hat, erhält beim ersten Fehlzugriff eine MOVED-Antwort, die auf den neuen Knoten verweist. Moderne Clients aktualisieren daraufhin automatisch ihre interne Slot-Tabelle, ohne dass die Anwendung eingreifen muss.

redis-cli -c CLUSTER NODES
# 07c37dfeb235213a872192d90877d0cd55635b91 127.0.0.1:6379@16379 myself,master - 0 0 1 connected 0-5460
# 67ed2db8d677e59ec4a4cefb06858cf2a1a89fa1 127.0.0.1:6380@16380 master - 0 1690000001000 2 connected 5461-10922
# 292f8b365bb7edb5e285caf0b7e6ddc7265d2f4f 127.0.0.1:6381@16381 master - 0 1690000002000 3 connected 10923-16383
# 6ec23923021cf3ffec47632106199cb7f496ce01 127.0.0.1:6382@16382 slave 07c37dfeb235213a872192d90877d0cd55635b91 0 1690000003000 1 connected

redis-cli -c CLUSTER SLOTS
# 1) 1) (integer) 0
#    2) (integer) 5460
#    3) 1) "127.0.0.1"
#       2) (integer) 6379
#       3) "07c37dfeb235213a872192d90877d0cd55635b91"

5. Warum Multi-Key-Operationen über Slot-Grenzen fehlschlagen

Redis Cluster erlaubt Multi-Key-Befehle wie MGET, MSET, MULTI/EXEC-Transaktionen oder Lua-Skripte mit EVAL nur dann, wenn alle beteiligten Keys demselben Hash Slot zugeordnet sind. Verletzt eine Anfrage diese Regel, antwortet der Knoten mit dem Fehler CROSSSLOT Keys in request don't hash to the same slot. Das ist keine willkürliche Einschränkung, sondern eine direkte Folge der Architektur: Ein Knoten kann eine atomare Operation nur für Daten garantieren, die er tatsächlich selbst besitzt.

In der Praxis trifft dieser Fehler Teams meist überraschend, wenn zuvor auf einer Single-Node-Instanz getesteter Code plötzlich im Cluster-Betrieb fehlschlägt. Ein MGET über user:1000:profile und user:1000:settings funktioniert nur, wenn beide Keys im selben Hash Slot landen, was ohne explizite Steuerung reiner Zufall ist, da CRC16 über den vollständigen Key-String berechnet wird und unterschiedliche Suffixe zu unterschiedlichen Slots führen können.

Für Anwendungen, die auf serverseitige Transaktionen oder Lua-Skripte über mehrere logisch zusammengehörige Keys angewiesen sind, ist das Verständnis dieser Grenze entscheidend für das Datenmodell. Wer Multi-Key-Operationen über Slot-Grenzen hinweg braucht, muss entweder die Anwendungslogik auf Single-Key-Operationen pro Roundtrip umbauen oder gezielt dafür sorgen, dass zusammengehörige Keys im selben Slot liegen.

# Ohne Hash Tag: CROSSSLOT-Fehler bei Multi-Key-Zugriff
redis-cli -c MSET user:1000:profile "{}" user:1000:settings "{}"
# (error) CROSSSLOT Keys in request don't hash to the same slot

redis-cli -c MGET user:1000:profile user:1000:settings
# (error) CROSSSLOT Keys in request don't hash to the same slot

# Mit Hash Tag: garantiert derselbe Slot, Operation gelingt
redis-cli -c MSET "user:{1000}:profile" "{}" "user:{1000}:settings" "{}"
# OK
redis-cli -c MGET "user:{1000}:profile" "user:{1000}:settings"
# 1) "{}"
# 2) "{}"

6. Hash Tags: Keys gezielt co-lokalisieren

Die Lösung für das CROSSSLOT-Problem sind Hash Tags. Enthält ein Key geschweifte Klammern, berechnet Redis den Hash Slot nur über den Teil zwischen der ersten öffnenden und der ersten schließenden Klammer, nicht über den gesamten Key-String. Der Key user:{1000}:profile und der Key user:{1000}:settings landen dadurch garantiert im selben Slot, weil beide denselben Hash-Tag-Inhalt 1000 verwenden, obwohl die restlichen Zeichenketten unterschiedlich sind.

Dieses Pattern ist der Standardweg, um verwandte Daten in Redis Cluster zusammenzuhalten, etwa alle Datenstrukturen eines einzelnen Mandanten, einer Bestellung oder einer Session. Wichtig dabei: Wird der Hash Tag zu grobkörnig gewählt, etwa ein gemeinsamer Tag für alle Keys eines gesamten Shops statt pro Kunde, sammeln sich enorm viele Keys in einem einzigen Hash Slot, was zu einem Hot Slot und ungleicher Lastverteilung führt.

Eine bewährte Faustregel: Hash Tags so granular wählen, dass sie exakt die Einheit abbilden, für die atomare Multi-Key-Operationen nötig sind, aber nicht gröber. Für eine Anwendung mit Millionen Nutzern bedeutet das üblicherweise einen Hash Tag pro User-ID oder pro Tenant-ID, niemals einen global geteilten Tag, der sämtliche Keys auf einen einzigen Slot zwingt und die Cluster-weite Verteilung faktisch aushebelt.

7. Resharding: Slots zwischen Knoten migrieren

Wächst ein Cluster um neue Knoten oder soll die Last neu verteilt werden, müssen Hash Slots von bestehenden auf neue Knoten migriert werden, ein Vorgang, den Redis Resharding nennt. Der manuelle Weg nutzt CLUSTER SETSLOT mit den Zuständen MIGRATING und IMPORTING: Der Quellknoten markiert einen Slot als migrierend, der Zielknoten als importierend, danach werden die einzelnen Keys im Slot mit MIGRATE nacheinander übertragen.

Der Befehl CLUSTER GETKEYSINSLOT liefert dabei die Liste der Keys in einem bestimmten Slot, damit ein Migrationsskript sie einzeln abarbeiten kann. Während der Migration bleibt der Cluster für Lesezugriffe verfügbar: Ein Client, der einen bereits migrierten Key beim alten Knoten anfragt, erhält eine ASK-Weiterleitung zum neuen Knoten statt eines Fehlers. Das erlaubt Resharding im laufenden Betrieb ohne Downtime, solange die Anwendung ASK- und MOVED-Antworten korrekt behandelt.

In der Praxis nutzt kaum jemand die manuelle Sequenz aus CLUSTER SETSLOT und MIGRATE direkt. Das Kommandozeilentool redis-cli --cluster reshard automatisiert den gesamten Ablauf inklusive gleichmäßiger Verteilung über mehrere Zielknoten und ist der empfohlene Weg für produktive Resharding-Operationen.

# Manuelle Migration eines einzelnen Slots (Prinzip)
redis-cli -h target -p 6380 CLUSTER SETSLOT 5461 IMPORTING <source-node-id>
redis-cli -h source -p 6379 CLUSTER SETSLOT 5461 MIGRATING <target-node-id>

redis-cli -h source -p 6379 CLUSTER GETKEYSINSLOT 5461 100
# 1) "order:{5461-sample}:1"
# 2) "order:{5461-sample}:2"

redis-cli -h source -p 6379 MIGRATE target 6380 "" 0 5000 KEYS \
  "order:{5461-sample}:1" "order:{5461-sample}:2"
# OK

# Nach vollstaendiger Migration: Slot-Besitz final zuweisen
redis-cli -h source -p 6379 CLUSTER SETSLOT 5461 NODE <target-node-id>
redis-cli -h target -p 6380 CLUSTER SETSLOT 5461 NODE <target-node-id>

# Empfohlen: automatisiertes Resharding ueber redis-cli
redis-cli --cluster reshard node1.cluster.internal:6379 \
  --cluster-from <source-node-id> --cluster-to <target-node-id> \
  --cluster-slots 1000 --cluster-yes

8. Slot-Verteilung und Hot Slots überwachen

Eine gleichmäßige Verteilung der 16384 Hash Slots über alle Master-Knoten ist Voraussetzung für gleichmäßige Last, garantiert aber noch keine gleichmäßige Zugriffslast. Ein einzelner extrem populärer Key, etwa ein globaler Zähler oder ein häufig gelesenes Konfigurationsobjekt, kann einen einzelnen Slot und damit einen einzelnen Knoten deutlich stärker belasten als alle anderen. Dieses Phänomen wird als Hot Slot bezeichnet und ist mit reiner Slot-Zählung nicht erkennbar.

Zur Überwachung eignet sich eine Kombination aus CLUSTER COUNTKEYSINSLOT pro Slot, um die reine Key-Anzahl zu prüfen, und redis-cli --hotkeys beziehungsweise redis-cli --bigkeys, um einzelne stark frequentierte oder große Keys zu identifizieren. Regelmäßige Stichproben über alle 16384 Hash Slots hinweg zeigen, ob die Verteilung der Slot-Zuweisung noch der tatsächlichen Zugriffslast entspricht oder ob ein gezieltes Resharding notwendig wird, um einen überlasteten Knoten zu entlasten.

# Sample key counts across all 16384 slots to spot uneven distribution
for slot in 0 5460 5461 10922 10923 16383; do
  count=$(redis-cli -c CLUSTER COUNTKEYSINSLOT "$slot")
  echo "slot $slot: $count keys"
done
# slot 0: 812 keys
# slot 5460: 799 keys
# slot 5461: 214032 keys   <- suspiciously high, likely a hot slot
# slot 10922: 803 keys
# slot 10923: 790 keys
# slot 16383: 811 keys

# Identify frequently accessed keys within a suspected hot slot
redis-cli -c --hotkeys
redis-cli -c --bigkeys

9. Typische Fallstricke im Umgang mit Hash Slots

Der häufigste Fehler ist die Annahme, Redis Cluster verteile Daten automatisch gleichmäßig, ohne dass die Anwendung etwas dafür tun muss. Ohne bewusste Key-Gestaltung mit Hash Tags landen fachlich zusammengehörige Daten zufällig auf verschiedenen Slots, was Multi-Key-Operationen unmöglich macht und Anwendungscode zu vielen einzelnen Roundtrips zwingt, statt eine einzige effiziente Operation zu nutzen.

Ein zweiter Fallstrick ist die übertriebene Nutzung von Hash Tags: Wird ein zu grober Tag gewählt, sammeln sich Millionen Keys in einem einzigen Hash Slot, und dieser eine Knoten wird zum Flaschenhals, während die restlichen 16383 Slots kaum belastet sind. Ein dritter Fallstrick betrifft cluster-require-full-coverage: Wird diese Einstellung im Produktivbetrieb deaktiviert, akzeptiert der Cluster Schreiboperationen selbst dann, wenn einzelne Slots temporär niemandem zugeordnet sind, was zu stillem, unbemerktem Datenverlust führen kann.

10. Zusammenfassung

Hash Slots sind das Fundament der Datenverteilung in Redis Cluster: 16384 feste Slots, jeder Key über CRC16(key) mod 16384 genau einem Slot zugeordnet, jeder Knoten für einen zusammenhängenden Bereich verantwortlich. CLUSTER KEYSLOT macht diese Zuordnung jederzeit nachvollziehbar, CLUSTER NODES und CLUSTER SLOTS zeigen die aktuelle Zuweisung. Multi-Key-Operationen scheitern mit dem CROSSSLOT-Fehler, sobald beteiligte Keys unterschiedlichen Slots angehören, und Hash Tags in geschweiften Klammern lösen dieses Problem, indem sie gezielt denselben Slot erzwingen.

Resharding mit CLUSTER SETSLOT, MIGRATE und dem komfortablen redis-cli --cluster reshard verschiebt Slots ohne Downtime, wenn der Cluster wächst oder die Last neu verteilt werden muss. Wer Hash Tags zu grob wählt, riskiert Hot Slots, die einen einzelnen Knoten überlasten, während CLUSTER COUNTKEYSINSLOT und redis-cli --hotkeys solche Ungleichgewichte frühzeitig sichtbar machen. Ein durchdachtes Key-Schema mit granularen Hash Tags ist damit keine Optimierung im Nachhinein, sondern eine Grundvoraussetzung für stabilen Cluster-Betrieb.

11. FAQ: Hash Slots in Redis Cluster