Модуль Health Checker

Это документация VMmanager 6 для редакций Hosting и Infrastructure. Документация VMmanager для редакции ФСТЭК находится в разделе VMmanager 6 ФСТЭК.

Health Checker — утилита, которая отслеживает состояние Docker-контейнеров и сервисов платформы. Утилита помогает находить:

неработающие контейнеры и сервисы;
сервисы, которые не удалось сопоставить ни с одним контейнером (сироты, orphans).

Health Checker:

отслеживает состояние Docker-контейнеров — запущен, остановлен, перезапускается;
проверяет сервисы внутри контейнеров через supervisorctl;
сверяет сервисы контейнеров со службами, зарегистрированными в системе обнаружения сервисов Consul;
выводит собранные данные в виде таблицы в терминале;
работает из собственного контейнера и обращается к Docker через сокет.

Принцип работы

Чтобы получить информацию о состоянии системы, Health Checker:

Собирает данные о контейнерах.
Анализирует информацию о сервисах в контейнерах.
Сопоставляет информацию о контейнерах с данными в Consul.

Сбор данных о контейнерах

Health Checker получает список контейнеров из двух источников:

/opt/ispsystem/vm/config.json — из секции Patches декодируются блоки base64_compose;
/opt/ispsystem/vm/docker-compose.yaml — из файла берётся список сервисов Docker Compose.

Затем через Docker API по сокету Health Checker запрашивает актуальный список контейнеров с полными данными: сетевые настройки (NetworkSettings), состояние (State), статус (Status).

Анализ сервисов в контейнерах

Для каждого запущенного контейнера Health Checker выполняет команду supervisorctl status через docker exec и разбирает вывод, чтобы получить статус каждого сервиса: RUNNING, STOPPED, FATAL, BACKOFF.

Из конфигурации supervisor (/opt/supervisor.d/*.conf) Health Checker извлекает параметры --name, --port и --mode. Эти параметры используются для сопоставления сервиса со службой в Consul.

Сопоставление сервисов с Consul

Интеграция с Consul

Health Checker запрашивает два эндпоинта Consul API:

/v1/agent/services — список зарегистрированных служб;
/v1/health/state/any — результаты health-check по каждой службе.

На основе этих данных Health Checker сопоставляет сервисы контейнеров со службами Consul.

Регистрация ожидаемых идентификаторов

Для каждого сервиса, у которого в конфигурации supervisor задан параметр --name, Health Checker формирует два возможных идентификатора службы в Consul (ServiceID):

по имени и режиму: {consul_service_name}_{mode}_{short_container_id};
по IP-адресу и порту: {container_ip}_{port}.

Оба варианта Health Checker сохраняет во внутреннем словаре для последующего поиска.

Синхронизация с Consul

При получении данных от /v1/agent/services Health Checker ищет соответствие в следующем порядке:

Прямое совпадение — ServiceID из Consul найден среди идентификаторов, сформированных на предыдущем шаге. Это точное соответствие.
Совпадение по IP:Port — если ServiceID не найден, Health Checker сравнивает пару Address:Port из данных Consul с IP-адресом и портом контейнера.
Частичные сироты (container orphans) — служба в Consul имеет IP-адрес контейнера, но не сопоставлена ни с одним сервисом. Health Checker привязывает такую службу к контейнеру как "сироту контейнера": в таблице она отображается в строке этого контейнера с префиксом +. Если позже появится подходящий сервис, служба будет сопоставлена с ним.
Полные сироты (full orphans) — службы Consul, которые не удалось связать ни с одним контейнером. Health Checker показывает их отдельным блоком Consul orphans внизу таблицы.

Обновление статусов health-check

Через /v1/health/state/any для каждого сопоставленного сервиса Health Checker обновляет:

статус health-check — passing, warning, critical, maintenance;
вывод команды проверки (output) — например, HTTP POST http://172.18.0.10:200/health: 200 OK.

Отслеживание изменений

При изменении состояния контейнера (переход в RUNNING или из него) Health Checker перерегистрирует или удаляет его сервисы из системы сопоставления. Службы, которые пропали из Consul, Health Checker помечает статусом REMOVED.

Установка и запуск

Чтобы установить Health Checker, в правом меню нажмите значок → раздел Модули → модуль Health Checker → кнопка Установить.

Чтобы запустить Health Checker:

Подключитесь к серверу с платформой по SSH. Подробнее о подключении по SSH см. в статье Настройка рабочего места.
Выполните команду:
```
docker exec -it health_check check <parameters>
```
Пояснения
- health_check — имя контейнера Health Checker (задано параметром container_name в файле патча);
- check — команда запуска утилиты внутри контейнера;
- -it — флаги docker exec для интерактивного терминала. Нужны, чтобы Health Checker раскрашивал таблицу и в режиме непрерывного мониторинга работала прокрутка (см. раздел Непрерывный мониторинг);
- <parameters> — параметры запуска.

Параметры запуска

Параметр	Короткая форма	Описание
`--help`	`-h`	выводит справку по параметрам и завершает работу
`--full`	`-f`	включает полный режим отображения (см. раздел --full (полный режим))
`--watch`	`-w`	включает непрерывный мониторинг (см. раздел Непрерывный мониторинг)
`--containers CONTAINERS [CONTAINERS ...]`	`-c`	ограничивает вывод указанными контейнерами; имена перечисляются через пробел, например `-c vm_box consul`
`--problems`	`-p`	показывает только контейнеры с проблемами (см. раздел --problems)
`--no-orphans`	—	скрывает блок сирот Consul (см. раздел --no-orphans)
`--format {table, json}`	—	задаёт формат вывода: `table` (по умолчанию) или `json`

Параметр --format json выводит те же данные, что и таблица, в структурированном виде: сводку (summary) со счётчиками и списком проблем, список контейнеров с сервисами (containers) и список полных сирот (orphans). Формат json позволяет передавать результаты проверки во внешние системы мониторинга.

Пример JSON-ответа

Пояснения к JSON-ответу:

summary.problems — список проблемных сервисов и контейнеров, найденных за один запуск проверки;
containers[].services — сервисы supervisor внутри контейнера, при --full включает сервисы в статусе RUNNING;
containers[].container_orphans — частичные сироты, привязанные к этому контейнеру по IP-адресу (см. раздел Синхронизация с Consul);
orphans — полные сироты Consul, не привязанные ни к одному контейнеру.

Режимы отображения

Структура таблицы

Health Checker выводит таблицу с колонками:

Колонка	Описание
Name	имя контейнера и древовидный список его сервисов с префиксами `├──` и `└──`; сироты контейнера (см. раздел Синхронизация с Consul) показаны отдельными строками с префиксом `+`
State	статус контейнера (`running`, `exited`) или сервиса (`RUNNING`, `FATAL`)
Details	IP-адрес контейнера, uptime сервиса, PID
Consul	статус в Consul: `passing`, `warning`, `critical`, `not checked` и имя сопоставленной службы

Например, для контейнера vm_box Health Checker в полном режиме выводит:

┼─────────────────────┼─────────┼─────────────────────┼─────────────────────┼
│ Name                │ State   │ Details             │ Consul              │
┼─────────────────────┼─────────┼─────────────────────┼─────────────────────┼
│ vm_box              │ running │ Up 3 days           │                     │
│                     │         │ 172.18.0.13         │                     │
│ ├── checker         │ running │ pid 166  uptime 3   │ Status: passing,    │
│                     │         │ days Port: 2400     │ Name: checker_v3(…) │
│ ├──                 │ exited  │ Jul 28 02:40 AM     │  -                  │
│ rdns_auto_enabler   │         │                     │                     │
│ + gosockify         │ -       │ -                   │ Status: passing,    │
│                     │         │                     │ Name: gosockify(…)  │
┼─────────────────────┼─────────┼─────────────────────┼─────────────────────┼

В этом примере checker и rdns_auto_enabler — сервисы supervisor внутри контейнера vm_box (второй остановлен), а gosockify — сирота контейнера: служба Consul с IP-адресом контейнера vm_box, которую Health Checker не смог сопоставить ни с одним сервисом supervisor.

Цветовое кодирование

Health Checker раскрашивает строки таблицы по статусу:

зелёный — всё в порядке (RUNNING, passing);
жёлтый — предупреждения (WARNING, BACKOFF, not checked, частично работающие сервисы контейнера);
красный — проблемы (FATAL, CRITICAL, exited, NOT_FOUND для ожидаемых сервисов).

Режимы просмотра

По умолчанию Health Checker показывает сокращённый вывод. Полноту вывода можно изменить параметрами запуска.

--full (полный режим)

Параметр --full показывает все сервисы во всех контейнерах с полными идентификаторами Consul, включая сервисы в статусе RUNNING с проходящим health-check. Например, для контейнера auth команда check --full --containers auth выводит все три сервиса supervisor с их портами и Consul-идентификаторами, тогда как без --full Health Checker показывает только счётчик services: 3/3.

Short Mode (по умолчанию)

Без параметра --full Health Checker показывает только:

список контейнеров с количеством здоровых сервисов, например services: 6/6;
сервисы в статусе, отличном от RUNNING;
сервисы с непроходящими health-check в Consul.

--problems

Параметр --problems — более строгий фильтр: показывает только контейнеры, в которых есть хотя бы одна проблема.

--no-orphans

Параметр --no-orphans скрывает блок Consul orphans с полными сиротами. Используйте этот параметр, если полные сироты не относятся к контролируемым сервисам и не нужны для текущей проверки.

Непрерывный мониторинг

Параметр --watch переводит Health Checker в режим непрерывного наблюдения за состоянием системы.

Поведение в режиме watch

В режиме --watch Health Checker:

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

Что отслеживается в реальном времени

В режиме --watch Health Checker отслеживает:

появление и исчезновение контейнеров. Если контейнер пропал из списка запущенных, Health Checker помечает его статусом UNKNOWN;
изменение состояния контейнера — запуск, остановку, перезапуск;
изменение статуса сервисов supervisor, например, переход RUNNING → STOPPED → FATAL;
изменение health-check в Consul, например, переход PASSING → WARNING → CRITICAL;
потерю регистрации в Consul — сервис был зарегистрирован, но пропал из /v1/agent/services.

Управление выводом

Чтобы перемещаться по таблице, используйте мышь или клавиши:

j — строка вниз;
k — строка вверх;
d — страница вниз;
u — страница вверх;
g — в начало таблицы;
G — в конец таблицы.

Чтобы завершить работу утилиты, нажмите q.