Solução de Problemas Comuns de Falhas na Alocação de Shards no Elasticsearch

Falhas na alocação de shards são onde o Elasticsearch deixa de ser abstrato. A saúde do cluster fica amarela ou vermelha, as buscas começam a retornar resultados parciais, a indexação fica mais lenta e a equipe precisa descobrir se o problema é de disco, um nó ausente, uma regra de alocação ruim ou dados de shard corrompidos.

O erro que vejo com mais frequência é tratar todo shard não atribuído da mesma forma. Um shard de réplica atrasado após uma reinicialização planejada não é a mesma emergência que um shard primário não atribuído para o índice principal de pedidos. Comece descobrindo qual shard não está atribuído, se é primário ou réplica, e o que o Elasticsearch diz sobre a decisão de alocação.

Leia o sinal de saúde corretamente

Comece com a saúde do cluster:

GET /_cluster/health?pretty

Os campos importantes são status, active_primary_shards, active_shards, relocating_shards, initializing_shards, unassigned_shards e delayed_unassigned_shards.

Amarelo significa que todos os shards primários estão atribuídos, mas uma ou mais réplicas não estão. Seus dados ainda devem estar disponíveis, mas a redundância é reduzida.

Vermelho significa que um ou mais shards primários não estão atribuídos. Os dados nesses shards ficam indisponíveis, a menos que o Elasticsearch consiga promover uma réplica, recuperar o nó que continha o shard ou restaurar a partir de um snapshot.

Se relocating_shards ou initializing_shards for diferente de zero, o cluster pode já estar se recuperando. Não interrompa uma recuperação normal só porque a cor está temporariamente amarela.

Liste os shards não atribuídos

Use _cat/shards para ver o problema exato:

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

Procure por UNASSIGNED. A coluna prirep informa se o shard é primário (p) ou réplica (r). A coluna unassigned.reason fornece um motivo curto, como NODE_LEFT, INDEX_CREATED, CLUSTER_RECOVERED ou ALLOCATION_FAILED.

Para um cluster grande, restrinja:

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

Depois de obter o índice, o número do shard e o sinalizador primário/réplica, peça ao Elasticsearch a explicação real.

Use a API de explicação de alocação

Para qualquer shard atualmente não atribuído:

GET /_cluster/allocation/explain
{}

Para um shard específico:

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

Leia can_allocate, allocate_explanation, unassigned_info e node_allocation_decisions. As decisões dos nós são especialmente úteis porque mostram por que cada nó foi rejeitado. Decisores comuns incluem limites de disco, regras de mesmo shard, filtros de alocação, regras de awareness e limites de total de shards por nó.

Se a saída disser no_valid_shard_copy para um primário, trate com seriedade. O Elasticsearch não vê atualmente uma cópia utilizável desse shard primário.

Causa 1: não há nós adequados suficientes

Um cluster simples de nó único com uma réplica ficará amarelo para sempre. O Elasticsearch não colocará uma réplica no mesmo nó que seu primário. Um cluster de três nós com um índice configurado para duas réplicas precisa de três nós de dados adequados. Se a awareness de alocação disser que as cópias devem ser distribuídas entre zonas, você também precisará de nós suficientes nas zonas necessárias.

Verifique as configurações de réplica:

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

Se este for um ambiente de laboratório ou temporário, reduza as réplicas:

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

Para produção, a melhor resposta geralmente é adicionar nós de dados adequados ou ajustar um número de réplicas irrealista. Reduzir réplicas remove a redundância.

Causa 2: watermarks de disco

A pressão no disco é um dos bloqueadores de alocação mais comuns. O Elasticsearch usa watermarks de disco para evitar encher os nós. Quando os nós ultrapassam os limites, o Elasticsearch pode parar de atribuir shards a eles e pode mover shards para longe.

Verifique a alocação e o uso do disco:

GET /_cat/allocation?v
GET /_cat/nodes?v&h=name,ip,disk.used_percent,disk.avail,heap.percent,ram.percent,node.role

A saída da explicação de alocação pode dizer que um nó está acima do watermark de disco baixo ou alto. Se um índice atingiu condições de estágio de inundação, o Elasticsearch também pode definir um bloqueio de gravação nos índices afetados.

Boas correções são correções de capacidade: exclua índices antigos após confirmar snapshots, adicione disco, adicione nós de dados, mova dados para outra camada ou reduza a retenção por meio do Gerenciamento do Ciclo de Vida do Índice.

Alterar watermarks pode ser razoável em uma emergência controlada, mas não é um plano de capacidade. Se todos os nós de dados estão quase cheios, aumentar os limites apenas permite que o cluster opere mais perto da falha.

Depois de liberar espaço de um evento de estágio de inundação, verifique se há um bloqueio somente leitura:

GET /my-index/_settings?filter_path=*.settings.index.blocks.write,*.settings.index.blocks.read_only_allow_delete

Remova o bloqueio somente depois que a pressão no disco for resolvida:

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

Causa 3: alocação desabilitada após manutenção

As equipes geralmente desabilitam a alocação durante a manutenção contínua e depois esquecem de reativá-la.

Verifique as configurações do cluster:

GET /_cluster/settings?include_defaults=true&pretty

Procure por cluster.routing.allocation.enable. Os valores incluem all, primaries, new_primaries e none. Se for none, as réplicas e possivelmente outros movimentos de shard não serão alocados normalmente.

Reative a alocação:

PUT /_cluster/settings
{
  "persistent": {
    "cluster.routing.allocation.enable": "all"
  }
}

Verifique também as configurações transient. Uma configuração de manutenção transitória ainda pode afetar o cluster mesmo se a seção persistente parecer correta.

Causa 4: filtros de alocação restritivos

Filtros no nível do índice podem fixar um índice em determinados nós:

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

Filtros no nível do cluster podem excluir nós da alocação:

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

Os atributos do nó também importam:

GET /_cat/nodeattrs?v

Uma falha típica se parece com isso: um índice requer box_type: hot, mas os nós hot foram substituídos e os novos nós não têm node.attr.box_type: hot. O Elasticsearch está seguindo a regra exatamente; a regra agora está errada.

Para remover filtros de índice excessivamente restritivos:

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

Use os nomes de configuração exatos presentes em seu índice. Não remova cegamente as regras de alocação se elas codificarem requisitos reais de zona ou camada.

Causa 5: alocação atrasada após a saída de um nó

Quando um nó sai, o Elasticsearch pode atrasar a alocação de shards de réplica porque o nó pode voltar rapidamente. Isso evita copiar shards grandes pela rede durante uma reinicialização normal.

Verifique shards atrasados:

GET /_cluster/health?pretty

Se delayed_unassigned_shards for maior que zero e o nó deve retornar, esperar pode ser a melhor ação. Você também pode inspecionar as configurações do índice:

GET /my-index/_settings?filter_path=*.settings.index.unassigned.node_left.delayed_timeout

O padrão é geralmente um minuto, mas sempre verifique seu cluster e versão. Algumas equipes aumentam isso para reinicializações contínuas planejadas de shards grandes. Não torne o tempo tão longo que falhas reais deixem as réplicas ausentes por um período desconfortável.

Causa 6: muitos shards em um nó

index.routing.allocation.total_shards_per_node pode limitar quantos shards de um índice podem residir no mesmo nó. Limites de shard no nível do cluster também podem ser aplicados. Essas configurações são úteis, mas podem bloquear a alocação em clusters pequenos.

Verifique as configurações do índice:

GET /my-index/_settings?filter_path=*.settings.index.routing.allocation.total_shards_per_node

Se você tem cinco shards primários, uma réplica, dois nós de dados e um limite baixo por nó, o Elasticsearch pode não ter um posicionamento legal. Corrija o limite, adicione nós ou redesenhe a contagem de shards.

Causa 7: nenhuma cópia válida de um primário

Este é o caso assustador. A explicação de alocação pode relatar que não há uma cópia de shard válida para um primário. Talvez o único nó com o primário tenha sumido. Talvez o disco tenha falhado. Talvez os dados do shard estejam corrompidos.

Primeiro, tente recuperar o nó ausente se ele deve retornar. Verifique os logs do sistema, logs do Elasticsearch, saúde do disco e conectividade de rede. Se existir uma réplica válida, o Elasticsearch deve promovê-la normalmente.

Se não existir cópia válida, restaure a partir de um snapshot:

POST /_snapshot/my_repository/snapshot_name/_restore
{
  "indices": "affected-index"
}

Se os dados puderem ser reconstruídos a partir de um sistema de origem e você aceitar perder o conteúdo do shard, allocate_empty_primary está disponível, mas é uma operação de perda de dados:

POST /_cluster/reroute
{
  "commands": [
    {
      "allocate_empty_primary": {
        "index": "affected-index",
        "shard": 0,
        "node": "target-node",
        "accept_data_loss": true
      }
    }
  ]
}

Não use isso para "deixar o cluster verde" a menos que você tenha decidido conscientemente que os dados ausentes se foram ou são reconstruíveis.

Acompanhe a recuperação

Após fazer uma alteração, acompanhe o progresso:

GET /_cat/recovery?v&active_only=true
GET /_cat/shards?v&h=index,shard,prirep,state,node,unassigned.reason
GET /_cluster/health?pretty

Shards grandes levam tempo. Se as contagens de bytes estão se movendo em _cat/recovery, o cluster está funcionando. Se nada mudar, verifique a explicação de alocação novamente. A decisão do Elasticsearch pode ter mudado após sua primeira correção, revelando o próximo bloqueador.

Prevenção que realmente ajuda

Monitore o disco antes que os watermarks sejam atingidos. Alerte sobre tendências, não apenas discos cheios.

Use ILM ou data streams para logs e métricas para que a retenção seja automática.

Mantenha os snapshots atualizados e teste as restaurações. Um snapshot que você nunca restaurou é apenas uma esperança.

Mantenha os tamanhos e contagens de shards razoáveis. Muitos shards minúsculos tornam a alocação e a recuperação mais lentas do que o volume de dados sugere.

Documente os filtros de alocação e atributos dos nós. Seis meses depois, alguém substituirá um nó e esquecerá o atributo que tornou um índice alocável.

Trate o amarelo como um aviso e o vermelho como um incidente. O amarelo pode ser aceitável durante a manutenção, mas não deve se tornar ruído de fundo. Vermelho significa que pelo menos um shard primário está indisponível, e quanto mais você espera, menos opções de recuperação fáceis você pode ter.

Uma lista de verificação de campo para incidentes

Quando a alocação de shard quebrar, colete as mesmas evidências todas as vezes. Isso impede que a equipe fique pulando entre teorias.

Execute:

GET /_cluster/health?pretty
GET /_cat/nodes?v&h=name,ip,roles,master,disk.used_percent,heap.percent,ram.percent
GET /_cat/shards?v&h=index,shard,prirep,state,node,unassigned.reason&s=state,index
GET /_cat/allocation?v
GET /_cat/recovery?v&active_only=true
GET /_cluster/settings?include_defaults=true&pretty

Em seguida, execute a explicação de alocação para um shard não atribuído representativo. Se houver muitos, agrupe-os por motivo. Dez réplicas não atribuídas bloqueadas por watermarks de disco são um problema. Três primários com no_valid_shard_copy são um problema diferente.

Anote se os dados afetados podem ser reconstruídos. Logs de uma fila upstream, métricas de agentes e índices de pesquisa derivados podem ser recuperáveis de sistemas de origem. Conteúdo criado pelo usuário ou registros de conformidade podem não ser. Os comandos de recuperação devem seguir essa realidade de negócios.

Quando esperar e quando agir

Espere quando a recuperação estiver progredindo ativamente, o nó ausente deve retornar em breve, ou a alocação atrasada está fazendo exatamente o que você configurou para fazer. Você pode verificar o progresso com _cat/recovery; contagens de bytes e arquivos em movimento são bons sinais.

Aja quando a explicação de alocação mostrar um bloqueador permanente: nenhum nó adequado, watermarks de disco em todos os nós, alocação desabilitada, atributos de nó ausentes ou nenhuma cópia de shard válida. Esperar não corrigirá uma regra que rejeita todos os nós.

Escale rapidamente quando shards primários não estiverem atribuídos para índices importantes. Falhas de réplica reduzem a segurança. Falhas primárias reduzem a disponibilidade.

Evite tornar a recuperação mais lenta

Recuperações grandes competem com pesquisa e indexação normais. Adicionar muitos nós de uma vez, reiniciar mais nós ou aumentar a simultaneidade de recuperação sem verificar a capacidade do disco e da rede pode tornar o cluster menos estável.

Se você ajustar as configurações de recuperação, faça isso deliberadamente e registre os valores originais. Configurações como recuperações simultâneas podem ajudar em alguns ambientes e prejudicar em outros. Uma recuperação mais rápida no papel pode sobrecarregar os discos e aumentar a latência da consulta o suficiente para que os usuários experimentem uma interrupção pior.

Fique de olho nos nós hot. A alocação pode tecnicamente ser bem-sucedida enquanto coloca muito trabalho em um nó devido a tamanhos de shard, regras de camada ou uso desigual do disco. Use _cat/allocation, estatísticas do nó e seu sistema de monitoramento para confirmar se o cluster está balanceado após a falha imediata ser resolvida.

Correções pós-ação

A maioria dos incidentes de alocação de shard tem uma história de prevenção. Incidentes de watermark de disco apontam para retenção, ILM ou planejamento de capacidade. Incidentes de filtro de alocação apontam para documentação de runbook ausente. Incidentes sem cópia válida apontam para snapshots e reprodução upstream. Recuperação lenta aponta para dimensionamento de shard e hardware.

Não feche o incidente só porque a saúde está verde. Remova alterações temporárias de réplica, restaure intervalos de atualização normais, reative a alocação se foi alterada, verifique snapshots e adicione o alerta que teria detectado o problema mais cedo.

Caso especial: índices fechados e ocultos

Às vezes, um índice não está alocando porque está fechado, oculto ou parte de um recurso do sistema que você não percebeu que estava tocando. Tenha cuidado com comandos de curinga amplos quando índices do sistema estiverem presentes. Em clusters modernos, segurança, Kibana, transformações e outros recursos da pilha podem manter seus próprios índices.

Use padrões estreitos e inclua índices ocultos apenas quando você pretende inspecioná-los. Se um índice do sistema tiver problemas de alocação, verifique os logs do componente da pilha relacionado, bem como o Elasticsearch. Por exemplo, um problema de índice de objetos salvos do Kibana pode aparecer como um problema de alocação de shard do Elasticsearch e como falhas de inicialização do Kibana.

A regra é a mesma que com dados do usuário: identifique o índice exato, entenda a quem ele pertence e escolha a correção. Não exclua ou force a alocação de um índice do sistema apenas para limpar um status de saúde vermelho, a menos que você entenda o impacto no nível do produto.