Основные типы уведомлений 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-manager2. Проверить состояние AgentRegistrar CR: kubectl get agentregistrar3. Агент автоматически переподключается каждые 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 будет недоступен, установка не сможет завершиться.
Если вы наблюдаете в логе следующие сообщения:
Проверьте, что нужный функционал действительно недоступен, выполнив команду:
В выводе команды должны присутствовать:
Если вывод отличается, выполните следующие действия:
в файл /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"
После чего обновите конфигурацию загрузчика:
Теперь перезагружаем сервер и проверяем логи host-agent. Установка k8s должна продолжиться.