Solución de problemas: Verificación e interpretación del estado de salud del clúster de Elasticsearch

La salud del clúster de Elasticsearch es una de esas comprobaciones que parecen simples hasta que suena el buscapersonas. La API te da un color, pero el color es solo el punto de partida. Un clúster verde puede ser lento. Un clúster amarillo puede ser perfectamente utilizable durante una ventana de mantenimiento corta. Un clúster rojo puede significar que un pequeño índice de prueba no está disponible, o que la búsqueda orientada al cliente está perdiendo datos reales.

Cuando verifico la salud del clúster de Elasticsearch, intento no saltar directamente de rojo a comandos de recuperación peligrosos. Primero quiero responder tres preguntas: ¿los shards primarios están asignados?, ¿las réplicas están asignadas?, y ¿el clúster está intentando recuperarse por sí mismo? Los comandos a continuación son los que uso para pasar de un color de salud amplio a una razón específica.

Comienza con la API de salud

Para una vista rápida en terminal, _cat/health es suficiente:

curl -s "http://localhost:9200/_cat/health?v"

Una respuesta típica se ve así:

epoch      timestamp cluster     status node.total node.data shards pri relo init unassign pending_tasks
1762219800 12:10:00  logs-prod   yellow          3         3    124  62    0    0        2             0

Los campos que miro primero son status, node.total, node.data, relo, init, unassign y pending_tasks. Un estado amarillo con init o relo mayor que cero puede ser simplemente un clúster recuperándose después de un reinicio. Un estado amarillo con shards no asignados y sin movimiento generalmente necesita investigación.

Para automatización, usa la API JSON en lugar de analizar la salida de _cat:

curl -s "http://localhost:9200/_cluster/health?pretty"

Esa respuesta incluye campos como active_primary_shards, active_shards, relocating_shards, initializing_shards, unassigned_shards y delayed_unassigned_shards. Esos nombres son más fáciles de usar en scripts y comprobaciones de monitoreo.

Qué significan realmente verde, amarillo y rojo

Verde significa que cada shard primario y cada shard réplica configurado está asignado. No significa que las consultas sean rápidas, que el disco esté sano o que los mapeos estén bien diseñados. Solo significa que Elasticsearch ha colocado los shards que se supone debe colocar.

Amarillo significa que todos los shards primarios están asignados, pero al menos un shard réplica no está asignado. Tus datos aún deberían ser buscables porque los primarios están disponibles. El riesgo es la redundancia. Si el nodo que contiene un primario falla mientras su réplica aún no está asignada, ese índice puede volverse rojo.

Rojo significa que al menos un shard primario no está asignado. Las búsquedas contra los índices afectados pueden fallar o devolver resultados parciales, y las escrituras en esos shards no pueden continuar normalmente. El rojo merece atención inmediata, pero la acción correcta depende de por qué el primario no está asignado.

Un ejemplo común en clústeres pequeños es un clúster de desarrollo de un solo nodo con una réplica configurada. Permanecerá amarillo porque Elasticsearch no colocará una réplica en el mismo nodo que su primario. Eso no es un misterio ni una razón para forzar la asignación. Agrega otro nodo de datos o establece las réplicas a cero para ese índice:

curl -X PUT "http://localhost:9200/my-index/_settings"   -H 'Content-Type: application/json'   -d '{"index":{"number_of_replicas":0}}'

No uses esa configuración casualmente en producción. Elimina la redundancia para ese índice.

Encuentra los shards no asignados exactos

Después del color de salud, lista los shards:

curl -s "http://localhost:9200/_cat/shards?v&h=index,shard,prirep,state,node,unassigned.reason" | sort

Busca UNASSIGNED. La columna prirep te dice si el shard es primario (p) o réplica (r). Esa distinción importa más que el color en sí. Algunas réplicas no asignadas generalmente significan tolerancia a fallos reducida. Un primario no asignado significa que al menos parte de un índice no está disponible.

Si ves muchos shards no asignados después de un reinicio planificado de un nodo, verifica también la asignación retrasada:

curl -s "http://localhost:9200/_cluster/health?pretty" | grep delayed_unassigned_shards

Elasticsearch puede esperar antes de reasignar réplicas después de que un nodo se va, porque el nodo puede volver rápidamente. Ese comportamiento evita cambios innecesarios en la red y el disco durante reinicios continuos.

Pregunta a Elasticsearch por qué falló la asignación

La API de explicación de asignación es el mejor siguiente paso. Puedes preguntar por cualquier shard no asignado:

curl -X GET "http://localhost:9200/_cluster/allocation/explain?pretty"   -H 'Content-Type: application/json'   -d '{}'

O preguntar por un shard específico:

curl -X GET "http://localhost:9200/_cluster/allocation/explain?pretty"   -H 'Content-Type: application/json'   -d '{
    "index": "logs-2026.05.24",
    "shard": 0,
    "primary": false
  }'

Lee unassigned_info, can_allocate y node_allocation_decisions. La parte útil suele estar en lenguaje sencillo: límite de disco excedido, asignación deshabilitada, ningún atributo de nodo coincidente, demasiados shards en un nodo, o una réplica no se puede colocar porque solo existe un nodo.

Si la explicación dice allocation_delayed, espera solo si se espera que el nodo faltante regrese pronto. Si la explicación dice que ningún nodo satisface las reglas de asignación, esperar no lo solucionará.

Manual de clúster amarillo

Para salud amarilla, uso este orden:

1. Verificar si el clúster tiene suficientes nodos de datos para el número de réplicas configurado.
2. Verificar los límites de disco con _cat/allocation.
3. Verificar si la asignación fue deshabilitada durante el mantenimiento.
4. Verificar los filtros de enrutamiento a nivel de índice y las reglas de awareness.
5. Decidir si agregar capacidad, reducir el número de réplicas o corregir una regla incorrecta.

La verificación del número de nodos es simple. Si un índice tiene number_of_replicas: 2, Elasticsearch necesita tres nodos de datos adecuados para colocar un primario más dos réplicas. "Adecuados" importa. Si el awareness de asignación requiere zonas separadas, necesitas nodos en esas zonas, no solo tres nodos cualesquiera.

Verifica la asignación y el disco:

curl -s "http://localhost:9200/_cat/allocation?v"

Si los nodos están por encima de los límites de disco, Elasticsearch puede rechazar nuevas asignaciones de shards. Libera espacio, agrega nodos, expande discos o elimina índices antiguos después de tomar snapshots. Aumentar los límites puede ganar tiempo en una emergencia controlada, pero no crea capacidad.

Verifica la configuración de asignación:

curl -s "http://localhost:9200/_cluster/settings?include_defaults=true&pretty"

Si cluster.routing.allocation.enable es none, la asignación está deshabilitada. Esto es común después de scripts de mantenimiento que olvidaron reactivarla. Vuelve a habilitarla con:

curl -X PUT "http://localhost:9200/_cluster/settings?pretty"   -H 'Content-Type: application/json'   -d '{
    "persistent": {
      "cluster.routing.allocation.enable": "all"
    }
  }'

También verifica si el valor se estableció como transient; las configuraciones persistentes y transitorias pueden afectar el comportamiento.

Manual de clúster rojo

Para salud roja, reduce la velocidad e identifica el radio de explosión. No empieces con allocate_empty_primary. Ese comando acepta pérdida de datos por diseño.

Primero, encuentra los shards primarios afectados:

curl -s "http://localhost:9200/_cat/shards?v&h=index,shard,prirep,state,node,unassigned.reason"   | grep ' p '   | grep UNASSIGNED

Luego inspecciona uno con la explicación de asignación:

curl -X GET "http://localhost:9200/_cluster/allocation/explain?pretty"   -H 'Content-Type: application/json'   -d '{
    "index": "affected-index",
    "shard": 0,
    "primary": true
  }'

Si el primario no está asignado porque un nodo está caído, tu mejor recuperación puede ser restaurar ese nodo. Verifica el servicio, el disco, los logs de JVM y la ruta de red. Si existe una copia réplica en otro nodo, Elasticsearch normalmente debería promoverla. Si no lo hace, la salida de explicación y los logs generalmente te dicen por qué.

Si los datos se pierden o corrompen, restaura desde un snapshot. Ese es el camino de recuperación limpio. Si no existe un snapshot y los datos se pueden reconstruir desde otra fuente, puedes decidir asignar un primario vacío:

curl -X POST "http://localhost:9200/_cluster/reroute?pretty"   -H 'Content-Type: application/json'   -d '{
    "commands": [
      {
        "allocate_empty_primary": {
          "index": "affected-index",
          "shard": 0,
          "node": "target-node-name",
          "accept_data_loss": true
        }
      }
    ]
  }'

Úsalo solo cuando perder el contenido del shard sea aceptable. El nombre es literal: Elasticsearch asigna un primario vacío y sigue adelante.

Observa la recuperación en lugar de adivinar

Después de una corrección, observa el movimiento de los shards:

curl -s "http://localhost:9200/_cat/recovery?v&active_only=true"
curl -s "http://localhost:9200/_cat/shards?v&h=index,shard,prirep,state,node,unassigned.reason"
curl -s "http://localhost:9200/_cluster/health?pretty"

La recuperación puede estar limitada por la velocidad del disco, el ancho de banda de la red, el tamaño del shard y la configuración de recuperación del clúster. Un shard grande puede permanecer en INITIALIZING más tiempo del esperado. Eso es diferente de estar atascado. Si los recuentos de bytes y archivos se mueven en _cat/recovery, déjalo trabajar.

También verifica las tareas pendientes del clúster cuando la salud no cambia:

curl -s "http://localhost:9200/_cat/pending_tasks?v"

Una cola larga puede apuntar a un nodo maestro sobrecargado o decisiones de asignación repetidas que no pueden completarse.

Un ejemplo práctico

Supongamos que _cat/health muestra amarillo con dos shards no asignados. _cat/shards muestra que ambos son réplicas para logs-2026.05.24. La explicación de asignación dice que el clúster no puede asignar porque cada nodo de datos está por encima del límite de disco bajo. La solución no es reenrutar shards manualmente. La solución es capacidad: eliminar índices antiguos después de tomar snapshots, agregar almacenamiento, agregar nodos de datos o mover datos fríos a otro lugar.

Otro ejemplo: un clúster de tres nodos está amarillo después de un reinicio continuo. _cluster/health muestra delayed_unassigned_shards: 8. El nodo detenido ya está volviendo. En ese caso, esperar unos minutos puede ser correcto. Forzar la asignación inmediatamente puede crear trabajo de recuperación adicional y hacer que el reinicio sea más lento.

Un tercer ejemplo: un clúster de laboratorio de un solo nodo está amarillo para siempre. _cat/shards muestra que cada shard no asignado es una réplica. El índice tiene una réplica. Elasticsearch se está comportando correctamente. Establece las réplicas a cero para el laboratorio o agrega un segundo nodo de datos.

Mantén honesta la verificación de salud

La salud del clúster debe ser parte del monitoreo, pero las reglas de alerta necesitan contexto. Alerta inmediatamente sobre rojo. Alerta sobre amarillo cuando dure más allá de una ventana de mantenimiento corta, cuando las réplicas no asignadas estén aumentando, o cuando la razón sea presión de disco. Rastrea los límites de disco, el número de nodos, la presión de JVM y el éxito de los snapshots junto con el color de salud. El color te dice por dónde empezar; las APIs de shards y asignación te dicen qué hacer después.

Cuando las verificaciones de salud no coinciden con los síntomas del usuario

A veces el clúster está verde y los usuarios aún se quejan. Eso no es una contradicción. La salud del clúster se trata de la asignación de shards, no de la latencia o corrección de las consultas. Si la salud es verde pero las búsquedas son lentas, pasa a la latencia de búsqueda, los grupos de hilos, los shards calientes, la presión de JVM y la latencia de almacenamiento. Un clúster verde con un nodo de datos sobrecargado aún puede sentirse roto.

También ocurre lo contrario. Un clúster puede estar amarillo por una razón inofensiva, como un entorno de desarrollo de un solo nodo con réplicas configuradas. El hábito útil es conectar el estado de salud al impacto empresarial. ¿Qué índice está afectado? ¿Es un primario o una réplica? ¿La aplicación está leyendo de ese índice ahora mismo? ¿Esto ocurre durante el mantenimiento planificado? Esas preguntas evitan que trates cada estado amarillo como un desastre.

Para sistemas orientados al cliente, me gusta mantener una pequeña tabla de runbook fuera de Elasticsearch: patrón de índice, servicio propietario, fuente de datos, política de snapshots, si los datos se pueden reproducir, y quién aprueba la recuperación destructiva. Durante un incidente rojo, esa tabla suele ser más útil que otro panel. Si clickstream-* se puede reproducir desde Kafka, la elección de recuperación es diferente de un índice que contiene documentos generados por usuarios sin copia ascendente.

Hábitos de comandos más seguros

Usa nombres de índice explícitos cuando puedas. Los comodines son convenientes, pero ocultan el radio de explosión. Antes de ejecutar cualquier comando que cambie configuraciones o elimine datos, lista lo que coincide con el patrón:

curl -s "http://localhost:9200/_cat/indices/logs-prod-*?v&s=index"

Guarda la salida de comandos del incidente. Pega los resultados de la explicación de asignación, los listados de shards y las respuestas de salud en el ticket. El estado de Elasticsearch cambia rápidamente durante la recuperación, y es posible que necesites la salida anterior para entender por qué se tomó una decisión.

Si la seguridad está habilitada, ejecuta estos comandos con un usuario que tenga los privilegios mínimos útiles para diagnósticos y un proceso separado más restringido para operaciones destructivas. En un incidente estresante, es demasiado fácil pegar un comando de escritura en el mismo shell donde solo estabas inspeccionando la salud.

Qué verificar después de que el clúster vuelva a verde

Verde no es el final del incidente. Verifica si las réplicas se reconstruyeron en los nodos que esperabas, si el disco todavía está cerca de los límites, y si algún índice quedó con configuraciones temporales como number_of_replicas: 0, un refresh_interval largo o asignación deshabilitada.

También confirma que los snapshots tengan éxito después de la recuperación. Un clúster que acaba de tener problemas de shards puede haber expuesto una brecha en la retención, las credenciales del repositorio o la programación de snapshots. Si la recuperación dependió de la suerte porque no existía un snapshot, escríbelo y arréglalo antes de la próxima falla.

Finalmente, revisa las alertas. Si los humanos notaron el problema antes que el monitoreo, agrega o ajusta alertas para salud roja, salud amarilla prolongada, presión de límites de disco, nodos faltantes, snapshots fallidos y elecciones de maestro repetidas. Un color de salud del clúster es útil, pero la mejor alerta te dice por qué cambió el color y qué índice está afectado.