Solución de Problemas Comunes de Fallos en la Asignación de Fragmentos de Elasticsearch

Los fallos en la asignación de fragmentos son donde Elasticsearch deja de ser abstracto. La salud del clúster se vuelve amarilla o roja, las búsquedas comienzan a devolver resultados parciales, la indexación se ralentiza y el equipo tiene que determinar si el problema es de disco, un nodo faltante, una mala regla de asignación o datos de fragmento dañados.

El error que veo más a menudo es tratar todos los fragmentos no asignados de la misma manera. Un fragmento réplica retrasado después de un reinicio planificado no es la misma emergencia que un fragmento primario no asignado para el índice principal de pedidos. Comience por encontrar qué fragmento no está asignado, si es primario o réplica, y qué dice Elasticsearch sobre la decisión de asignación.

Lea la señal de salud correctamente

Comience con la salud del clúster:

GET /_cluster/health?pretty

Los campos importantes son status, active_primary_shards, active_shards, relocating_shards, initializing_shards, unassigned_shards y delayed_unassigned_shards.

Amarillo significa que todos los fragmentos primarios están asignados, pero una o más réplicas no lo están. Sus datos aún deberían estar disponibles, pero la redundancia está reducida.

Rojo significa que uno o más fragmentos primarios no están asignados. Los datos en esos fragmentos no están disponibles a menos que Elasticsearch pueda promover una réplica, recuperar el nodo que tenía el fragmento o restaurar desde una instantánea.

Si relocating_shards o initializing_shards no es cero, el clúster puede estar curándose. No interrumpa una recuperación normal solo porque el color sea temporalmente amarillo.

Liste los fragmentos no asignados

Use _cat/shards para ver el problema exacto:

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

Busque UNASSIGNED. La columna prirep le indica si el fragmento es primario (p) o réplica (r). La columna unassigned.reason da una razón corta como NODE_LEFT, INDEX_CREATED, CLUSTER_RECOVERED o ALLOCATION_FAILED.

Para un clúster grande, reduzca el alcance:

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

Una vez que tenga el índice, número de fragmento y bandera primario/réplica, pida a Elasticsearch la explicación real.

Use la API de explicación de asignación

Para cualquier fragmento actualmente no asignado:

GET /_cluster/allocation/explain
{}

Para un fragmento específico:

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

Lea can_allocate, allocate_explanation, unassigned_info y node_allocation_decisions. Las decisiones de nodo son especialmente útiles porque muestran por qué cada nodo fue rechazado. Los decisores comunes incluyen umbrales de disco, reglas de mismo fragmento, filtros de asignación, reglas de conciencia y límites de fragmentos totales por nodo.

Si la salida dice no_valid_shard_copy para un primario, tómelo en serio. Elasticsearch no ve actualmente una copia utilizable de ese fragmento primario.

Causa 1: no hay suficientes nodos adecuados

Un clúster simple de un solo nodo con una réplica estará amarillo para siempre. Elasticsearch no colocará una réplica en el mismo nodo que su primario. Un clúster de tres nodos con un índice configurado para dos réplicas necesita tres nodos de datos adecuados. Si la conciencia de asignación dice que las copias deben distribuirse entre zonas, también necesita suficientes nodos en las zonas requeridas.

Verifique la configuración de réplicas:

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

Si este es un entorno de laboratorio o temporal, reduzca las réplicas:

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

Para producción, la mejor respuesta suele ser agregar nodos de datos adecuados o ajustar un número de réplicas poco realista. Reducir las réplicas elimina la redundancia.

Causa 2: marcas de agua de disco

La presión de disco es uno de los bloqueadores de asignación más comunes. Elasticsearch usa marcas de agua de disco para evitar llenar nodos. Cuando los nodos cruzan umbrales, Elasticsearch puede dejar de asignar fragmentos a ellos y puede mover fragmentos fuera.

Verifique la asignación y el uso de disco:

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

La salida de explicación de asignación puede decir que un nodo está por encima de la marca de agua baja o alta de disco. Si un índice ha alcanzado condiciones de etapa de inundación, Elasticsearch también puede establecer un bloque de escritura en los índices afectados.

Las buenas soluciones son arreglos de capacidad: eliminar índices antiguos después de confirmar instantáneas, agregar disco, agregar nodos de datos, mover datos a otro nivel o acortar la retención a través de Index Lifecycle Management.

Cambiar las marcas de agua puede ser razonable en una emergencia controlada, pero no es un plan de capacidad. Si cada nodo de datos está casi lleno, aumentar los umbrales solo permite que el clúster funcione más cerca del fallo.

Después de liberar espacio de un evento de etapa de inundación, verifique si hay un bloque de solo lectura:

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

Elimine el bloque solo después de que la presión de disco esté resuelta:

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

Causa 3: asignación deshabilitada después del mantenimiento

Los equipos a menudo deshabilitan la asignación durante el mantenimiento continuo y luego olvidan volver a activarla.

Verifique la configuración del clúster:

GET /_cluster/settings?include_defaults=true&pretty

Busque cluster.routing.allocation.enable. Los valores incluyen all, primaries, new_primaries y none. Si es none, las réplicas y posiblemente otros movimientos de fragmentos no se asignarán normalmente.

Vuelva a habilitar la asignación:

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

También verifique la configuración transient. Una configuración transitoria de mantenimiento aún puede afectar al clúster incluso si la sección persistente se ve bien.

Causa 4: filtros de asignación restrictivos

Los filtros a nivel de índice pueden fijar un índice a ciertos nodos:

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

Los filtros a nivel de clúster pueden excluir nodos de la asignación:

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

Los atributos de nodo también importan:

GET /_cat/nodeattrs?v

Un fallo típico se ve así: un índice requiere box_type: hot, pero los nodos calientes fueron reemplazados y los nuevos nodos no tienen node.attr.box_type: hot. Elasticsearch está siguiendo la regla exactamente; la regla ahora está equivocada.

Para eliminar filtros de índice demasiado restrictivos:

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 los nombres de configuración exactos presentes en su índice. No elimine las reglas de asignación a ciegas si codifican requisitos reales de zona o nivel.

Causa 5: asignación retrasada después de que un nodo se va

Cuando un nodo se va, Elasticsearch puede retrasar la asignación de fragmentos réplica porque el nodo podría volver rápidamente. Esto evita copiar fragmentos grandes a través de la red durante un reinicio normal.

Verifique fragmentos retrasados:

GET /_cluster/health?pretty

Si delayed_unassigned_shards es mayor que cero y se espera que el nodo vuelva, esperar puede ser la mejor acción. También puede inspeccionar la configuración del índice:

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

El valor predeterminado suele ser un minuto, pero siempre verifique su clúster y versión. Algunos equipos lo aumentan para reinicios continuos planificados de fragmentos grandes. No lo haga tan largo que los fallos reales dejen réplicas faltantes por un tiempo incómodo.

Causa 6: demasiados fragmentos en un nodo

index.routing.allocation.total_shards_per_node puede limitar cuántos fragmentos de un índice pueden vivir en el mismo nodo. Los límites de fragmentos a nivel de clúster también pueden aplicarse. Estas configuraciones son útiles, pero pueden bloquear la asignación en clústeres pequeños.

Verifique la configuración del índice:

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

Si tiene cinco fragmentos primarios, una réplica, dos nodos de datos y un límite bajo por nodo, Elasticsearch puede no tener una ubicación legal. Arregle el límite, agregue nodos o rediseñe el número de fragmentos.

Causa 7: ninguna copia válida de un primario

Este es el caso aterrador. La explicación de asignación puede informar que no hay una copia de fragmento válida para un primario. Quizás el único nodo con el primario se ha ido. Quizás el disco falló. Quizás los datos del fragmento están corruptos.

Primero, intente recuperar el nodo faltante si se espera que vuelva. Verifique los registros del sistema, los registros de Elasticsearch, la salud del disco y la conectividad de red. Si existe una réplica válida, Elasticsearch normalmente debería promoverla.

Si no existe una copia válida, restaure desde una instantánea:

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

Si los datos pueden reconstruirse desde un sistema fuente y acepta perder el contenido del fragmento, allocate_empty_primary está disponible, pero es una operación de pérdida de datos:

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

No use esto para "poner el clúster verde" a menos que haya decidido conscientemente que los datos faltantes se han ido o son reconstruibles.

Observe la recuperación

Después de hacer un cambio, observe el progreso:

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

Los fragmentos grandes toman tiempo. Si los recuentos de bytes se mueven en _cat/recovery, el clúster está funcionando. Si nada cambia, verifique la explicación de asignación nuevamente. La decisión de Elasticsearch puede haber cambiado después de su primera solución, revelando el siguiente bloqueador.

Prevención que realmente ayuda

Monitoree el disco antes de que se alcancen las marcas de agua. Alerte sobre tendencias, no solo discos llenos.

Use ILM o flujos de datos para registros y métricas para que la retención sea automática.

Mantenga las instantáneas actualizadas y pruebe las restauraciones. Una instantánea que nunca ha restaurado es solo una esperanza.

Mantenga los tamaños de fragmento y los recuentos de fragmentos razonables. Demasiados fragmentos pequeños hacen que la asignación y la recuperación sean más lentas de lo que sugiere el volumen de datos.

Documente los filtros de asignación y los atributos de nodo. Seis meses después, alguien reemplazará un nodo y olvidará el atributo que hizo que un índice fuera asignable.

Trate el amarillo como una advertencia y el rojo como un incidente. El amarillo puede ser aceptable durante el mantenimiento, pero no debe convertirse en ruido de fondo. El rojo significa que al menos un fragmento primario no está disponible, y cuanto más espere, menos opciones de recuperación fáciles puede tener.

Una lista de verificación de campo para incidentes

Cuando la asignación de fragmentos se rompe, recoja la misma evidencia cada vez. Mantiene al equipo saltando entre teorías.

Ejecute:

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

Luego ejecute la explicación de asignación para un fragmento no asignado representativo. Si hay muchos, agrúpelos por razón. Diez réplicas no asignadas bloqueadas por marcas de agua de disco son un problema. Tres primarios con no_valid_shard_copy son un problema diferente.

Anote si los datos afectados pueden reconstruirse. Los registros de una cola ascendente, las métricas de agentes y los índices de búsqueda derivados pueden ser recuperables de sistemas fuente. El contenido creado por el usuario o los registros de cumplimiento pueden no serlo. Los comandos de recuperación deben seguir esa realidad empresarial.

Cuándo esperar y cuándo actuar

Espere cuando la recuperación esté progresando activamente, se espera que el nodo faltante vuelva pronto, o la asignación retrasada está haciendo exactamente lo que configuró que hiciera. Puede verificar el progreso con _cat/recovery; los recuentos de bytes y archivos en movimiento son buenas señales.

Actúe cuando la explicación de asignación muestre un bloqueador permanente: sin nodos adecuados, marcas de agua de disco en cada nodo, asignación deshabilitada, atributos de nodo faltantes o ninguna copia de fragmento válida. Esperar no arreglará una regla que rechaza cada nodo.

Escale rápidamente cuando los fragmentos primarios no estén asignados para índices importantes. Los fallos de réplica reducen la seguridad. Los fallos de primario reducen la disponibilidad.

Evite hacer la recuperación más lenta

Las recuperaciones grandes compiten con la búsqueda e indexación normales. Agregar demasiados nodos a la vez, reiniciar más nodos o aumentar la concurrencia de recuperación sin verificar la capacidad del disco y la red puede hacer que el clúster sea menos estable.

Si ajusta la configuración de recuperación, hágalo deliberadamente y registre los valores originales. Configuraciones como recuperaciones concurrentes pueden ayudar en algunos entornos y perjudicar en otros. Una recuperación más rápida en papel puede sobrecargar los discos y aumentar la latencia de consulta lo suficiente como para que los usuarios experimenten una interrupción peor.

Esté atento a los nodos calientes. La asignación puede tener éxito técnicamente mientras coloca demasiado trabajo en un nodo debido a tamaños de fragmento, reglas de nivel o uso desigual del disco. Use _cat/allocation, estadísticas de nodo y su sistema de monitoreo para confirmar que el clúster está equilibrado después de que se resuelva el fallo inmediato.

Arreglos posteriores a la acción

La mayoría de los incidentes de asignación de fragmentos tienen una historia de prevención. Los incidentes de marcas de agua de disco apuntan a retención, ILM o planificación de capacidad. Los incidentes de filtros de asignación apuntan a documentación faltante de runbook. Los incidentes de ninguna copia válida apuntan a instantáneas y reproducción ascendente. La recuperación lenta apunta al tamaño de fragmento y hardware.

No cierre el incidente solo porque la salud esté verde. Elimine los cambios temporales de réplica, restaure los intervalos de actualización normales, vuelva a habilitar la asignación si se cambió, verifique las instantáneas y agregue la alerta que habría detectado el problema antes.

Caso especial: índices cerrados y ocultos

A veces un índice no se asigna porque está cerrado, oculto o es parte de una característica del sistema que no se dio cuenta de que estaba tocando. Tenga cuidado con comandos comodín amplios cuando hay índices del sistema presentes. En clústeres modernos, la seguridad, Kibana, transformaciones y otras características de la pila pueden mantener sus propios índices.

Use patrones estrechos e incluya índices ocultos solo cuando tenga la intención de inspeccionarlos. Si un índice del sistema tiene problemas de asignación, verifique los registros del componente de la pila relacionado además de Elasticsearch. Por ejemplo, un problema de índice de objetos guardados de Kibana puede aparecer como un problema de asignación de fragmentos de Elasticsearch y como fallos de inicio de Kibana.

La regla es la misma que con los datos de usuario: identifique el índice exacto, entienda quién lo posee, luego elija la solución. No elimine ni fuerce la asignación de un índice del sistema solo para limpiar un estado de salud rojo a menos que entienda el impacto a nivel de producto.