Как работает агент

Агент Наблюдателя — один процесс, который работает рядом с вашим приложением: сервисом в Docker Compose, Deployment-ом в Kubernetes или службой systemd на сервере. Он собирает метрики, статусы и ошибки, маскирует персональные данные и отправляет всё в Наблюдатель по HTTPS.

Здесь собрано, к чему агент получает доступ, что он делает в вашем окружении, сколько потребляет и что уходит в облако. Прочитайте перед установкой в production.

#Один агент — три режима

Режим агент выбирает сам:

• запущен контейнером в compose-проекте — режим Docker Compose;
• запущен подом в кластере — режим Kubernetes;
• иначе — режим сервера (host).

Режим можно задать явно переменной NABL_MODE: auto (по умолчанию), compose, kubernetes или host. Один агент обслуживает одну цель — стек или сервер.

#Какие доступы нужны агенту

#Docker Compose

• Docker socket /var/run/docker.sock. Через него агент читает Docker API: список контейнеров, их параметры, статистику, логи и размер томов. Доступ к сокету Docker равносилен root на хосте — это свойство Docker, а не агента. Если это неприемлемо, поставьте docker-socket-proxy и укажите его адрес в NABL_DOCKER_HOST (tcp://…). В прокси разрешите чтение containers, info, system.
• Exec в контейнеры баз. Раз в 3 минуты агент выполняет в контейнерах баз короткий запрос только на чтение, чтобы узнать их размер (таймаут 40 секунд):

На MySQL с десятками тысяч таблиц такой запрос бывает тяжёлым. Отключить: NABL_DB_SIZE_PROBE: "false" в окружении агента (агент 0.8.1+). Пропадёт только размер баз. Для работы через docker-socket-proxy exec и POST нужны только для этой проверки.

• Видит только свой compose-проект — контейнеры с той же меткой com.docker.compose.project. Живые логи тоже доступны только по ним.

#Kubernetes

• Kube API, только чтение в своём namespace: get, list, watch на pods и pods/log; get, list на persistentvolumeclaims и metrics.k8s.io/pods. Отдельный ClusterRole — get, list на persistentvolumes, только чтобы узнать, где лежат тома.
• Exec в поды не делает. Ничего в кластере не создаёт и не меняет.
• Под без привилегий: не от root (uid 65532), файловая система только для чтения, без capabilities, seccomp RuntimeDefault, без hostPath, hostNetwork и privileged.

Подробнее о манифесте — в статье Мониторинг Kubernetes.

#Сервер

• Служба systemd от root в /opt/nabl-agent. Программа скачивается с nablops.io/releases.
• Читает /proc и /sys: CPU, память, PSI, диски, сеть, TCP-соединения, открытые файлы процессов.
• Каждый цикл читает сообщения ядра за последние сутки (journalctl -k, если его нет — dmesg), чтобы найти OOM.
• С версии 0.14 читает таблицы TCP-соединений контейнеров и подов своего сервера (/proc/<pid>/net/tcp): кто с каким адресом и портом соединён. По ним Наблюдатель рисует связи сервисов без трассировки. Содержимое трафика и имена процессов агент не читает и не отправляет, eBPF и дополнительные права не нужны.
• Ничего на сервере не меняет.

#Что агент не делает

• Не перезапускает, не останавливает и не меняет контейнеры, поды и тома.
• Не внедряется в приложения: никаких sidecar-контейнеров, admission webhook, CRD и DaemonSet. Образы и манифесты приложений не меняются.
• Не выполняет команды по запросу Наблюдателя. Канал управления позволяет только включить и выключить живые логи и живые метрики, когда вы открыли их в кабинете или через ИИ-ассистента.
• Не передаёт переменные окружения контейнеров, их метки, содержимое томов и баз.

Если агент упадёт или зависнет, перестанут приходить данные — и только. Приложения от агента не зависят. Если приложение шлёт трассы через OpenTelemetry SDK, а агент недоступен, SDK отбрасывает их в фоне и не задерживает запросы.

#Нагрузка на окружение

На небольшом namespace агент фактически тратит около 1m CPU и 5 МиБ памяти. С числом подов и объёмом логов и трасс потребление растёт. На больших стеках (десятки контейнеров, много трасс) лимит памяти можно поднять. Если агент превысит лимит, Docker или Kubernetes перезапустят только его.

Нагрузка на Kubernetes API: раз в 30 секунд — список подов и метрики, плюс чтение логов 4–16 контейнеров, не больше 2 МиБ за одно чтение. В Docker Compose — запросы к Docker API того же порядка: логи каждого контейнера просматриваются хотя бы раз в три цикла, размер томов — раз в 3 минуты.

#Сеть: какие порты и куда ходит агент

Исходящие соединения — только на адрес Наблюдателя https://app.nablops.io (порт 443):

• отправка данных раз в 30 секунд (NABL_INTERVAL);
• постоянный канал управления (WebSocket) — для живых логов и метрик.

Агент сервера при установке и обновлении скачивает программу с https://nablops.io. Сам агент обращается ещё только к адресам источников метрик, которые вы добавили в стек.

Входящие из интернета агенту не нужны.

Порты внутри сети стека (только у агента стека):

Эти порты работают без авторизации — слать на них может любое приложение в сети стека. Публиковать их наружу не нужно и не стоит. С агентом 0.8.1+ сжатый запрос на порт 4318 после распаковки ограничен 64 МиБ.

#Что уходит в облако

Полные логи контейнеров и подов не хранятся. Агент читает stdout/stderr и отправляет только распознанные ошибки, а также до 5 строк лога до и после каждой ошибки (агент 0.9.2+). Весь лог можно смотреть вживую, пока он открыт. Если логи нужно хранить и искать, отправляйте их как события и логи.

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

#Как маскируются персональные данные

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

Номера карт, ИНН и СНИЛС распознаются по контрольным суммам, поэтому случайные идентификаторы почти не задеваются. Ищутся они и внутри фраз: order created for ivan@mail.ru превратится в order created for i***@m***.ru.

Не маскируются: IP-адреса сервисов в тексте ошибок (dial tcp 10.0.0.8:5432 — без них сбой не разобрать) и ФИО в свободном тексте без имени поля.

С какой версии:

Более старые агенты отправляют ошибки и живые логи как есть — обновите агента.

Следствие для поиска: найти ошибку или строку лога по email или телефону нельзя — в облаке их нет. В событиях для этого есть поиск по точному значению: Наблюдатель сравнивает не само значение, а его псевдоним.

#Безопасность токена

• Токен агента показывается один раз при создании. В Наблюдателе хранится только его хеш, поэтому показать токен повторно нельзя — только выпустить новый.
• Токен действует только для агента: отправлять данные и получать его настройки, например список источников метрик стека. Войти с ним в кабинет или настроить проект нельзя.
• Не коммитьте токен в git: в Docker Compose вынесите его в .env, в Kubernetes он лежит в Secret nabl-agent. У агента сервера файл /opt/nabl-agent/.env доступен только root.
• Если токен утёк, выпустите новый — старый перестанет работать сразу. См. Обновление агента и токен.

#Образ агента

Образ — публичный velgir/nabl-agent на Docker Hub. Для production закрепите версию тегом (velgir/nabl-agent:0.14.1) или по digest (velgir/nabl-agent@sha256:…) вместо latest.

Совет. Хотите попробовать без риска — поставьте агента в staging или отдельный namespace, посмотрите на его потребление и права, затем решайте про production.

#Что дальше

• Мониторинг Docker Compose — установка в compose-проект.
• Мониторинг Kubernetes — манифест и права.
• Мониторинг сервера Linux — агент на сервере.
• Обновление агента и токен — версии и смена токена.