Que es un cluster Redis/Valkey

Cuando una unica instancia de Redis o Valkey no soporta el volumen de datos o throughput necesario, el modo Cluster permite distribuir los datos entre multiples nodos. En vez de mantener todo en un unico servidor, el cluster particiona el keyspace en 16384 hash slots y distribuye esos slots entre los nodos disponibles.

Cada nodo del cluster es responsable de un subconjunto de los slots. Cuando un cliente ejecuta un comando, el cluster calcula el hash slot de la clave y dirige la operacion al nodo correcto. Si el cliente envia el comando al nodo equivocado, recibe una redireccion MOVED con la direccion del nodo correcto.

Distribucion tipica con 3 nodos:

NodoSlots
Nodo A0-5460
Nodo B5461-10922
Nodo C10923-16383

Esta distribucion puede ser rebalanceada conforme se agregan o remueven nodos. El comando CLUSTER SLOTS o CLUSTER SHARDS permite consultar la distribucion actual.

Hash Slots: como funcionan los 16384 slots

El hash slot de una clave es determinado por los 14 bits menos significativos del CRC16 de la clave:

slot = CRC16(key) mod 16384

Este calculo es deterministico: la misma clave siempre resulta en el mismo slot y, por lo tanto, en el mismo nodo. Clientes inteligentes (como redis-cli --cluster, Lettuce o Jedis en modo cluster) calculan el slot localmente y envian el comando directamente al nodo correcto, evitando redirecciones innecesarias.

El total de 16384 slots es un valor fijo de la especificacion. No importa si el cluster tiene 3 o 100 nodos — los slots son siempre 16384, solo redistribuidos.

El problema del CROSSSLOT

En un escenario comun, diferentes claves de un mismo usuario terminan en slots diferentes porque el CRC16 se calcula sobre la clave completa:

SET user:1000:profile "Joao"      # slot 8421 -> Nodo B
SET user:1000:orders "[...]"      # slot 12657 -> Nodo C
SET user:1000:settings "{...}"    # slot 3891 -> Nodo A

Acceder a estas claves individualmente funciona sin problemas. El error aparece al intentar operaciones multi-key:

MGET user:1000:profile user:1000:orders user:1000:settings
# ERROR: CROSSSLOT Keys in request don't hash to the same slot

El cluster no puede ejecutar una unica operacion atomica entre nodos diferentes. Comandos afectados:

  • MGET, MSET, DEL con multiples claves
  • Transacciones con MULTI/EXEC
  • Scripts Lua que acceden a multiples claves
  • Pipelines con claves en slots diferentes

El error CROSSSLOT es una restriccion arquitectonica: el cluster no tiene un coordinador de transacciones distribuidas entre nodos.

HashTags: la solucion con {prefix}

Redis y Valkey ofrecen un mecanismo llamado HashTags. Si una clave contiene el patron {...}, solo el contenido entre las primeras llaves {} es usado para calcular el hash slot:

SET {user:1000}:profile "Joao"      # slot 7542 -> Nodo B
SET {user:1000}:orders "[...]"      # slot 7542 -> Nodo B
SET {user:1000}:settings "{...}"    # slot 7542 -> Nodo B

Todas las claves con el mismo HashTag {user:1000} caen en el mismo slot. Ahora las operaciones multi-key funcionan:

MGET {user:1000}:profile {user:1000}:orders {user:1000}:settings
# OK - todas las claves estan en el slot 7542

Pipelines y transacciones tambien funcionan correctamente, ya que el cluster resuelve todo en un unico nodo.

La regla de parsing es simple: el cluster busca la primera ocurrencia de { y la primera ocurrencia de } despues de ella. Si el contenido entre ellos no esta vacio, se usa como input del CRC16. Si {} esta vacio o no existe, se usa la clave completa.

Cuando usar HashTags y cuando evitarlos

Los HashTags resuelven el CROSSSLOT, pero introducen riesgos:

Usa cuando:

  • Necesitas operaciones multi-key sobre datos relacionados (perfil + pedidos + configuraciones de un usuario)
  • Necesitas transacciones atomicas entre claves relacionadas
  • Scripts Lua que manipulan multiples claves del mismo contexto

Evita cuando:

  • Las claves no necesitan ser accedidas juntas (operaciones GET/SET individuales no necesitan HashTags)
  • El HashTag tiene baja cardinalidad (ej: {orders} colocaria TODOS los pedidos en el mismo nodo)
  • Una entidad concentra un volumen desproporcionado de datos — esto crea hot keys y sobrecarga un unico nodo mientras los demas permanecen ociosos

Monitorea la distribucion:

CLUSTER SLOTS
CLUSTER SHARDS

Si un nodo esta consistentemente mas cargado que los otros, puede ser senal de HashTags con pocos valores distintos. Prefiere tags con alta cardinalidad, como IDs de usuario o tenant.

Valkey vs Redis

Desde 2024, Valkey es el fork open-source de Redis, mantenido por la Linux Foundation. Surgio tras el cambio de licencia de Redis (de BSD a dual-license con SSPL/RSALv2). Valkey mantiene compatibilidad total con el protocolo y comandos de Redis, incluyendo todo el comportamiento de cluster, hash slots y HashTags descrito aqui. Si ya usas Redis Cluster, la migracion a Valkey es transparente en terminos de protocolo y comandos.

Referencias