Основные типы уведомлений host-agent

В этой статье представлены основные типы уведомлений host-agent'a, которые вы можете встретить при установке платформы.

Ложноположительные ошибки

В некоторых ситуациях host-agent логирует события с пометкой ERROR, которые возникают из-за штатных внутренних процессов (остановка agent, миграция между кластерами, race condition, запуск controller-runtime). Большинство таких событий зачастую разрешаются автоматически и не требуют от пользователя дополнительных действий.

Важно

Важно отметить, что если ошибка появляется единовременно — это ложноположительная ошибка.
Если она повторяется постоянно или не разрешается после перезапуска — это реальная проблема.

Группа 1: Ошибки при остановке/перезапуске агента (SIGTERM от systemd)

При перезапуске или остановке хоста agent получает SIGTERM и прерывается на любом этапе. Контекст отменяется, и agent логирует ERROR — но это штатное завершение.

№	Сообщение / Паттерн в логах	Ситуация	Почему не ошибка
1	client config load failed → stat /root/.byoh/config: no such file or directory	Первый запуск agent. systemd перезапустил процесс до завершения discovery/регистрации, kubeconfig ещё не создан. applyKubeConfig пытается загрузить kubeconfig и падает	Agent перезапускается автоматически. При следующем запуске регистрация завершится успешно. В логе видно: первый запуск без флагов → SIGTERM → перезапуск с флагами (--label role=master --zap-log-level 4) → регистрация проходит
2	certificate rotation failed → certificate rotation aborted	Agent ждёт момент ротации сертификата (таймер). Приходит SIGTERM → ротация abort-ится	Агент будет перезапущен systemd. При перезапуске ротация начнётся заново. Если cert свежий, таймер просто отложен
3	error creating machineinfo → context canceled	Agent только зарегистрировался и пытается создать MachineInfo. Приходит SIGTERM → контекст отменяется	MachineInfo будет создан при следующем запуске agent'a

Группа 2: Ошибки при миграции хоста между кластерами (cluster move)

Когда хост перемещается из одного кластера в другой, старый kubeconfig перестаёт быть валидным. Host-agent пытается работать со старым kubeconfig и получает cascade ошибок.

№	Сообщение / Паттерн в логах	Ситуация	Почему не ошибка
4	error getting ByoHost / Reconciler error → byohosts "..." not found	ByoHost CR удалён из старого кластера при move. Agent ещё reconciliit по старым credentials	ByoHost удалён намеренно в рамках миграции. Agent перезапустится с новым kubeconfig
5	failed to patch byohost → byohosts "..." not found	Аналогично: agent пытается патчить ByoHost, которого больше нет	Штатный процесс cluster move
6	failed to get byohost, events will not be recorded for certificate rotation → forbidden: User "agent:..." cannot get resource "byohosts"	Новый kubeconfig ещё не применён, RBAC для нового пользователя не создан. Старый kubeconfig уже не валиден	CertificateUpdater автоматически восстановит регистрацию. При перезапуске agent'a RBAC будет настроен корректно
7	Failed to watch → forbidden: cannot list resource "byohosts"	controller-runtime пытается watch за ByoHost, но RBAC ещё не готов	Временно. При перезапуске agent'a с новым kubeconfig RBAC будет настроен

Группа 3: Race condition при регистрации

№	Сообщение / Паттерн в логах	Ситуация	Почему не ошибка
8	Cannot register → server doesn't have config request for this host	Agent отправил CSR на registration server, но poll'ит статус слишком быстро — сервер ещё не сохранил запрос. Через 1 минуту (следующее discovery-окно) регистрация проходит успешно	Race condition между client polling и серверной обработкой CSR. Автоматически ретраится. Не требует действий

Группа 4: Стартап controller-runtime (инициализация k8s watch)

№	Сообщение / Паттерн в логах	Ситуация	Почему не ошибка
9	failed to get informer from cache → Timeout: failed waiting for *v1alpha1.Flag/MachineConfig/MachineInfo/ByoHost Informer to sync	controller-runtime запускает informers для watch за CR. API server медленный или перегруженный, и informer не успевает синхронизироваться в отведённый timeout	Стандартное поведение controller-runtime при медленном старте API server. Informer пересинхронизируется. Контроллеры продолжат работу

Сообщения-предупреждения (INFO-уровень, содержат слово "error"/"warning", но не являются проблемой)

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

Подгруппа 1: Компоненты Kubernetes ещё не установлены

Поскольку agent запускается до установки Kubernetes-компонентов (kubelet, containerd), запросы к ним неизбежно падают с executable not found.

№	Сообщение / Паттерн в логах	Ситуация	Почему не ошибка
10	Warning, error getting kubelet version: exec: "kubelet": executable file not found in $PATH	Agent пытается получить версию kubelet при сборе ComponentVersions, но kubelet ещё не установлен (хост не привязан к кластеру / нет Machine ref)	Норма на этапе регистрации. Kubelet появится только после bootstrap. Сообщение возникает в каждом reconcile до назначения узла в кластер
11	Warning, get containerd version failed - error creating containerd client: ...	Agent пытается подключиться к containerd, но он ещё не установлен (аналогично kubelet)	Норма на этапе регистрации. Containerd появится только после bootstrap

Подгруппа 2: Discovery — нормальное ожидание кластера

Discovery-агент работает в цикле: ожидает MIP-пакеты → закрывает окно → проверяет наличие кластера → повторяет. Сообщения "cannot find" — это результат проверки в момент, когда кластер ещё не обнаружен.

№	Сообщение / Паттерн в логах	Ситуация	Почему не ошибка
12	Cannot find any cluster in network, continue waiting	Discovery-окно закрылось, но MIP-пакеты от management-кластера не получены. Agent продолжит ждать в следующем цикле	Норма на старте agent'a, пока discovery-сервер не отправит MIP-пакеты. В логах пилота видно: 7 циклов ожидания, потом discovery прошёл успешно
13	Cannot find cluster in network, continue waiting	Аналогично, но с указанием целевого кластера (--target-cluster)	Норма, если агент ожидает определённый кластер по имени

Подгруппа 3: HardwareInfo — сбор информации о "железе"

Agent собирает hardware-информацию для заполнения ByoHost.Status.Capacity. Не все хосты имеют GPU, и не все компоненты доступны.

№	Сообщение / Паттерн в логах	Ситуация	Почему не ошибка
14	error while getting host memory info / error while getting host CPU cores count / error while getting partition usage info / error while getting supported GPU devices	gopsutil-библиотека не смогла собрать данные о ресурсах (например, /proc/meminfo недоступен, нет GPU)	Если сообщение появляется один раз при старте — это временная проблема доступа к системным файлам. Если GPU нет — сообщение "no GPU" норма

Подгруппа 4: Bootstrap — нормальное ожидание ресурсов

№	Сообщение / Паттерн в логах	Ситуация	Почему не ошибка
15	Machine ref not yet set	ByoHost ещё не привязан к Machine (контроллер не назначил хост в кластер). Agent ждёт назначения	Норма. Контроллер назначит хост, когда найдёт подходящую Machine
16	BootstrapDataSecret not ready	Секрет с bootstrap-данными (токен, CA) ещё не создан контроллером	Норма. Контроллер создаст secret, когда назначит хост в кластер
17	Config isn't ready yet	Kubeconfig для agent'a ещё не готов на стороне registration server	Норма. Agent автоматически poll'ит и получит kubeconfig, когда server его подготовит

Подгруппа 5: Certificate Rotation — нормальное ожидание

№	Сообщение / Паттерн в логах	Ситуация	Почему не ошибка
18	starting certificate rotation / waiting for certificate to be ready for renewal	Agent проверяет срок действия TLS-сертификата и готовит ротацию (за 20% до истечения)	Норма. Сертификат будет автоматически обновлён. Сообщение возникает в каждом reconcile
19	kubeconfig with updated certificate has been successfully generated, restarting agent	Сертификат успешно обновлён, agent перезапускается для применения нового kubeconfig	Норма. Агент автоматически перезапустится

Подгруппа 6: Reconciliation — спам в логах

№	Сообщение / Паттерн в логах	Ситуация	Почему не ошибка
20	Reconcile request received	Reconcile запущен (каждые 15 сек)	Спам. В production использовать --zap-log-level=info, чтобы подавить
21	reconcile normal	Reconcile прошёл без изменений	Спам. Повторяется каждые 15 сек
22	Add Network Info / Attach Host Platform details	Agent обновляет NetworkInfo и HardwareInfo в ByoHost	Спам. Происходит при каждом reconcile

Критические события - требуют вмешательства пользователя

№	Сообщение / Паттерн в логах	Суть проблемы	Что делать
23	Cannot register to management cluster (повторяется постоянно)	Агент не может зарегистрироваться в кластере управления. Возможные причины: нет discovery-сервера, сервер регистрации недоступен, сеть некорректно настроена	1. Проверить, что discovery-сервер (порт 30001 UDP) активен на управляющем узле 2. Проверить сетевое соединение между узлом и management-кластером 3. Убедиться, что firewall не блокирует UDP-порты 30001/30002 4. Проверить разрешение ARP-трафика между узлами
24	client config load failed → no such file or directory (повторяется после перезапуска)	Kubeconfig не найден — агент не завершил регистрацию или файл поврежден	1. Дождаться завершения discovery-процесса (до 60 сек) 2. Проверить права доступа к /root/.byoh/ 3. Перезапустить agent: systemctl restart host-agent
25	Certificate rotation failed (без причины "certificate rotation aborted")	Не удалось обновить TLS-сертификат агента. Возможные причины: CSR отклонен, registrar-контроллер упал	1. Проверить логи baremetal-controller-manager 2. Проверить состояние AgentRegistrar CR: kubectl get agentregistrar 3. Агент автоматически переподключается каждые 5 секунд
26	error in bootstrapping k8s node	Критическая ошибка при bootstrap узла Kubernetes. Узел НЕ будет добавлен в кластер	1. Проверить наличие bootstrap-секрета в ByoHost 2. Проверить состояние узла: kubectl describe byohost <hostname> 3. Валидация хоста должна быть пройдена (см. раздел "Валидации")
27	error executing installation script	Скрипт установки Kubernetes-компонентов упал	1. Проверить доступность bundle-репозитория 2. Проверить дисковое пространство 3. Проверить состояние byohost: kubectl describe byohost <name>
28	problem running manager	Менеджер контроллеров упал. Агент неработоспособен	1. Перезапустить agent 2. Проверить системные ресурсы (CPU/RAM)
29	got unexpected error while bootstrapping / failed to deserialize Bootsman bootstrap config / failed to prepare Bootsman bootstrap flow	Ошибка в процессе bootsman-bootstrap (BKE). Узел не будет добавлен в кластер	1. Проверить ByoHost conditions: kubectl describe byohost <name> 2. Проверить logs bootsman-agent 3. При необходимости перезапустить agent
30	clean k8s directories failed / error cleaning up k8s directories, please delete it manually	Очистка каталогов /run/kubeadm/* и /etc/cni/net.d/* не удалась. Bootstrap не может продолжиться	1. Удалить каталоги вручную: rm -rf /run/kubeadm/* /etc/cni/net.d/* 2. Перезапустить agent
31	server cannot process request	HTTP-запрос к registration server завершился с кодом != 200	1. Проверить регистрацию на management-кластере 2. Проверить logs registration server

Важные события

№	Сообщение / Паттерн в логах	Суть	Что делать
32	too many clusters in network, cannot select from N	Агент нашел >1 management-кластер в сети	Указать целевой кластер явно: --target-cluster <name> --registration-server <address>
33	Validation <name>: Status: FAIL	Валидация узла не пройдена (например: CPU < 2 cores, RAM < 4GB, нет GPU, insufficient disk space). Узел не будет назначен в кластер	1. Посмотреть список валидаций: kubectl describe byohost <name> 2. Убедиться, что хост соответствует минимальным требованиям 3. Валидации повторяются каждые --validation-interval (по умолчанию 1 мин)
34	kubeadm not found on the target host, skipping node reset	При очистке узла kubeadm не найден. Может означать, что узел не был корректно разбутстраппен	Проверить состояние узла: kubectl get node, kubectl describe byohost <name>
35	install and uninstall script <name> not found / InstallScriptExecutionFailed	Скрипт установки не найден или упал	Проверить secret с установочным скриптом: kubectl get secret <name> -o yaml
36	error parsing Uninstallation script / error executing Uninstallation script	Ошибка при удалении хоста из кластера	1. Проверить uninstall-скрипт 2. Вручную выполнить kubeadm reset
37	cannot create patch helper / failed to patch byohost	Ошибка обновления ByoHost в кластере	Проверить API server и RBAC. При перезапуске agent'a обычно разрешается
38	agent was deleted, cleaning up	ByoHost CR удалён из кластера. Agent начинает cleanup	1. Проверить, кто удалил ByoHost (kubectl get byohost <name>) — если on-delete — это штатное поведение 2. Agent выполнит uninstall-скрипт и удалит kubeconfig

Информационные оповещения — норма, можно игнорировать

№	Сообщение / Паттерн в логах	Пояснение	Рекомендации
39	Waiting for management cluster in network	Агент ожидает discovery-пакеты. Норма на старте	Не требует действий. Ожидание до 60 сек (настраивается --discoveryWaitWindow)
40	Found new cluster in network, waiting till window will be closed	Агент получил MIP, ожидает закрытия окна	Норма. После закрытия окна — регистрация
41	Start listening MIPs	Агент открыл UDP-порт для discovery	Норма
42	Validation <name>: Status: PASS	Валидация пройдена	Норма
43	k8s node successfully bootstrapped	Узел успешно добавлен в кластер	Норма
44	cleaning up directory /run/kubeadm/* / cleaning up directory /etc/cni/net.d/*	Очистка каталогов перед bootstrap	Норма

DEBUG-логи (LEVEL(-2), LEVEL(-4) — появляются только при --zap-log-level=4)

№	Сообщение / Паттерн в логах	Пояснение	Рекомендации
45	Received packet from server / Successfully read from server	Детали работы discovery UDP-сокета	Игнорировать. Появляются только с --zap-log-level=4
46	Cluster already known, waiting till window will be closed	Агент повторно получает MIP от того же кластера	Игнорировать. Появляются только с --zap-log-level=4

Рекомендации по настройке логирования

При штатной установке используется уровень логирования info, в случае поиска проблем можно переключить режим работы на более деталезированные логи установки host agent'а:

Параметр	Значение	Эффект
--zap-log-level	info (по умолчанию debug при --zap-devel=true)	Подавит debug-сообщения discovery/reconcile
--zap-log-level	error	Покажет ТОЛЬКО критические ошибки
--zap-log-level	4	Максимальная детализация (LEVEL(-4))

Рекомендация для штатной установки: использовать --zap-log-level=info

Для поиска проблем: временно использовать — --zap-log-level=4

Краткий чек-лист для пользователей:

Критично:

  □ "Cannot register to management cluster" → проверить сеть и discovery-сервер
  □ "client config load failed" (повторяется) → проверить kubeconfig, перезапустить agent
  □ "Certificate rotation failed" (не aborted) → проверить registrar, controller-manager
  □ "error in bootstrapping k8s node" → проверить byohost conditions
  □ "error executing installation script" → проверить bundle-репозиторий

Важно:

  □ "too many clusters in network" → указать --target-cluster
  □ Validation FAIL → проверить соответствие хоста требованиям
  □ "kubeadm not found... skipping node reset" → проверить состояние узла

Норма:

  □ "Waiting for management cluster in network"
  □ "Cannot find any cluster in network"
  □ "Reconcile request received" / "reconcile normal"
  □ "Machine ref not yet set" / "BootstrapDataSecret not ready"
  □ "Config isn't ready yet"
  □ "starting certificate rotation"
  □ "client config load failed" (один раз, потом регистрация прошла)
  □ "certificate rotation failed" → "certificate rotation aborted"
  □ "error creating machineinfo" → "context canceled"
  □ "byohosts ... not found" / "forbidden" (после cluster move)
  □ "failed to get informer from cache" → "Timeout"
  □ "server doesn't have config request for this host"
  □ "Warning, error getting kubelet version" (до bootstrap)
  □ "Warning, get containerd version failed" (до bootstrap)

Ошибка missing required cgroups

Внимание

Данный раздел описывает решение проблемы для RedOS. В случае возникновения проблемы на других OS обратитесь в техническую поддержку боцмана.

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

Если вы наблюдаете в логе следующие сообщения:

[ERROR SystemVerification]: missing required cgroups: cpu

Проверьте, что нужный функционал действительно недоступен, выполнив команду:

    cat /sys/fs/cgroup/cgroup.controllers

В выводе команды должны присутствовать:

cpuset cpu io memory hugetlb pids misc

Если вывод отличается, выполните следующие действия:

в файл /etc/default/grub в параметр GRUB_CMDLINE_LINUX допишите через пробел два параметра

• systemd.unified_cgroup_hierarchy=1
• cgroup_no_v1=all

Пример правильно сформированной строки:

GRUB_CMDLINE_LINUX="resume=/dev/mapper/ro_redos-swap rd.lvm.lv=ro_redos/root rd.lvm.lv=ro_redos/swap rhgb quiet systemd.unified_cgroup_hierarchy=1 cgroup_no_v1=all"

После чего обновите конфигурацию загрузчика:

grub2-mkconfig -o /boot/efi/EFI/redos/grub.cfg

Теперь перезагружаем сервер и проверяем логи host-agent. Установка k8s должна продолжиться.