Operación diaria y escenarios de fallo de Elasticsearch (8.x / 9.x)

No es una instalación: runbook por escenarios para administrar a diario un cluster Elasticsearch 8.x / 9.x ya instalado y recuperarlo cuando falla. Estado y allocation explain, resolución de shards sin asignar (disco, filtering, retry_failed, replicas, stale/empty primary como último recurso), disk watermark, el bloque read_only_allow_delete, alta y retirada segura de nodos, reindex sin interrupción con un alias, ILM y rollover, _shrink / _split, restauración de un único índice desde un snapshot con un nombre nuevo. Si no sabe qué hacer, empiece por la comprobación de estado. La configuración del snapshot repository y SLM, el endurecimiento de seguridad y la actualización de versión están en guías de Elasticsearch separadas.

Topología: Cluster Elasticsearch 8.x / 9.x (1–N nodos), TLS y autenticación activados

Escenarios

• Estado del cluster: status, nodos, shards sin asignar, disco — Solo lectura: green/yellow/red, lista de nodos, shards sin asignar (UNASSIGNED) y su causa (allocation explain), uso de disco y watermark, tareas pendientes. Empiece aquí si no está seguro de qué hacer.
• Resolver un shard sin asignar (UNASSIGNED) (según explain) — El cluster está en yellow o red y los shards no se asignan: según la causa de allocation explain, disco, allocation filtering, límite de reintentos (retry_failed), número de replicas o, como último recurso, un primary a partir de una copia antigua.
• Ver / cambiar la configuración de disk watermark — Los shards se mueven o no se asignan por la ocupación del disco; hay que cambiar los umbrales de watermark (low / high / flood_stage) de forma temporal o permanente, o volver a los valores predeterminados.
• El índice pasó a solo lectura: quitar el bloque read_only_allow_delete — Las escrituras se rechazan con 'FORBIDDEN/12/index read-only / allow delete (api)' o 'TOO_MANY_REQUESTS/12/disk usage exceeded flood-stage watermark': primero se libera disco y después se quita el bloque.
• Añadir un nodo al cluster (enrollment token) — Se necesita más capacidad: se ha instalado Elasticsearch en un servidor nuevo, que se une al cluster con un enrollment token; los shards se reequilibran solos. Sin interrupción.
• Retirar un nodo de forma segura (exclude, vaciar, apagar) — Un nodo se retira o se le va a cambiar el hardware: con un allocation exclude sus shards se mueven a los demás nodos, se comprueba que ha quedado vacío, si es master-eligible se le aplica una voting exclusion y después se apaga.
• Reindex: cambio sin interrupción a un índice nuevo con alias para un cambio de mapping/configuración — Hay que cambiar el tipo de un campo del mapping, el analyzer o el número de shards: se crea un índice nuevo, los datos se copian con _reindex y el alias se cambia de forma atómica al índice nuevo.
• Configurar / diagnosticar index lifecycle (ILM) y rollover — Los índices de logs/series temporales crecen o no se borran: se configuran una política ILM (rollover + delete), un index template y el índice inicial (write alias); explain muestra por qué una política existente no avanza.
• Corregir el número de shards: _shrink (reducir) / _split (aumentar) — El número de shards del índice se eligió mal: los shards muy pequeños (exceso de shards) se combinan con _shrink, los muy grandes se dividen con _split; el cambio se hace con un alias.
• Restaurar un único índice desde un snapshot con un nombre nuevo — Se borró o se dañó un índice: desde el snapshot repository se restaura solo ese índice con un nombre nuevo (rename), sin tocar el índice en producción; tras verificarlo, se pone en servicio con un alias.

Antes de empezar

• En … (…) dispone de acceso root, curl y el certificado CA de HTTP del cluster (…); tiene la contraseña del usuario elastic (o de un usuario con manage + privilegios sobre índices). Las llamadas a la API se hacen a este nodo por HTTPS.
• Se ha abierto un registro de cambio y se ha informado al equipo de aplicación. El movimiento de shards, el reindex y las operaciones de resize generan carga de disco, red y CPU; hágalos fuera de las horas punta. Antes de los pasos irreversibles (borrado, stale/empty primary) debe existir un snapshot reciente: Snapshot.
• El servidor nuevo está preparado con las fases de preparación del sistema operativo e instalación del software de la guía de instalación del cluster: la misma versión de Elasticsearch, vm.max_map_count, heap, swap desactivado, 9200/9300 abiertos en el firewall; el servicio nunca se ha iniciado (el enrollment solo es posible antes del primer arranque).

Fases de la guía

• Acceso a la API — Archivo temporal de credenciales para la API
• Estado: salud, nodos, shards, disco (solo lectura) — Estado del cluster, nodos y shards sin asignar · Preguntar por qué el shard no está asignado (allocation explain) · Uso de disco y watermark · Tareas pendientes e interpretación del resultado
• 1. Diagnóstico: ¿por qué no se asigna el shard? — Shards del índice y decisión de explain
• 2. Aplicación — Reintentar las asignaciones fallidas (retry_failed) · Ajustar el número de replicas al número de nodos · Quitar el allocation filtering · Ir al bloqueo por disco · Asignar el primary desde una copia antigua (allocate_stale_primary) · Asignar un primary vacío (allocate_empty_primary)
• 3. Verificación — Seguir el arranque de los shards
• 1. Diagnóstico — Uso de disco y umbrales actuales
• 2. Aplicación — …Cambiar los umbrales…Volver a los umbrales predeterminados…
• 1. Diagnóstico: bloque y disco — Ver los índices bloqueados y el disco · Opciones para liberar disco
• 2. Aplicación — Quitar el bloque
• 3. Verificación — Comprobar que la escritura funciona
• 1. Diagnóstico — Ver el estado del cluster
• 2. Aplicación: enrollment y unión — Crear un enrollment token de nodo · Configurar el nodo nuevo con el token · Comprobar node.name y la configuración de red · Iniciar el servicio
• 3. Verificación — Verificar que el nodo se ha unido y recibe shards
• 1. Diagnóstico — Ver los shards y el rol del nodo
• 2. Aplicación: vaciar y apagar — Mover los shards fuera del nodo (allocation exclude) · Esperar a que el nodo se vacíe · Excluir de la votación el nodo master-eligible · Detener el nodo · Quitar el exclude y la voting exclusion
• 3. Verificación — Verificar el estado del cluster
• 1. Diagnóstico y preparación — Ver el índice de origen y el alias · Crear el índice nuevo con el mapping/ajustes nuevos
• 2. Aplicación: copiar y cambiar el alias — Copiar los datos (_reindex, en segundo plano) · Seguir la tarea · Preparar el índice nuevo y comparar los recuentos · Cambiar el alias de forma atómica al índice nuevo
• 3. Después — Cerrar el índice antiguo (borrarlo después)
• 1. Política ILM, template e índice inicial — Crear la política ILM · Crear el index template · Crear el índice inicial con el alias de escritura
• Diagnóstico: ¿por qué no avanza ILM? — Ver el estado de ILM y los índices con error · Reintentar el paso fallido
• Rollover manual — Hacer rollover del alias ahora
• 1. Diagnóstico — Número de shards y tamaño del índice
• 3. Aplicación — …Shrink…Split…: … → … (… shards) · Cambiar el alias al índice nuevo
• 4. Después — Cerrar el índice de origen (borrarlo después)
• 1. Diagnóstico: ¿está el índice en el snapshot? — Ver los snapshots y el índice que contienen
• 2. Aplicación: restaurar con un nombre nuevo — Restaurar el índice como …… · Verificar y poner en servicio
• Limpieza — Borrar el archivo de credenciales