Статусы хоста и действия оператора

Статус показывает две независимые стороны работы хоста: когда Control Plane (CP) последний раз получил heartbeat и применил ли агент нужное поколение правил. Для диагностики нужно смотреть статус вместе с полями Last seen, Desired generation и Current generation.

Основные статусы

Статус	Что означает	Действие оператора
enrolling	Хост создан, но ещё не завершил первичный обмен сертификатами	Проверить токен, доверие к CA и доступность enrollment-порта
active	Heartbeat свежий; хост не превысил пороги ожидания нового поколения	Действий не требуется
pending	Агент на связи, но не подтвердил новое поколение за отведённое время	Сравнить поколения, открыть логи агента и проверить ошибку применения
stale	CP не получает heartbeat дольше порога	Проверить сервис агента, сеть и mTLS-соединение
degraded	Нужное поколение остаётся неприменённым дольше критического порога	Разобрать причину немедленно; хост может исполнять старые правила

Статус active не означает, что агент подключён в эту секунду. Он означает, что heartbeat ещё не устарел и CP не обнаружил длительного расхождения поколений.

Переходы зависят от heartbeat и поколений

enrolling ── успешный энролмент ──► active
                                      │
                    нет heartbeat     │ новое поколение не подтверждено
                    дольше порога     │ дольше порога
                         ▼            ▼
                       stale       pending
                         └──────┬─────┘
                                │ поколение не подтверждено
                                │ дольше критического порога
                                ▼
                             degraded

stale / pending / degraded ── связь и поколение восстановлены ──► active

CP проверяет переходы примерно каждые 30 секунд. Поэтому статус меняется не точно на границе порога, а на ближайшей проверке после неё.

Пороги настраиваются в qf-cp

Переменная	По умолчанию	Назначение
QF_STATUS_STALE_SECONDS	90	Сколько секунд CP ждёт heartbeat до статуса stale
QF_STATUS_PENDING_SECONDS	120	Сколько секунд живой агент может не подтверждать новое поколение до pending
QF_STATUS_DEGRADED_SECONDS	300	Сколько секунд расхождение поколений может сохраняться до degraded

QF_STATUS_DEGRADED_SECONDS должен быть больше QF_STATUS_PENDING_SECONDS, иначе промежуточный статус pending почти не будет виден. Полный список параметров находится в справочнике qf-cp.

enrolling: энролмент ещё не завершён

В статусе enrolling у хоста ещё нет рабочей mTLS-сессии, поэтому CP не может доставить ему политики. Нужно проверить:

1. доступность enrollment-порта с хоста;
2. срок действия и число применений enrollment-токена;
3. соответствие токена типу операции: bulk для нового хоста или single_host для существующей записи;
4. QF_ENROLL_CA, QF_ENROLL_CA_FINGERPRINT или QF_ENROLL_CA_FETCH;
5. журнал агента: journalctl -u qf-agent -n 100.

Подробная процедура приведена в гайде по энролменту.

pending: агент не подтвердил новое поколение

pending появляется, когда heartbeat остаётся свежим, но агент не применил новое поколение за QF_STATUS_PENDING_SECONDS. На странице хоста нужно сравнить:

• Desired generation — поколение, которое ожидает CP;
• Current generation — поколение, которое применил агент;
• Confirmed generation — поколение, прошедшее watchdog-подтверждение агента;
• системные события и журнал агента — причина отклонения бандла.

Синхронизация означает только точное равенство Current == Desired. Если Current < Desired, агент штатно отстаёт и CP может повторно доставить bundle. Если Current > Desired, поколения относятся к разным identity или нарушен протокол: CP не зажимает значение до desired, оставляет host в degraded и не отправляет меньший bundle. Host Detail показывает такое состояние как Diverged со всеми тремя числами.

Частые причины: отсутствующий интерфейс из QF_IFACES, превышение лимита правил, неразрешившийся hostset, ошибка eBPF или неудачная проверка подписи. Пока ошибка не устранена, агент продолжает исполнять last-good generation.

stale: heartbeat не приходит

stale означает, что CP не получал heartbeat дольше QF_STATUS_STALE_SECONDS. Диагностика идёт от процесса к сети:

sudo systemctl status qf-agent
sudo journalctl -u qf-agent -n 100

Затем проверяются DNS и доступность агентского gRPC-порта CP. Офлайн-хост остаётся в области действия селекторов. CP сохраняет для него нужное поколение, а агент получит его после восстановления соединения. До этого агент исполняет правила из last-good cache.

degraded: старые правила требуют немедленной проверки

degraded означает, что нужное поколение не применено дольше QF_STATUS_DEGRADED_SECONDS. Причиной может быть как длительная потеря связи, так и повторяющаяся ошибка применения. Для разбора используются те же проверки, что для pending и stale, но приоритет выше: хост может продолжать работать со старым набором правил.

После восстановления связи и применения нужного поколения CP возвращает статус active автоматически.

Удаление хоста отзывает его сертификаты

Штатный способ прекратить доступ хоста — Delete в Web UI или DELETE /hosts/{id}. CP отзывает активные сертификаты, разрывает поток агента и переносит запись в архив. Простая смена поля status через PATCH /hosts/{id} не заменяет отзыв сертификатов.

Значения needs_rebootstrap и revoked принимает API, но стандартный UI их не назначает и не показывает отдельными фильтрами. Для повторного подключения существующего хоста используется single_host-токен и процедура повторного энролмента.

Last seen обновляется без перезагрузки страницы

Web UI получает last_heartbeat_at, статус и текущее поколение через отдельный низкочастотный канал. По умолчанию CP отправляет такие обновления раз в 15 секунд; интервал задаёт QF_LIVENESS_INTERVAL.

Last seen — серверное время, когда CP принял heartbeat, а не время на часах агента. Отображение может отставать на сумму интервала записи heartbeat в БД и QF_LIVENESS_INTERVAL.