O que e um cluster Redis/Valkey

Quando uma unica instancia de Redis ou Valkey nao suporta o volume de dados ou throughput necessario, o modo Cluster permite distribuir os dados entre multiplos nos. Em vez de manter tudo em um unico servidor, o cluster particiona o keyspace em 16384 hash slots e distribui esses slots entre os nos disponiveis.

Cada no do cluster e responsavel por um subconjunto dos slots. Quando um cliente executa um comando, o cluster calcula o hash slot da chave e direciona a operacao para o no correto. Se o cliente envia o comando para o no errado, recebe um redirecionamento MOVED com o endereco do no correto.

A distribuicao tipica com 3 nos:

NoSlots
No A0-5460
No B5461-10922
No C10923-16383

Essa distribuicao pode ser rebalanceada conforme nos sao adicionados ou removidos. O comando CLUSTER SLOTS ou CLUSTER SHARDS permite consultar a distribuicao atual.

Hash Slots: como funcionam os 16384 slots

O hash slot de uma chave e determinado pelos 14 bits menos significativos do CRC16 da chave:

slot = CRC16(key) mod 16384

Esse calculo e deterministico: a mesma chave sempre resulta no mesmo slot e, portanto, no mesmo no. Clientes inteligentes (como redis-cli --cluster, Lettuce ou Jedis no modo cluster) calculam o slot localmente e enviam o comando diretamente para o no correto, evitando redirecionamentos.

O total de 16384 slots e um valor fixo da especificacao. Nao importa se o cluster tem 3 ou 100 nos — os slots sao sempre 16384, apenas redistribuidos.

O problema do CROSSSLOT

Em um cenario comum, diferentes chaves de um mesmo usuario acabam em slots diferentes porque o CRC16 e calculado sobre a chave inteira:

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

Acessar essas chaves individualmente funciona sem problemas. O erro aparece ao tentar operacoes multi-key:

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

O cluster nao consegue executar uma unica operacao atomica entre nos diferentes. Comandos afetados:

  • MGET, MSET, DEL com multiplas chaves
  • Transacoes com MULTI/EXEC
  • Scripts Lua que acessam multiplas chaves
  • Pipelines com chaves em slots diferentes

O erro CROSSSLOT e uma restricao arquitetural: o cluster nao tem um coordenador de transacoes distribuidas entre nos.

HashTags: a solucao com {prefix}

O Redis e o Valkey oferecem um mecanismo chamado HashTags. Se uma chave contem o padrao {...}, apenas o conteudo entre as primeiras chaves {} e usado para calcular o hash slot:

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

Todas as chaves com a mesma HashTag {user:1000} caem no mesmo slot. Agora operacoes multi-key funcionam:

MGET {user:1000}:profile {user:1000}:orders {user:1000}:settings
# OK - todas as chaves estao no slot 7542

Pipelines e transacoes tambem passam a funcionar, ja que o cluster resolve tudo em um unico no.

A regra de parsing e simples: o cluster procura a primeira ocorrencia de { e a primeira ocorrencia de } apos ela. Se o conteudo entre eles nao e vazio, ele e usado como input do CRC16. Se {} esta vazio ou nao existe, a chave inteira e usada.

Quando usar HashTags e quando evitar

HashTags resolvem o CROSSSLOT, mas introduzem riscos:

Use quando:

  • Precisa de operacoes multi-key sobre dados relacionados (perfil + pedidos + configuracoes de um usuario)
  • Precisa de transacoes atomicas entre chaves relacionadas
  • Scripts Lua que manipulam multiplas chaves do mesmo contexto

Evite quando:

  • As chaves nao precisam ser acessadas juntas (GET/SET individuais nao precisam de HashTags)
  • A HashTag tem baixa cardinalidade (ex: {orders} colocaria TODOS os pedidos no mesmo no)
  • Uma entidade concentra volume desproporcional de dados — isso cria hot keys e sobrecarrega um unico no enquanto os demais ficam ociosos

Monitore a distribuicao:

CLUSTER SLOTS
CLUSTER SHARDS

Se um no esta consistentemente mais carregado que os outros, pode ser sinal de HashTags com poucos valores distintos. Prefira tags com alta cardinalidade, como IDs de usuario ou tenant.

Valkey vs Redis

Desde 2024, o Valkey e o fork open-source do Redis, mantido pela Linux Foundation. Ele surgiu apos a mudanca de licenca do Redis (de BSD para dual-license com SSPL/RSALv2). O Valkey mantém compatibilidade total com o protocolo e comandos do Redis, incluindo todo o comportamento de cluster, hash slots e HashTags descrito aqui. Se voce ja usa Redis Cluster, a migracao para Valkey e transparente em termos de protocolo e comandos.

Referencias