Solução de Problemas de Saúde do Cluster Elasticsearch: Um Guia Passo a Passo

Um cluster Elasticsearch amarelo ou vermelho não é um estado misterioso. Geralmente significa que o Elasticsearch não consegue colocar um ou mais shards onde deseja. O trabalho é descobrir qual shard está travado, por que a alocação está bloqueada e se a correção correta é esperar, liberar recursos, trazer um nó de volta, restaurar de um snapshot ou aceitar deliberadamente a perda de dados.

Trato a saúde do cluster como um sinal de triagem, não como o diagnóstico em si. Verde significa que todos os shards primários e réplicas estão atribuídos. Amarelo significa que todos os shards primários estão atribuídos, então pesquisas e gravações geralmente podem continuar, mas pelo menos uma réplica está faltando. Vermelho significa que pelo menos um shard primário não está atribuído, então parte de pelo menos um índice está indisponível. Vermelho é o que pode quebrar leituras ou gravações de aplicativos imediatamente.

Comece obtendo a visão simples:

GET /_cluster/health?pretty
GET /_cat/health?v

Observe status, number_of_nodes, active_primary_shards, unassigned_shards, initializing_shards e relocating_shards. Se você vir shards inicializando ou realocando após uma reinicialização do nó, o cluster pode já estar se recuperando. Não comece a alterar as configurações de alocação antes de saber se o Elasticsearch está simplesmente trabalhando.

Em seguida, liste os shards não atribuídos:

GET /_cat/shards?v&h=index,shard,prirep,state,node,unassigned.reason&s=state,index,shard

A coluna prirep é importante. Um shard p é primário. Um cluster vermelho sempre tem pelo menos um primário não atribuído. Um shard r é uma réplica. Um cluster amarelo geralmente tem apenas réplicas não atribuídas.

A API mais útil nesta situação é a explicação de alocação:

GET /_cluster/allocation/explain?pretty

Para um shard específico, seja explícito:

GET /_cluster/allocation/explain?pretty
{
  "index": "logs-2026.05.24",
  "shard": 0,
  "primary": false
}

Leia a resposta can_allocate e as decisões no nível do nó. O Elasticsearch geralmente dirá exatamente qual regra bloqueou a alocação: watermarks de disco, filtros de alocação, regras de mesmo shard, alocação atrasada após a saída de um nó, dados primários ausentes, versões incompatíveis ou uma incompatibilidade de função do nó.

Quando o Cluster Está Amarelo

Amarelo é comum em clusters pequenos. O caso clássico é um cluster de desenvolvimento de um nó com number_of_replicas: 1. O Elasticsearch não pode colocar uma réplica no mesmo nó que seu primário, então a réplica permanece não atribuída para sempre. Isso não é uma emergência em um ambiente de laptop. É uma incompatibilidade de configuração.

Verifique a contagem de réplicas:

GET /my-index/_settings?filter_path=*.settings.index.number_of_replicas

Para um cluster de produção de nó único, defina réplicas como zero:

PUT /my-index/_settings
{
  "index": {
    "number_of_replicas": 0
  }
}

Para produção, não esconda o problema reduzindo réplicas, a menos que você esteja intencionalmente aceitando menos redundância. Se o índice deve ter uma réplica, você precisa de pelo menos dois nós de dados elegíveis. Se tiver duas réplicas, você precisa de pelo menos três nós de dados elegíveis. A hierarquização pode tornar isso menos óbvio: uma réplica de índice warm não pode ser alocada em um nó somente hot se as regras de alocação exigirem nós warm.

A pressão do disco é a próxima causa comum de amarelo. Verifique o uso do disco do nó:

GET /_cat/allocation?v
GET /_cat/nodes?v&h=name,roles,disk.used_percent,disk.avail,heap.percent,cpu,load_1m

O Elasticsearch usa watermarks de disco para evitar encher nós. Os padrões variam de acordo com a versão e configuração, então inspecione as configurações reais do seu cluster:

GET /_cluster/settings?include_defaults=true&flat_settings=true&filter_path=**cluster.routing.allocation.disk.watermark**

Se um nó estiver acima do watermark alto, o Elasticsearch evitará alocar mais shards lá. Se atingir o watermark de flood-stage, o Elasticsearch pode colocar os índices afetados em um estado de bloqueio de gravação para proteger o nó. A correção duradoura é excluir dados antigos, mover dados para mais nós, aumentar o disco, reduzir contagens de shards superdimensionados ou ajustar a retenção do ILM. Aumentar temporariamente os watermarks pode ganhar tempo, mas não deve ser seu primeiro movimento.

Uma sequência prática de limpeza se parece com isso:

GET /_cat/indices?v&s=store.size:desc
GET /_cat/shards?v&s=store:desc

Encontre índices grandes e antigos, verifique as expectativas de retenção com a equipe proprietária, faça snapshot se necessário e exclua apenas os dados que você tem permissão para remover:

DELETE /old-logs-2025.12.*

Após liberar espaço, a alocação pode ser retomada automaticamente. Se não, execute novamente a explicação de alocação. A razão antiga ainda pode estar armazenada em cache na sua cabeça, mas o cluster agora pode estar bloqueado por uma regra diferente.

A filtragem de alocação é outra causa frequente de amarelo, especialmente após migrações de hardware. Alguém pode ter definido um índice para exigir um atributo de nó que não existe mais:

GET /my-index/_settings?flat_settings=true&filter_path=*.settings.index.routing.allocation*
GET /_cluster/settings?flat_settings=true&filter_path=**routing.allocation**

Se a regra estiver errada, remova-a ou atualize-a:

PUT /my-index/_settings
{
  "index.routing.allocation.require.box_type": null,
  "index.routing.allocation.include._name": null,
  "index.routing.allocation.exclude._name": null
}

Use as chaves exatas que suas configurações mostram. Não cole uma reinicialização ampla na produção sem lê-la; as regras de alocação às vezes estão lá por um bom motivo, como manter certos dados em uma camada controlada por conformidade.

Quando o Cluster Está Vermelho

Vermelho merece mãos mais lentas e melhores anotações. A primeira pergunta é se o shard primário ausente tem uma cópia recuperável em algum lugar.

Liste os shards primários não atribuídos:

GET /_cat/shards?v&h=index,shard,prirep,state,unassigned.reason | grep ' p UNASSIGNED'

Em seguida, verifique quais nós estão presentes:

GET /_cat/nodes?v&h=name,ip,roles,master,uptime,heap.percent,disk.avail

Se um nó estiver faltando, seu melhor caminho de recuperação geralmente é trazer esse nó de volta. Verifique o serviço, montagem do disco, rede do host, certificados e logs no nó ausente. Um nó que perdeu o acesso ao seu caminho de dados pode iniciar como um nó vazio diferente, o que não ajuda a recuperar o shard primário.

No nó Elasticsearch, os logs geralmente mostram a falha real mais cedo do que as APIs. Procure mensagens sobre falhas de bloqueio de shard, arquivos de índice corrompidos, descoberta do master, erros de handshake TLS, sistemas de arquivos somente leitura do disco ou alterações de função do nó. Uma falha comum no mundo real é a reinicialização de um nó após um disco ser remontado em um caminho diferente. O Elasticsearch sobe, mas o caminho de dados está vazio, então o cluster ainda não tem a cópia do shard de que precisa.

Execute a explicação de alocação para o primário:

GET /_cluster/allocation/explain?pretty
{
  "index": "orders-2026.05.24",
  "shard": 2,
  "primary": true
}

Se a explicação disser que nenhuma cópia de shard válida pode ser encontrada, pare e verifique os snapshots antes de fazer qualquer coisa destrutiva:

GET /_snapshot/_all
GET /_snapshot/my-repository/_all?verbose=false

Restaurar um snapshot geralmente é mais seguro do que alocar um primário vazio. Um primário vazio cria um novo shard em branco para esse ID de shard. Não é uma operação de reparo. Diz ao Elasticsearch: "Eu aceito que os dados antigos para este shard se foram."

O comando de último recurso se parece com isso:

POST /_cluster/reroute
{
  "commands": [
    {
      "allocate_empty_primary": {
        "index": "orders-2026.05.24",
        "shard": 2,
        "node": "es-data-03",
        "accept_data_loss": true
      }
    }
  ]
}

Use-o somente depois de confirmar que não há cópia de nó utilizável e nenhum snapshot que você possa restaurar. Em um incidente, anote quem aprovou essa escolha e qual índice e shard foram afetados. A depuração futura é muito mais fácil quando a decisão de perda de dados é explícita.

Casos Que Parecem Problemas de Alocação, Mas São Realmente Problemas de Cluster

Às vezes, os shards não são atribuídos porque o cluster não consegue manter uma associação estável. Se os nós elegíveis para master não conseguem se comunicar entre si, o master eleito pode mudar repetidamente, e a alocação será agitada ou pausada. Verifique a estabilidade do master:

GET /_cat/master?v
GET /_cat/nodes?v&h=name,roles,master,ip

Se o master mudar com frequência, inspecione a confiabilidade da rede, DNS, certificados de nó e configurações de descoberta. Para clusters Elasticsearch modernos, cluster.initial_master_nodes é para a inicialização inicial do cluster, não uma configuração para deixar como uma muleta de descoberta para sempre. discovery.seed_hosts deve apontar para hosts de seed apropriados, e todos os nós devem usar o mesmo nome de cluster e configurações de segurança compatíveis.

A alta pressão da JVM também pode causar sintomas de alocação. Um nó de dados preso em longas pausas de coleta de lixo pode sair e reentrar no cluster do ponto de vista do master. Isso pode criar shards não atribuídos, mesmo que a máquina nunca tenha travado completamente.

Verifique o heap e os logs de coleta de lixo:

GET /_cat/nodes?v&h=name,heap.percent,ram.percent,cpu,load_1m,node.role
GET /_nodes/stats/jvm?filter_path=nodes.*.jvm.mem,nodes.*.jvm.gc

Se o heap estiver consistentemente alto, não aumente o heap cegamente. O Elasticsearch geralmente tem melhor desempenho quando o heap deixa memória suficiente para o cache do sistema de arquivos. Procure agregações superdimensionadas, uso intenso de fielddata, muitos shards, indexação agressiva ou consultas que precisam de mapeamentos melhores.

A contagem de shards pode ser a causa silenciosa por trás de muitos problemas de saúde. Um cluster com muitos shards minúsculos gasta muito esforço rastreando metadados e movendo shards. Use:

GET /_cat/indices?v&h=index,pri,rep,docs.count,store.size,pri.store.size&s=pri:desc
GET /_cluster/stats?filter_path=indices.shards,indices.count,nodes.count

Se cada índice de log diário tem muitos shards primários, mas poucos dados, corrija o modelo de índice para índices futuros. Em seguida, considere planos de shrink, rollover ou reindex para dados existentes.

Uma Ordem Prática de Triagem

Quando alguém diz "Elasticsearch está vermelho", eu uso esta ordem:

1. Confirme a saúde com _cluster/health.
2. Liste os shards não atribuídos com _cat/shards.
3. Separe as falhas primárias das falhas de réplica.
4. Execute _cluster/allocation/explain em um shard representativo.
5. Verifique se todos os nós esperados estão presentes.
6. Verifique os watermarks de disco e as regras de alocação.
7. Para primários vermelhos, tente recuperar o nó ausente ou restaurar de um snapshot antes de considerar a alocação de primário vazio.
8. Depois que o cluster ficar verde, encontre a causa que o tornou não saudável em primeiro lugar.

Essa última etapa é importante. Um cluster pode ficar verde depois que você adiciona disco, reinicia um nó ou reduz réplicas, mas o mesmo incidente retornará se a retenção do ILM estiver errada, as contagens de shards forem muito altas, os nós forem subdimensionados ou um processo de implantação continuar alterando os atributos do nó.

A solução de problemas de saúde do cluster é menos sobre memorizar um comando mágico e mais sobre se recusar a adivinhar. O Elasticsearch expõe a decisão de alocação. Leia-a, verifique-a em relação às configurações do nó e do índice e escolha a menor correção que corresponda ao bloqueador real.

Depois Que o Cluster Está Verde Novamente

Não feche o incidente só porque a cor mudou. Verde significa apenas que os shards estão atribuídos agora. Não prova que o cluster é saudável o suficiente para o próximo pico de tráfego, ciclo de crescimento de disco ou reinicialização de nó. Gosto de capturar uma breve nota pós-ação enquanto os detalhes ainda estão frescos: quais índices foram afetados, quais nós estavam envolvidos, qual regra de alocação bloqueou a recuperação e qual comando ou mudança de infraestrutura corrigiu.

Verifique se a correção criou um novo risco. Se você reduziu réplicas para transformar amarelo em verde, registre que o índice agora tem menos redundância. Se você aumentou os watermarks de disco, adicione um lembrete para reduzi-los após a capacidade ser adicionada. Se você restaurou um snapshot, verifique se o índice restaurado tem os aliases e as configurações de gravação esperados antes que os aplicativos retomem as gravações normais.

Algumas verificações rápidas ajudam a capturar trabalhos inacabados:

GET /_cat/recovery?v&active_only=true
GET /_cat/pending_tasks?v
GET /_cat/aliases?v
GET /_cluster/health?wait_for_status=green&timeout=30s

pending_tasks não deve crescer para sempre. A recuperação deve eventualmente esvaziar. Aliases são importantes porque restaurar um índice com um nome diferente pode deixar o aplicativo escrevendo no alvo antigo quebrado ou lendo apenas parte dos dados pretendidos.

Também verifique os bloqueios de gravação após incidentes de disco:

GET /*/_settings?filter_path=*.settings.index.blocks*

Se o Elasticsearch definiu um bloqueio de flood-stage, remova-o somente após a pressão do disco ser corrigida:

PUT /my-index/_settings
{
  "index.blocks.read_only_allow_delete": null
}

O trabalho de prevenção mais útil geralmente é chato: snapshots funcionais, restaurações testadas, retenção ILM realista, espaço em disco suficiente e contagens de shards que correspondem ao tamanho do cluster. Um cluster com snapshots confiáveis e dimensionamento de shards sensato é muito mais fácil de recuperar do que um cluster com comandos de emergência inteligentes e nenhum caminho de restauração.

O Que Não Fazer Durante Incidentes de Saúde

Não reinicie todos os nós de uma vez. É tentador quando o cluster parece não saudável, mas uma abordagem contínua e observada é mais segura. Reiniciar nós saudáveis pode remover cópias de shards que o Elasticsearch precisa para a recuperação. Se você precisar reiniciar, faça um nó de cada vez e aguarde o cluster se estabilizar entre as etapas.

Não desabilite a alocação e esqueça disso. Alterações temporárias de alocação são comuns durante a manutenção, mas uma configuração esquecida pode deixar réplicas não atribuídas muito depois do término da janela de manutenção. Sempre verifique as configurações persistentes e transitórias:

GET /_cluster/settings?flat_settings=true&include_defaults=false

Não exclua índices com base apenas no tamanho. Índices grandes podem ser críticos para os negócios. Índices pequenos podem ser seguros para remover. Vincule a limpeza à política de retenção, snapshots e propriedade do aplicativo. Em uma interrupção real, a limpeza segura mais rápida geralmente é excluir índices de log ou métricas conhecidos como expirados, não adivinhar a partir de uma lista classificada por tamanho.

Não presuma que Kibana e Elasticsearch usam o mesmo idioma para o problema. Kibana pode mostrar um status vermelho amplo, enquanto as APIs do Elasticsearch mostram o shard não atribuído preciso. Use a interface do usuário para visibilidade, mas use as APIs para a decisão.