Elasticsearch-кластер стал yellow: как найти и устранить неприсвоенные шарды

Yellow означает, что primary shards назначены, а одна или несколько реплик не размещены. На одноузловом кластере это может быть ожидаемым следствием replica count, но в многоузловом — сигналом дискового watermark, allocation filters, awareness, несовместимой версии или недостатка подходящих узлов.

Сначала выполните только чтение: cluster health, cat shards с unassigned reason, allocation explain, состояние узлов и дисков. Не используйте reroute allocate stale primary и не удаляйте индекс, пока primary доступны и причина относится к репликам.

Что проверить в первую очередь

Для проблемы «состояние Elasticsearch-кластера изменилось на yellow» сначала зафиксируйте один воспроизводимый пример: точное время, идентификатор объекта, пользователя или операции, входные данные, версию приложения и фактический результат. Отдельно запишите ожидаемое поведение: все primary и требуемые replica shards назначены согласно ресурсам и topology, а причина каждого unassigned shard понятна и устранена без необоснованного удаления данных. Это не формальность. Без исходной точки легко принять временное совпадение за исправление, изменить сразу несколько условий и потерять возможность доказать настоящую причину сбоя.

Проверку начинайте с чтения состояния и журналов. Не запускайте массовый перерасчёт, повторную отправку, удаление записей или изменение прав на рабочей системе, пока не подготовлены резервная копия и способ отката. Секреты, токены, персональные данные и содержимое заказов в диагностические выгрузки не включайте.

• Проверьте число data-узлов и количество replicas проблемного индекса.
• Получите unassigned.reason и решение allocation deciders.
• Сверьте disk watermarks и свободное место по data path.
• Проверьте node roles, allocation include exclude require и awareness attributes.
• Уточните недавний restart, upgrade, изменение template или потерю узла.

Почему возникает проблема

Видимый симптом обычно находится в конце цепочки. Пользователь видит неверный статус или отказ, хотя первичная ошибка могла произойти в API, фоновой задаче, кеше, очереди, внешнем сервисе либо при проверке доступа. Основной риск этого сценария: данные пока доступны, но часть replica shards не размещена и отказ одного узла может привести к потере доступности или усложнить восстановление. Поэтому исправление только интерфейса или ручная правка итоговой записи часто скрывает проблему, но не устраняет её.

Разбирайте события по хронологии и ищите первую точку, где фактические данные перестают соответствовать бизнес-правилу. В распределённой системе одинаково важны успешный ответ, повтор запроса, задержка события, параллельное выполнение и восстановление после временного отказа.

• Одна реплика настроена на кластере с одним data-узлом.
• Диск превысил low или high watermark.
• Allocation awareness требует зону, которой нет среди доступных узлов.
• Фильтр индекса или кластера исключает все подходящие узлы.
• Replica recovery ожидает узел, перегружена throttling или заблокирована несовместимостью.

Пошаговая диагностика

Создайте безопасный тестовый сценарий, максимально похожий на проблемный, но не затрагивающий реальные списания, рассылки и клиентские данные. Присвойте операции единый correlation ID и проследите его через входящий запрос, бизнес-логику, базу, очередь и внешние интеграции. Для каждого этапа фиксируйте вход, результат, код ответа, время выполнения и номер версии записи.

Сначала подтвердите сам факт расхождения, затем последовательно исключайте уровни. Сравните рабочий и ошибочный случаи по одним и тем же полям. Проверьте часовой пояс, формат идентификаторов, порядок событий, права сервисной учётной записи и актуальность конфигурации на каждом экземпляре приложения. Если результат зависит от повторного запроса, задержки или конкретного узла, это важная часть причины, а не случайный шум.

• Запросите allocation explain для конкретного unassigned replica.
• Сравните размер shard со свободным местом и watermark каждого узла.
• Посмотрите cluster settings с include_defaults и index settings.
• Проверьте pending tasks, recovery и состояние master.
• Сопоставьте начало yellow с изменением topology или шаблона.

Как выбирать корректное действие для yellow

Исправление определяется ответом allocation deciders. Для одноузловой среды допустимо осознанно уменьшить replicas, а для рабочего кластера обычно нужно вернуть подходящий узел, место или корректную topology.

Надёжная реализация хранит бизнес-состояние явно и не пытается восстановить его только по экрану, случайному логу или последнему webhook. У каждого значимого действия должен быть стабильный идентификатор, понятный владелец, версия правила и проверяемый переход статуса. Повторная доставка одного события не должна создавать второе действие, а запоздавшее событие не должно возвращать объект в невозможное состояние.

• Количество replicas соответствует требуемой отказоустойчивости и числу независимых узлов.
• Shards имеют разумный размер и не создают чрезмерное число мелких размещений.
• Disk watermarks наблюдаются заранее, а освобождение места не удаляет актуальные данные вслепую.
• Awareness attributes совпадают с реальными зонами.
• Index templates не возвращают ошибочное число replicas для новых индексов.

Как исправить проблему

Исправление разделите на небольшие обратимые изменения. Сначала устраните подтверждённую первопричину, затем восстановите повреждённые данные отдельной контролируемой процедурой. Не смешивайте выпуск нового кода и массовую коррекцию истории в одном непрозрачном запуске: для них нужны разные отчёты, критерии успеха и планы отката.

Если затронуты существующие записи, сначала сформируйте dry-run: список объектов, старое значение, предлагаемое новое значение и основание для изменения. Обновление должно быть идемпотентным, ограниченным точной выборкой и сопровождаться аудитом. Для финансовых данных, прав доступа и персональной информации предпочтительны компенсирующие записи, а не переписывание истории.

• На одноузловом тестовом кластере задайте replicas 0 только после подтверждения допустимого риска.
• Освободите или добавьте дисковую ёмкость и устраните причину роста.
• Исправьте allocation filters и awareness по фактическим атрибутам узлов.
• Верните потерянный data-узел или добавьте совместимый узел нужной роли.
• Обновите templates и политики, чтобы новые индексы не повторяли проблему.

Безопасный порядок внедрения

• Сохраните конфигурацию, связанные записи и необходимые журналы; отдельно проверьте, что резервную копию действительно можно восстановить.
• Воспроизведите проблему на тестовом объекте и сохраните результат до изменения, чтобы после выпуска сравнить одинаковые сценарии.
• Внесите минимальное изменение под системой контроля версий, опишите причину, ожидаемый эффект, ограничения и точный способ отката.
• Прогоните нормальный сценарий, ошибочный ввод, повтор одного запроса, два параллельных запроса и временную недоступность зависимости.
• Выпустите изменение на ограниченную долю трафика или один процесс, если архитектура это позволяет, и сравните метрики со старой версией.
• Только после стабильного наблюдения выполните контролируемое исправление исторических данных и сохраните итоговый отчёт.

Как проверить результат

Один успешный пример недостаточен. Проверьте основную операцию повторно, крайние значения, одновременные действия, перезапуск процесса и восстановление после краткого сбоя сети. Результат подтверждайте не только экраном пользователя, но и состоянием базы, очереди, внешнего сервиса и журналом аудита. Особое внимание уделите тому, что система делает при повторной доставке уже обработанного события.

Критерии приёмки сформулируйте до выпуска. Каждый пункт должен давать однозначный ответ «выполнено» или «не выполнено», а не субъективную оценку. Если тест невозможно повторить автоматически, оставьте короткий регрессионный чек-лист с тестовыми данными и ожидаемыми статусами.

• Cluster health становится green после завершения recovery.
• Allocation explain больше не содержит блокирующего decider для выбранного shard.
• Новые индексы получают корректное число replicas.
• Перезапуск одного узла не создаёт неожиданный длительный yellow сверх периода восстановления.
• Поиск и индексирование сохраняют приемлемую задержку во время rebalance.

Типичные ошибки при исправлении

• Удалять индекс, чтобы быстро получить green.
• Принудительно назначать stale primary, когда проблема только в replica.
• Навсегда отключать disk threshold.
• Ставить replicas 0 в production без принятия риска.
• Запускать массовый reroute без оценки сетевой и дисковой нагрузки.

Опаснее всего исправление, которое убирает заметный симптом ценой отключения проверки, ослабления прав или потери аудита. Такое изменение может сделать интерфейс «зелёным», но увеличить ущерб при следующем сбое. Если временный обход всё же необходим, ограничьте его срок, пользователей и область действия, добавьте мониторинг и заранее назначьте дату удаления.

Как предотвратить повторение

Профилактика строится вокруг явных контрактов, идемпотентных обработчиков, наблюдаемости и повторяемых релизов. Система должна не только корректно работать сейчас, но и быстро показывать нарушение правила после обновления, роста нагрузки или отказа интеграции. Ошибку, которая уже привела к потере времени, денег, данных или заявок, стоит закрепить автоматическим тестом.

Настройте мониторинг полного пользовательского пути, а не только доступности отдельных серверов. Техническая метрика должна быть связана с бизнес-результатом: заказ завершён, доступ выдан, файл восстановлен, событие обработано один раз, данные изолированы. Порог оповещения задавайте по нормальному профилю нагрузки и проверяйте, что уведомление содержит достаточно контекста для первого решения.

• Число unassigned replicas и возраст yellow.
• Disk usage относительно watermarks по каждому data path.
• Recovery bytes, throttling и длительность relocation.
• Количество shards на узел и средний размер shard.
• Изменения cluster settings и templates перед инцидентом.

Что подготовить для технического разбора

• Короткое описание ожидаемого и фактического поведения с точной последовательностью действий.
• Время возникновения, идентификатор тестового объекта и версии всех затронутых компонентов.
• Обезличенные фрагменты журналов до и после ошибки с единым correlation ID.
• Список последних изменений, результаты уже выполненных проверок и условия, при которых симптом исчезает.
• Безопасный доступ к тестовой среде либо минимальный пример, не содержащий паролей, токенов и персональных данных.

Частые вопросы

Работает ли поиск при yellow?

Обычно primary shards доступны, поэтому поиск работает, но запас отказоустойчивости снижен.

Можно ли поставить replicas 0?

Для одноузловой тестовой среды иногда да; для production это решение уменьшает устойчивость и требует осознанного согласования.

Нужно ли делать reroute вручную?

Сначала изучить allocation explain. Ручные команды нужны редко и могут быть опасны без точной причины.

Когда нужна помощь специалиста

Если Elasticsearch стал yellow, я могу безопасно разобрать allocation explain, диски, roles, filters и templates и предложить минимальное исправление. Для оценки нужны read-only health, unassigned shards и allocation explain без учётных данных.