Operação diária e cenários de falha do Elasticsearch (8.x / 9.x)

Não é uma instalação: runbook por cenários para administrar no dia a dia um cluster Elasticsearch 8.x / 9.x instalado e recuperá-lo quando quebrar. Saúde e allocation explain, solução de shards não alocados (disco, filtering, retry_failed, replica, em último caso stale/empty primary), disk watermark, bloqueio read_only_allow_delete, adição e remoção segura de nodes, reindex sem interrupção com alias, ILM e rollover, _shrink / _split, restauração de um único índice a partir de snapshot com novo nome. Se não souber o que fazer, comece pela verificação de saúde. Instalação de snapshot repository e SLM, hardening de segurança e upgrade de versão estão em guias Elasticsearch separados.

Topologia: Cluster Elasticsearch 8.x / 9.x (1–N nodes), com TLS e autenticação ativos

Cenários

• Saúde do cluster: status, nodes, shards não alocados, disco — Somente leitura: green/yellow/red, lista de nodes, shards não alocados (UNASSIGNED) e o motivo (allocation explain), uso de disco e watermark, tarefas pendentes. Se não tiver certeza do que fazer, comece por aqui.
• Resolver shard não alocado (UNASSIGNED) (conforme o explain) — Cluster yellow ou red e shards que não são alocados: conforme o motivo do allocation explain, disco, allocation filtering, limite de tentativas (retry_failed), número de replicas ou, em último caso, primary a partir de uma cópia antiga.
• Ver / alterar o disk watermark — Shards estão sendo movidos ou não são alocados por causa da ocupação do disco; os limites de watermark (low / high / flood_stage) serão alterados de forma temporária ou permanente, ou voltarão ao padrão.
• Índice ficou somente leitura: remover o bloqueio read_only_allow_delete — As escritas são recusadas com 'FORBIDDEN/12/index read-only / allow delete (api)' ou 'TOO_MANY_REQUESTS/12/disk usage exceeded flood-stage watermark': primeiro libera-se espaço em disco, depois remove-se o bloqueio.
• Adicionar node ao cluster (enrollment token) — É preciso mais capacidade: o Elasticsearch foi instalado em um novo servidor, que entra no cluster com enrollment token; os shards se rebalanceiam sozinhos. Sem indisponibilidade.
• Remover node com segurança (exclude, esvaziar, desligar) — Um node vai ser aposentado ou ter o hardware trocado: com allocation exclude os shards são movidos para os outros nodes, confirma-se que ele esvaziou, se for master-eligible recebe voting exclusion, e então é desligado.
• Reindex: novo índice para mudança de mapping/configuração e migração sem interrupção com alias — O tipo de um campo do mapping, o analyzer ou o número de shards vai mudar: cria-se um novo índice, os dados são copiados com _reindex e o alias é apontado de forma atômica para o novo índice.
• Configurar / resolver problemas de index lifecycle (ILM) e rollover — Índices de log/séries temporais crescem ou não são apagados: configura-se a política ILM (rollover + delete), o index template e o índice inicial (write alias); com explain vê-se por que a política existente não avança.
• Corrigir o número de shards: _shrink (reduzir) / _split (aumentar) — O número de shards do índice foi mal escolhido: shards muito pequenos (oversharding) são unidos com _shrink, shards muito grandes são divididos com _split; a migração é feita com alias.
• Restaurar um único índice de snapshot com novo nome — Um índice foi apagado ou corrompido: do snapshot repository restaura-se apenas esse índice, com novo nome (rename), sem tocar no índice em produção; após a validação, ele entra em uso com alias.

Antes de começar

• Em … (…) há acesso root, curl e o certificado da CA HTTP do cluster (…); você tem a senha do usuário elastic (ou de um usuário com manage + privilégios de índice). As chamadas de API são feitas por HTTPS a este node.
• Registro de mudança aberto, equipe da aplicação informada. Movimentação de shards, reindex e resize geram carga de disco, rede e CPU; faça fora do horário de pico. Antes de passos irreversíveis (exclusão, stale/empty primary) deve haver um snapshot atual: Snapshot.
• O novo servidor está pronto com as fases de preparação do sistema operacional e instalação do software do guia de instalação do cluster: mesma versão do Elasticsearch, vm.max_map_count, heap, swap desativado, 9200/9300 liberadas no firewall; o serviço nunca foi iniciado (o enrollment só pode ser feito antes da primeira inicialização).

Fases do guia

• Acesso à API — Arquivo temporário de credenciais para a API
• Estado: saúde, nodes, shards, disco (somente leitura) — Saúde do cluster, nodes e shards não alocados · Consultar o motivo do shard não alocado (allocation explain) · Uso de disco e watermark · Tarefas pendentes e interpretação do resultado
• 1. Diagnóstico: por que o shard não é alocado? — Shards do índice e a decisão do explain
• 2. Aplicação — Tentar de novo as alocações com falha (retry_failed) · Ajustar o número de replicas ao número de nodes · Remover o allocation filtering · Ir para o bloqueio de disco · Alocar primary a partir da cópia antiga (allocate_stale_primary) · Alocar primary vazia (allocate_empty_primary)
• 3. Verificação — Acompanhar o início dos shards
• 1. Diagnóstico — Uso de disco e limites atuais
• 2. Aplicação — …Alterar os limites…Voltar os limites ao padrão…
• 1. Diagnóstico: bloqueio e disco — Ver os índices bloqueados e o disco · Opções para liberar disco
• 2. Aplicação — Remover o bloqueio
• 3. Verificação — Testar se a escrita funciona
• 1. Diagnóstico — Ver o estado do cluster
• 2. Aplicação: enrollment e entrada no cluster — Gerar o enrollment token do node · Configurar o novo node com o token · Verificar node.name e a configuração de rede · Iniciar o serviço
• 3. Verificação — Confirmar que o node entrou e recebe shards
• 1. Diagnóstico — Ver os shards e o papel do node
• 2. Aplicação: esvaziar e desligar — Mover os shards do node (allocation exclude) · Aguardar o node esvaziar · Retirar o node master-eligible da votação · Parar o node · Remover o exclude e a voting exclusion
• 3. Verificação — Validar a saúde do cluster
• 1. Diagnóstico e preparação — Ver o índice de origem e o alias · Criar o novo índice com o novo mapping/configurações
• 2. Aplicação: copiar e apontar o alias — Copiar os dados (_reindex, em segundo plano) · Acompanhar a tarefa · Preparar o novo índice e comparar as contagens · Apontar o alias para o novo índice de forma atômica
• 3. Depois — Fechar o índice antigo (apagar depois)
• 1. Política ILM, template e índice inicial — Criar a política ILM · Criar o index template · Criar o índice inicial com o alias de escrita
• Diagnóstico: por que o ILM não avança? — Ver o status do ILM e os índices com erro · Tentar de novo o passo com erro
• Rollover manual — Fazer rollover do alias imediatamente
• 1. Diagnóstico — Número de shards e tamanho do índice
• 3. Aplicação — …Shrink…Split…: … → … (… shards) · Apontar o alias para o novo índice
• 4. Depois — Fechar o índice de origem (apagar depois)
• 1. Diagnóstico: o índice está no snapshot? — Ver os snapshots e o índice contido neles
• 2. Aplicação: restaurar com novo nome — Restaurar o índice com o nome …… · Validar e colocar em uso
• Limpeza — Apagar o arquivo de credenciais