Resolución de problemas de salud del clúster Elasticsearch: una guía paso a paso

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

Elasticsearch es un sistema distribuido robusto, pero como cualquier arquitectura distribuida, requiere monitoreo activo e intervención ocasional para mantener una salud óptima. El estado de salud del clúster es la métrica más crítica para determinar la preparación operativa y la seguridad de los datos de su implementación. Cuando el clúster pasa de Verde a Amarillo o, fundamentalmente, a Rojo, la integridad o disponibilidad de los datos se ve amenazada.

Esta guía exhaustiva proporciona pasos expertos para diagnosticar y resolver problemas comunes de estado de salud del clúster de Elasticsearch, centrándose específicamente en la recuperación de los estados Amarillo y Rojo. Utilizaremos las API Cat prácticas y verificaciones paso a paso para identificar rápidamente la causa raíz e implementar acciones correctivas.

---

1. Comprensión del estado de salud del clúster de Elasticsearch

Antes de solucionar problemas, es esencial comprender lo que significa cada color de estado de salud del clúster. El estado de salud está determinado por el estado de asignación de sus fragmentos primarios y de réplica en todos los nodos del clúster.

Estado	Significado	Implicaciones
Verde	Todos los fragmentos primarios y de réplica están asignados con éxito.	El clúster está totalmente operativo y es resistente.
Amarillo	Todos los fragmentos primarios están asignados, pero uno o más fragmentos de réplica no están asignados.	Los datos están disponibles, pero el clúster carece de plena resiliencia ante fallos de nodos.
Rojo	Al menos un fragmento primario no está asignado (y, por lo tanto, no está disponible).	Pérdida de datos o inaccesibilidad para el índice que contiene los fragmentos fallidos. Se requiere acción crítica.

2. Diagnóstico inicial: comprobación del estado del clúster

El primer paso en cualquier proceso de solución de problemas es confirmar el estado actual y recopilar métricas básicas utilizando la API de estado del clúster (Cluster Health API) y la API de nodos (Nodes API).

Paso 2.1: Comprobar el estado del clúster

Utilice la API _cat/health para obtener un resumen de alto nivel. El parámetro ?v proporciona una salida detallada, incluido el número de nodos y el recuento total de fragmentos.

GET /_cat/health?v

Salida de ejemplo (estado Amarillo):

epoch      timestamp cluster       status node.total node.data shards  pri relo init unassign pending_tasks max_task_wait_time active_shards_percent
1678233600 09:00:00  my-cluster    yellow 3          3         10     5    0    0        5 0             -                  50.0%

Si el estado es Amarillo o Rojo, anote el valor de unassign.

Paso 2.2: Comprobar el estado y la memoria de los nodos

Asegúrese de que todos los nodos esperados estén conectados y operando correctamente. Además, compruebe la utilización del heap (crítico para el rendimiento y la estabilidad).

GET /_cat/nodes?v&h=name,node.role,version,heap.percent,disk.total,disk.used,disk.avail

Si falta un nodo en esta lista, es posible que tenga un problema de conectividad o un servicio detenido.

3. Resolución del estado de clúster Rojo (Fallo del fragmento primario)

Un estado Rojo significa que los datos son inmediatamente inaccesibles. El objetivo es volver a poner en línea el fragmento primario lo más rápido posible.

Paso 3.1: Identificar los fragmentos primarios no asignados

Utilice la API _cat/shards para identificar el índice y el fragmento exactos que están causando el problema. Busque específicamente las entradas marcadas como UNASSIGNED con un rol p (primario).

GET /_cat/shards?v | grep UNASSIGNED

Salida de ejemplo:

index_logs 0 p UNASSIGNED 

Paso 3.2: Comprobar la explicación de la asignación

Este es el paso de diagnóstico más importante. La API de explicación de asignación (Allocation Explain API) le dice por qué un fragmento específico (o cualquier fragmento no asignado) no se puede asignar.

GET /_cluster/allocation/explain

Razones comunes para el estado Rojo:

1. Fallo del nodo: El nodo que albergaba el fragmento primario se ha bloqueado o se ha eliminado del clúster. Si el nodo fallido tiene suficientes réplicas en otros nodos, el fragmento primario debería promocionar automáticamente una réplica. Si todas las copias (primario y réplicas) estaban en el nodo fallido, el fragmento se pierde a menos que el nodo se recupere.
2. Datos dañados: Los archivos del fragmento primario en el disco se han corrompido, lo que impide que el nodo los inicialice.

Paso 3.3: Plan de acción para el estado Rojo

• Escenario A: Nodo Desconectado (Preferido)
  • Si el nodo que albergaba el fragmento primario está simplemente fuera de línea, restaure el servicio del nodo (por ejemplo, reinicie Elasticsearch o solucione los problemas de red). Una vez que el nodo se reincorpora al clúster, el fragmento primario debería recuperarse.
• Escenario B: Fragmento primario perdido (Último recurso)
  • Si el nodo se pierde permanentemente y no existían réplicas, los datos han desaparecido. Debe omitir manualmente la recuperación utilizando el comando allocate_empty_primary. Advertencia: Esto creará un fragmento primario nuevo y vacío, lo que resultará en la pérdida permanente de datos para ese segmento del índice.

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

Mejor práctica: Antes de recurrir a allocate_empty_primary, verifique siempre si existe una instantánea o copia de seguridad para el índice.

4. Resolución del estado de clúster Amarillo (Fallo del fragmento de réplica)

Un estado Amarillo significa que el clúster está operativo pero vulnerable. El objetivo principal es asignar las réplicas faltantes.

Paso 4.1: Usar Explicación de Asignación

Si el estado es Amarillo, utilice la API _cluster/allocation/explain (Sección 3.2) para comprender por qué no se puede asignar la réplica. La explicación para las réplicas suele ser más sencilla.

Razones comunes para el estado Amarillo:

Código de razón	Explicación	Solución
NO_AVAILABLE_NODES	El tamaño del clúster es demasiado pequeño (por ejemplo, el recuento de réplicas es 2, pero solo existen 2 nodos).	Añadir más nodos de datos o reducir number_of_replicas.
NOT_ENOUGH_DISK_SPACE	Los nodos alcanzaron el umbral de marca de agua baja o alta.	Eliminar índices antiguos, liberar espacio en disco o ajustar las marcas de agua de disco.
ALLOCATION_DISABLED	La asignación de fragmentos se deshabilitó explícitamente mediante la configuración del clúster.	Reactivar el enrutamiento mediante PUT /_cluster/settings.
PRIMARY_NOT_ACTIVE	El fragmento primario todavía se está inicializando o recuperando.	Espere a que el primario esté activo (Verde).

Paso 4.2: Comprobación de los requisitos y restricciones de los nodos

Asegúrese de que el clúster cumpla con los requisitos básicos para la asignación de réplicas:

1. Recuento de nodos: Para N réplicas, necesita al menos N+1 nodos de datos para garantizar que el primario y las réplicas nunca estén en el mismo nodo.
2. Marcas de agua de disco: Elasticsearch deja de asignar fragmentos a los nodos cuando el uso del disco supera la marca de agua alta (90 % por defecto).

# Comprobar la configuración de asignación de disco
GET /_cluster/settings?flat_settings=true&filter_path=*watermark*

# Ejemplo: Establecer la marca de agua alta en 95% (¡Temporalmente!)
PUT /_cluster/settings
{
  "persistent": {
    "cluster.routing.allocation.disk.watermark.high": "95%"
  }
}

Paso 4.3: Reenrutamiento manual (si la lógica de asignación falla)

En raras ocasiones, si el proceso de asignación estándar parece atascado a pesar de contar con recursos suficientes, puede forzar manualmente la asignación de la réplica a un nodo saludable específico utilizando el comando allocate_replica.

POST /_cluster/reroute
{
  "commands" : [
    {
      "allocate_replica" : {
        "index" : "[index-name]", 
        "shard" : [shard-id],
        "node" : "[target-node-name]"
      }
    }
  ]
}

5. Solución de problemas avanzados y errores comunes

Si el estado Rojo o Amarillo persiste, la causa raíz puede estar fuera de la lógica estándar de asignación de fragmentos.

5.1 Conectividad de red y Split-Brain

En los sistemas distribuidos, la partición (split-brain) puede causar problemas graves. Si los nodos aptos para ser maestro no pueden comunicarse, el clúster podría no lograr elegir un maestro estable, lo que llevaría a fragmentos no asignados.

• Acción: Verifique la conectividad de red entre todos los nodos, especialmente entre los nodos aptos para ser maestro.
• Comprobación de configuración: Asegúrese de que su lista discovery.seed_hosts sea precisa y de que se haya utilizado correctamente la configuración cluster.initial_master_nodes durante el arranque del clúster.

5.2 Alta presión de memoria JVM

El uso excesivo del heap (a menudo por encima del 75 %) provoca pausas frecuentes y largas de Recolección de Basura (GC). Durante estas pausas, un nodo puede parecer no responder, lo que provoca que el nodo maestro lo desconecte, lo que lleva a fragmentos no asignados.

• Acción: Supervise el uso del heap (_cat/nodes?h=heap.percent). Si es constantemente alto, considere aumentar la memoria de los nodos, optimizar los procesos de indexación o implementar la gestión del ciclo de vida de los índices (ILM).

5.3 Filtrado de asignación de fragmentos

La aplicación accidental de filtros de asignación (utilizando atributos de nodo como etiquetas o ID) puede evitar que los fragmentos se asignen a nodos que de otro modo podrían ser elegibles.

# Comprobar las reglas de asignación a nivel de índice
GET /[index-name]/_settings
# Buscar: index.routing.allocation.require.*

# Restablecer las reglas de asignación de índices (si es necesario)
PUT /[index-name]/_settings
{
  "index.routing.allocation.require": null
}

Lista de verificación de resumen para una recuperación rápida

Estado	Herramienta de diagnóstico principal	Pasos de acción clave
Amarillo	GET /_cluster/allocation/explain	1. Comprobar el espacio en disco. 2. Verificar el recuento de nodos frente al recuento de réplicas. 3. Buscar reglas de filtrado de asignación. 4. Esperar la recuperación del primario.
Rojo	GET /_cat/shards?v | grep UNASSIGNED	1. Revisar los registros del nodo que alojaba anteriormente. 2. Intentar reiniciar el nodo fallido. 3. Si se confirma la pérdida del primario y no existe copia de seguridad, usar allocate_empty_primary (Riesgo de pérdida de datos).

Al utilizar sistemáticamente las API _cat y el punto final crítico _cluster/allocation/explain, puede identificar rápidamente la causa de la degradación del estado de salud del clúster e implementar los pasos correctivos necesarios para restaurar su clúster al estado estable Verde.