Redis / Valkey: operação diária e cenários de falha (Cluster e Sentinel)

Não é instalação: runbook por cenários para administrar no dia a dia um Redis Cluster já instalado ou uma estrutura master/replica com Sentinel e recuperá-la quando quebrar (Redis 7.2, Redis 8 e Valkey). Cluster: verificação de saúde, adição/remoção de nodes, rebalance/reshard, failover manual (diferença entre FORCE/TAKEOVER), substituição de node com defeito e --cluster fix. Sentinel: estado e quorum, SENTINEL FAILOVER, adição/remoção de nodes e SENTINEL RESET, alteração de configuração. Nos dois: diagnóstico de pressão de memória e de chaves grandes/quentes. Se não souber o que fazer, comece pela verificação de saúde; restauração de backup e hardening de segurança estão em guias Redis separados.

Topologia: Redis Cluster (3+ masters + replicas) ou Sentinel (1 master + replicas + 3 Sentinels)

Cenários

• Verificação de saúde do cluster (--cluster check, CLUSTER INFO / NODES) — Somente leitura: todos os slots estão cobertos, os nodes têm a mesma configuração, há node caído (fail) ou master sem replica? Se não tiver certeza do que fazer, comece por aqui.
• Adicionar node ao cluster (master ou replica) — A nova instância (cluster-enabled yes, vazia) está pronta: entra no cluster como master e recebe slots, ou vira replica de um master. Sem interrupção.
• Remover node do cluster (esvaziar slots + del-node) — Um master ou replica vai ser aposentado: os slots do master são movidos para os outros masters e depois o node é removido do cluster. Sem interrupção; durante a migração ocorre redirecionamento ASK.
• Redistribuir os slots (rebalance / reshard) — Os slots ou a memória estão desbalanceados entre os masters, um novo master não recebeu slots, ou um número definido de slots será movido de um master para outro.
• Failover manual: promover a replica a master (CLUSTER FAILOVER, FORCE, TAKEOVER) — Haverá manutenção no servidor do master (planejada, sem perda de dados), ou o master está inacessível e o failover automático não ocorreu (FORCE / TAKEOVER; risco de perda de dados).
• Substituir master / node com defeito (FORGET, nova replica, --cluster fix) — O servidor de um node foi perdido de vez: se a replica dele virou master, o node antigo é esquecido e uma nova replica é adicionada no lugar; se não havia replica, os slots ficam sem dono e são cobertos com --cluster fix (os dados desses slots são perdidos).
• Estado do Sentinel: master, replicas, Sentinels, quorum — Somente leitura: o endereço do master visto pelos Sentinels, as replicas, os outros Sentinels, CKQUORUM e os últimos eventos de failover. Em uma estrutura com Sentinel, se não tiver certeza do que fazer, comece por aqui.
• Failover manual com o Sentinel (SENTINEL FAILOVER) — Haverá manutenção no servidor do master: o Sentinel promove a replica mais adequada a master e redireciona as outras replicas e os clientes para o novo master. Interrupção de 1–2 s; com o master em execução, sem perda de dados.
• Adicionar / remover / substituir node no ambiente Sentinel (SENTINEL RESET) — Uma replica ou um Sentinel foi removido de vez ou adicionado: a nova replica se conecta com REPLICAOF e os registros antigos dos Sentinels são limpos com SENTINEL RESET.
• Alterar o quorum e as configurações do Sentinel (SENTINEL SET) — O número de Sentinels mudou ou o failover dispara tarde demais/cedo demais: quorum, down-after-milliseconds, failover-timeout e parallel-syncs são alterados em todos os Sentinels.
• Pressão de memória: diagnóstico de uso, fragmentação e eviction — used_memory se aproximou de maxmemory, erro 'OOM command not allowed', eviction aumentando, RSS maior que o esperado ou buffers de replica/AOF inchados. O diagnóstico é somente leitura; as opções de solução são descritas à parte.
• Encontrar chaves grandes e quentes (--bigkeys, --memkeys, --hotkeys) — A memória ou a CPU de um único node está mais alta que a dos outros, há picos de latência, o DEL demora: as maiores chaves e as mais acessadas são encontradas e limpas com segurança (UNLINK).

Antes de começar

• O … está instalado no servidor de administração (vem com o …, /usr/bin/…) e há acesso …à instância ……a todos os nodes do cluster, tanto pela porta de cliente quanto pela porta do cluster bus (porta + 10000)…aos Sentinels (…) e ao Redis (…)….
• Você tem a senha do … (requirepass / masterauth); ela é pedida nos passos ou lida da variável de ambiente REDIS_PASS. Se usar ACL, o usuário precisa das permissões +@admin (comandos de cluster/sentinel) e +@keyspace.
• O registro de mudança foi aberto e a equipe de aplicação foi informada. Failover e migração de slots podem causar nos clientes redirecionamentos MOVED/ASK breves ou quedas de conexão; clientes com suporte a cluster (cluster-aware) os acompanham sozinhos.
• A nova instância … está pronta como no guia de instalação do Redis Cluster: mesma versão do …, cluster-enabled yes, mesmos requirepass/masterauth, diretório de dados vazio (sem nodes-.conf, RDB/AOF antigos), portas de cliente e de bus (porta + 10000) abertas no firewall.

Fases do guia

• Estado: cobertura de slots, nodes e consistência da configuração (somente leitura) — Verificar o cluster (--cluster check) · Mostrar os nodes, os papéis e a distribuição das replicas · Interpretar o resultado
• 1. Diagnóstico: o novo node está vazio e acessível? — Verificar o novo node e o cluster
• 2. Aplicação: adicionar o node — Adicionar o node ao cluster (--cluster add-node) · Distribuir os slots para o novo master (rebalance) · Planejar uma replica para o novo master
• 3. Verificação — Verificar o cluster e o novo node
• 1. Diagnóstico: o node é master, tem slots? — Ver o papel e os slots do node a remover
• 2. Aplicação: esvaziar os slots e remover o node — Mover os slots do master para os outros masters · Remover o node do cluster (--cluster del-node) · Desativar o serviço no servidor removido
• 3. Verificação — Verificar o cluster
• 1. Diagnóstico: distribuição atual — Slots, chaves e memória por master
• 2. Aplicação — …Equalizar os slots (rebalance)…Mover … slots (reshard)…
• 1. Diagnóstico — Ver o papel da replica e a conexão com o master
• 2. Aplicação — Iniciar o failover (CLUSTER FAILOVER… FORCE… TAKEOVER…)
• 3. Verificação — Verificar a nova estrutura
• 1. Diagnóstico: node perdido e cobertura de slots — Ver os nodes em estado fail e os slots sem dono
• 2. Aplicação: esquecer o node perdido — Fazer todos os nodes esquecerem o node perdido (CLUSTER FORGET) · Cobrir os slots sem dono (--cluster fix) · Adicionar o novo node como replica
• 3. Verificação e próximos passos — Verificar o cluster
• Estado: master, replicas, Sentinels (somente leitura) — O master e o quorum vistos pelo Sentinel · Listar as replicas e os outros Sentinels · Procurar os últimos eventos de failover no log do Sentinel
• 1. Diagnóstico — Confirmar que o quorum e as replicas estão prontos
• 2. Aplicação — Iniciar o failover (SENTINEL FAILOVER)
• 3. Verificação — Verificar o novo master e as replicas
• 1. Diagnóstico — Número de replicas e de Sentinels conhecidos pelos Sentinels
• 2. Aplicação — Conectar a nova replica ao master · Desligar o serviço da replica removida · Iniciar o novo Sentinel · Desligar o Sentinel removido · SENTINEL RESET em todos os Sentinels
• 3. Verificação — Verificar de novo os números e o quorum
• 1. Diagnóstico — Ver as configurações atuais em cada Sentinel
• 2. Aplicação — Definir … como … em todos os Sentinels
• 1. Diagnóstico: memória, limite e eviction — Ver o uso de memória e o limite (INFO memory) · MEMORY DOCTOR e MEMORY STATS · Ver as configurações de memória
• 2. Opções de solução — Solução conforme a situação
• 1. Diagnóstico: chaves grandes e quentes — As maiores chaves por tipo (--bigkeys) · As maiores chaves por memória (--memkeys) · Chaves quentes (--hotkeys) · Examinar o tamanho e o tipo de uma chave
• 2. Solução — Apagar a chave grande com segurança (UNLINK)