Solución de problemas de salud del clúster de Elasticsearch: Una guía paso a paso

Un clúster de Elasticsearch amarillo o rojo no es un estado misterioso. Generalmente significa que Elasticsearch no puede colocar uno o más fragmentos donde quiere colocarlos. El trabajo es encontrar qué fragmento está atascado, por qué la asignación está bloqueada y si la solución correcta es esperar, liberar recursos, recuperar un nodo, restaurar desde una instantánea o aceptar deliberadamente la pérdida de datos.

Trato la salud del clúster como una señal de triaje, no como el diagnóstico en sí. Verde significa que cada fragmento primario y réplica está asignado. Amarillo significa que todos los fragmentos primarios están asignados, por lo que las búsquedas y escrituras generalmente pueden continuar, pero al menos una réplica falta. Rojo significa que al menos un fragmento primario no está asignado, por lo que parte de al menos un índice no está disponible. El rojo es el que puede romper las lecturas o escrituras de la aplicación de inmediato.

Comience obteniendo la vista simple:

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

Mire status, number_of_nodes, active_primary_shards, unassigned_shards, initializing_shards y relocating_shards. Si ve fragmentos inicializando o reubicándose después de reiniciar un nodo, el clúster puede ya estar recuperándose. No comience a cambiar la configuración de asignación antes de saber si Elasticsearch simplemente está trabajando.

Luego enumere los fragmentos no asignados:

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

La columna prirep es importante. Un fragmento p es primario. Un clúster rojo siempre tiene al menos un primario no asignado. Un fragmento r es una réplica. Un clúster amarillo generalmente solo tiene réplicas no asignadas.

La API más útil en esta situación es la explicación de asignación:

GET /_cluster/allocation/explain?pretty

Para un fragmento específico, sea explícito:

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

Lea la respuesta can_allocate y las decisiones a nivel de nodo. Elasticsearch generalmente le dirá exactamente qué regla bloqueó la asignación: marcas de agua de disco, filtros de asignación, reglas de mismo fragmento, asignación retrasada después de que un nodo se fue, datos primarios faltantes, versiones incompatibles o una discrepancia de roles de nodo.

Cuando el Clúster Está Amarillo

El amarillo es común en clústeres pequeños. El caso clásico es un clúster de desarrollo de un solo nodo con number_of_replicas: 1. Elasticsearch no puede colocar una réplica en el mismo nodo que su primario, por lo que la réplica permanece no asignada para siempre. Eso no es una emergencia en un entorno de computadora portátil. Es un desajuste de configuración.

Verifique el recuento de réplicas:

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

Para un clúster de un solo nodo no productivo, establezca las réplicas a cero:

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

Para producción, no oculte el problema reduciendo las réplicas a menos que esté aceptando intencionalmente menos redundancia. Si se supone que el índice tiene una réplica, necesita al menos dos nodos de datos elegibles. Si tiene dos réplicas, necesita al menos tres nodos de datos elegibles. La estratificación puede hacer esto menos obvio: una réplica de índice cálido no puede asignarse a un nodo solo caliente si las reglas de asignación requieren nodos cálidos.

La presión de disco es la siguiente causa común de amarillo. Verifique el uso de disco del nodo:

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

Elasticsearch utiliza marcas de agua de disco para evitar llenar nodos. Los valores predeterminados varían según la versión y la configuración, así que inspeccione la configuración real de su clúster:

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

Si un nodo supera la marca de agua alta, Elasticsearch evitará asignar más fragmentos allí. Si alcanza la marca de agua de nivel de inundación, Elasticsearch puede colocar los índices afectados en un estado de bloqueo de escritura para proteger el nodo. La solución duradera es eliminar datos antiguos, mover datos a más nodos, aumentar el disco, reducir el recuento de fragmentos sobredimensionados o ajustar la retención de ILM. Aumentar temporalmente las marcas de agua puede ganar tiempo, pero no debería ser su primer movimiento.

Una secuencia práctica de limpieza se ve así:

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

Encuentre índices grandes y antiguos, verifique las expectativas de retención con el equipo propietario, haga una instantánea si es necesario, luego elimine solo los datos que tiene permitido eliminar:

DELETE /old-logs-2025.12.*

Después de liberar espacio, la asignación puede reanudarse automáticamente. Si no es así, vuelva a ejecutar la explicación de asignación. La razón anterior puede aún estar almacenada en su cabeza, pero el clúster ahora puede estar bloqueado por una regla diferente.

El filtrado de asignación es otra causa frecuente de amarillo, especialmente después de migraciones de hardware. Alguien puede haber establecido un índice para requerir un atributo de nodo que ya no existe:

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

Si la regla es incorrecta, elimínela o actualícela:

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

Use las claves exactas que muestran sus configuraciones. No pegue un reinicio amplio en producción sin leerlo; las reglas de asignación a veces están allí por una buena razón, como mantener ciertos datos en un nivel controlado por cumplimiento.

Cuando el Clúster Está Rojo

El rojo merece manos más lentas y mejores notas. La primera pregunta es si el fragmento primario faltante tiene una copia recuperable en algún lugar.

Enumere los fragmentos primarios no asignados:

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

Luego verifique qué nodos están presentes:

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

Si falta un nodo, su mejor ruta de recuperación es a menudo traer ese nodo de vuelta. Verifique el servicio, el montaje del disco, la red del host, los certificados y los registros en el nodo faltante. Un nodo que perdió el acceso a su ruta de datos puede iniciar como un nodo vacío diferente, lo que no ayuda a recuperar el fragmento primario.

En el nodo de Elasticsearch, los registros generalmente muestran la falla real antes que las API. Busque mensajes sobre fallas de bloqueo de fragmentos, archivos de índice corruptos, descubrimiento maestro, errores de protocolo de enlace TLS, sistemas de archivos de solo lectura de disco o cambios de roles de nodo. Una falla común del mundo real es un reinicio de nodo después de que un disco se volvió a montar bajo una ruta diferente. Elasticsearch se inicia, pero la ruta de datos está vacía, por lo que el clúster aún carece de la copia del fragmento que necesita.

Ejecute la explicación de asignación para el primario:

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

Si la explicación dice que no se puede encontrar ninguna copia de fragmento válida, deténgase y verifique las instantáneas antes de hacer algo destructivo:

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

Restaurar una instantánea suele ser más seguro que asignar un primario vacío. Un primario vacío crea un nuevo fragmento en blanco para esa ID de fragmento. No es una operación de reparación. Le dice a Elasticsearch: "Acepto que los datos antiguos para este fragmento se han ido".

El comando de último recurso se ve así:

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

Úselo solo después de haber confirmado que no hay una copia de nodo utilizable ni una instantánea que pueda restaurar. En un incidente, escriba quién aprobó esa elección y qué índice y fragmento se vieron afectados. La depuración futura es mucho más fácil cuando la decisión de pérdida de datos es explícita.

Casos Que Parecen Problemas de Asignación Pero Son Realmente Problemas de Clúster

A veces los fragmentos no están asignados porque el clúster no puede mantener una membresía estable. Si los nodos elegibles para maestro no pueden comunicarse entre sí, el maestro elegido puede cambiar repetidamente, y la asignación se agitará o pausará. Verifique la estabilidad del maestro:

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

Si el maestro cambia a menudo, inspeccione la confiabilidad de la red, DNS, certificados de nodo y configuraciones de descubrimiento. Para clústeres modernos de Elasticsearch, cluster.initial_master_nodes es para el arranque inicial del clúster, no una configuración para dejar como una muleta de descubrimiento para siempre. discovery.seed_hosts debe apuntar a hosts semilla apropiados, y todos los nodos deben usar el mismo nombre de clúster y configuraciones de seguridad compatibles.

La alta presión de JVM también puede causar síntomas de asignación. Un nodo de datos atascado en pausas largas de recolección de basura puede salir y reingresar al clúster desde el punto de vista del maestro. Eso puede crear fragmentos no asignados aunque la máquina nunca se haya estrellado por completo.

Verifique el montón y los registros de recolección de basura:

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

Si el montón es consistentemente alto, no aumente el montón ciegamente. Elasticsearch generalmente funciona mejor cuando el montón deja suficiente memoria para el caché del sistema de archivos. Busque agregaciones sobredimensionadas, uso intensivo de fielddata, demasiados fragmentos, indexación agresiva o consultas que necesiten mejores mapeos.

El recuento de fragmentos puede ser la causa silenciosa detrás de muchos problemas de salud. Un clúster con muchos fragmentos pequeños gasta demasiado esfuerzo rastreando metadatos y moviendo fragmentos. 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

Si cada índice de registro diario tiene muchos fragmentos primarios pero pocos datos, arregle la plantilla de índice para índices futuros. Luego considere planes de reducción, renovación o reindexación para datos existentes.

Un Orden de Triaje Práctico

Cuando alguien dice "Elasticsearch está rojo", uso este orden:

1. Confirme la salud con _cluster/health.
2. Enumere los fragmentos no asignados con _cat/shards.
3. Separe las fallas primarias de las fallas de réplica.
4. Ejecute _cluster/allocation/explain en un fragmento representativo.
5. Verifique si todos los nodos esperados están presentes.
6. Verifique las marcas de agua de disco y las reglas de asignación.
7. Para primarios rojos, intente recuperar el nodo faltante o restaurar desde instantánea antes de considerar la asignación de primario vacío.
8. Después de que el clúster se vuelva verde, encuentre la causa que lo hizo insalubre en primer lugar.

Ese último paso es importante. Un clúster puede volverse verde después de agregar disco, reiniciar un nodo o reducir réplicas, pero el mismo incidente regresará si la retención de ILM es incorrecta, los recuentos de fragmentos son demasiado altos, los nodos son demasiado pequeños o un proceso de implementación sigue cambiando los atributos del nodo.

La solución de problemas de salud del clúster se trata menos de memorizar un comando mágico y más de negarse a adivinar. Elasticsearch expone la decisión de asignación. Léala, verifíquela contra la configuración del nodo y del índice, y elija la solución más pequeña que coincida con el bloqueador real.

Después de Que el Clúster Esté Verde Nuevamente

No cierre el incidente solo porque el color cambió. Verde solo significa que los fragmentos están asignados ahora. No prueba que el clúster sea lo suficientemente saludable para el próximo pico de tráfico, ciclo de crecimiento de disco o reinicio de nodo. Me gusta capturar una breve nota posterior a la acción mientras los detalles aún están frescos: qué índices se vieron afectados, qué nodos estuvieron involucrados, qué regla de asignación bloqueó la recuperación y qué comando o cambio de infraestructura lo solucionó.

Verifique si la solución creó un nuevo riesgo. Si redujo las réplicas para convertir amarillo en verde, registre que el índice ahora tiene menos redundancia. Si aumentó las marcas de agua de disco, agregue un recordatorio para bajarlas después de agregar capacidad. Si restauró una instantánea, verifique que el índice restaurado tenga los alias y configuraciones de escritura esperados antes de que las aplicaciones reanuden las escrituras normales.

Algunas verificaciones rápidas ayudan a detectar trabajo incompleto:

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 no debería crecer para siempre. La recuperación eventualmente debería vaciarse. Los alias importan porque restaurar un índice bajo un nombre diferente puede dejar a la aplicación escribiendo en el objetivo antiguo roto o leyendo solo parte de los datos previstos.

También verifique los bloqueos de escritura después de incidentes de disco:

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

Si Elasticsearch estableció un bloqueo de nivel de inundación, elimínelo solo después de que se solucione la presión de disco:

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

El trabajo de prevención más útil suele ser aburrido: instantáneas funcionales, restauraciones probadas, retención realista de ILM, suficiente espacio libre en disco y recuentos de fragmentos que coincidan con el tamaño del clúster. Un clúster con instantáneas confiables y un tamaño de fragmentos sensato es mucho más fácil de recuperar que un clúster con comandos de emergencia ingeniosos y sin ruta de restauración.

Qué No Hacer Durante Incidentes de Salud

No reinicie todos los nodos a la vez. Es tentador cuando el clúster se ve insalubre, pero un enfoque gradual y observado es más seguro. Reiniciar nodos saludables puede eliminar copias de fragmentos que Elasticsearch necesita para la recuperación. Si debe reiniciar, hágalo un nodo a la vez y espere a que el clúster se estabilice entre pasos.

No deshabilite la asignación y lo olvide. Los cambios temporales de asignación son comunes durante el mantenimiento, pero una configuración olvidada puede dejar réplicas no asignadas mucho después de que termine la ventana de mantenimiento. Siempre verifique las configuraciones persistentes y transitorias:

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

No elimine índices basándose solo en el tamaño. Los índices grandes pueden ser críticos para el negocio. Los índices pequeños pueden ser seguros de eliminar. Vincule la limpieza a la política de retención, instantáneas y propiedad de la aplicación. En una interrupción real, la limpieza segura más rápida suele ser eliminar índices de registro o métricas que se sabe que han expirado, no adivinar a partir de una lista ordenada por tamaño.

No asuma que Kibana y Elasticsearch usan el mismo lenguaje para el problema. Kibana puede mostrar un estado rojo amplio mientras que las API de Elasticsearch muestran el fragmento no asignado preciso. Use la interfaz de usuario para visibilidad, pero use las API para la decisión.