Setup: Cluster Agent и проверки уровня кластера

Mon, 01 Jan 0001 00:00:00 +0000

На этой странице:

Назначение
Как устроено взаимодействие
Параметры в Helm-чарте
- Токен Cluster Agent
- Отказоустойчивость
Проверки уровня кластера
Admission Controller
Проверка работы

Назначение

В Kubernetes агент устанавливается в два вида подов:

Компонент	Тип ресурса	Задача
Агент на нодах (`protoobp`)	DaemonSet — по поду на каждой ноде	Метрики ноды и контейнеров, трейсы и логи приложений на этой ноде, проверки интеграций для подов ноды
Cluster Agent (`protoobp-cluster-agent`)	Deployment	Задачи уровня всего кластера, которые нельзя или не нужно выполнять на каждой ноде

Cluster Agent:

собирает метрики состояния объектов Kubernetes (Deployment, Pod, Node, Job и др.) — проверка kubernetes_state_core, параметр protoobp.kubeStateMetricsCore.enabled, по умолчанию включена;
собирает события Kubernetes (protoobp.collectEvents);
запрашивает API Kubernetes один раз за весь кластер и передаёт агентам на нодах метаданные (имена сервисов, теги подов), снижая нагрузку на API-сервер;
распределяет между агентами проверки уровня кластера;
обслуживает Admission Controller — автоматическое подключение трейсеров к подам.

Cluster Agent включён в Helm-чарте агента по умолчанию (clusterAgent.enabled: true) и устанавливается вместе с ним — см. Установка агента в Kubernetes.

Как устроено взаимодействие

Агенты на нодах подключаются к Cluster Agent через сервис Kubernetes по порту 5005/tcp.
Подлинность соединения подтверждается общим токеном.
Cluster Agent и агенты на нодах отправляют данные на ProtoOBP Backend независимо друг от друга, каждый по своему pobp_url.
API-сервер Kubernetes обращается к Admission Controller Cluster Agent по порту 8000/tcp.

Полный список сетевых портов — в разделе Установка агента в Kubernetes.

Обратите внимание

Переменные окружения из protoobp.env передаются только агентам на нодах. Параметры, которые нужны и Cluster Agent (например, прокси), продублируйте в clusterAgent.env.

Параметры в Helm-чарте

Основные параметры секции clusterAgent файла values.yaml:

Параметр	По умолчанию	Назначение
`clusterAgent.enabled`	`true`	Устанавливать Cluster Agent
`clusterAgent.image.name`, `clusterAgent.image.tag`	—	Образ Cluster Agent; тег совпадает с версией агента
`clusterAgent.replicas`	`1`	Число реплик
`clusterAgent.token`	—	Токен связи с агентами на нодах
`clusterAgent.tokenExistingSecret`	—	Имя существующего Secret с токеном (ключ `token`)
`clusterAgent.env`	`[]`	Переменные окружения Cluster Agent
`clusterAgent.confd`	`{}`	Конфигурации проверок уровня кластера
`clusterAgent.admissionController.enabled`	`true`	Admission Controller
`clusterAgent.resources`	`{}`	Запросы и лимиты CPU и памяти
`clusterAgent.createPodDisruptionBudget`	`false`	Создать PodDisruptionBudget
`clusterAgent.nodeSelector`, `tolerations`, `affinity`	—	Размещение пода
`protoobp.clusterChecks.enabled`	`true`	Проверки уровня кластера
`protoobp.kubeStateMetricsCore.enabled`	`true`	Метрики состояния объектов Kubernetes

Изменения применяются командой helm upgrade — см. Изменение параметров.

Токен Cluster Agent

Токен — общий секрет агентов на нодах и Cluster Agent, строка не короче 32 символов. Если clusterAgent.token и clusterAgent.tokenExistingSecret не заданы, чарт генерирует случайный токен при каждом helm upgrade, и все поды агента перезапускаются. Чтобы токен не менялся, задайте его явно — лучше через собственный Secret:

kubectl create secret generic protoobp-cluster-agent-token -n protoobp \
 --from-literal=token="$(head -c 32 /dev/urandom | base64 | tr -dc 'A-Za-z0-9' | head -c 32)"

clusterAgent:
 tokenExistingSecret: protoobp-cluster-agent-token

Отказоустойчивость

При clusterAgent.replicas: 2 и больше одна реплика выбирается ведущей и выполняет задачи уровня кластера, остальные находятся в резерве и подхватывают работу при её отказе. Для кластеров, где важна непрерывность сбора событий и метрик состояния, рекомендуется:

clusterAgent:
 replicas: 2
 createPodDisruptionBudget: true

Проверки уровня кластера

Когда использовать

Обычная проверка интеграции выполняется агентом той ноды, где работает под сервиса (см. Автообнаружение). Проверка уровня кластера (cluster check) выполняется один раз на весь кластер: Cluster Agent назначает её одному из агентов на нодах, а при выходе ноды из строя переназначает другому.

Такие проверки нужны для сервисов, которые не работают в подах кластера или не привязаны к конкретной ноде:

внешние базы данных и брокеры сообщений (управляемые облачные сервисы, отдельные серверы);
HTTP-, TCP- и TLS-проверки доступности адресов — см. Мониторинг сети;
сервисы за балансировщиком, которые нужно проверять один раз, а не с каждой ноды.

Настройка

Конфигурация задаётся в clusterAgent.confd: каждый ключ становится файлом в conf.d Cluster Agent. Обязателен параметр cluster_check: true — без него Cluster Agent не распределяет проверку.

protoobp:
 clusterChecks:
 enabled: true

clusterAgent:
 confd:
 postgres.yaml: |-
 cluster_check: true
 init_config:
 instances:
 - host: pg.db.corp.local
 port: 5432
 username: protoobp
 password: ENC[k8s_secret@protoobp/postgres-credentials/password]
 http_check.yaml: |-
 cluster_check: true
 init_config:
 instances:
 - name: Внешний портал
 url: https://portal.corp.local/health

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

Параметры каждой интеграции описаны на её странице в разделе Подключение технологий.

Отдельные исполнители проверок

По умолчанию проверки уровня кластера выполняют агенты на нодах. Если проверок много или они тяжёлые (например, запросы к крупным базам данных), их можно вынести в отдельный Deployment — исполнители проверок (cluster checks runners):

clusterChecksRunner:
 enabled: true
 replicas: 2

Тогда Cluster Agent распределяет проверки только между этими подами, а агенты на нодах занимаются только своими нодами.

Admission Controller

Admission Controller — веб-хук Kubernetes, который Cluster Agent регистрирует в кластере. При создании пода он может:

добавить в под переменные окружения для отправки трейсов и метрик агенту на той же ноде;
подключить трейсер приложения через init-контейнер без пересборки образа.

Подробно настройка описана на странице Автоматическое подключение трейсеров в Kubernetes. Основные параметры чарта:

Параметр	По умолчанию	Назначение
`clusterAgent.admissionController.enabled`	`true`	Включить веб-хук
`clusterAgent.admissionController.mutateUnlabelled`	`false`	Изменять поды без лейбла `admission.proto.group/enabled: "true"`
`clusterAgent.admissionController.configMode`	`hostip`	Как под находит агента: `hostip`, `service` или `socket`

Для работы веб-хука API-сервер Kubernetes должен иметь доступ к нодам по порту 8000/tcp.

Проверка работы

Команды выполняются в поде Cluster Agent:

# общее состояние, лидер, подключённые агенты
kubectl exec -it deploy/protoobp-cluster-agent -n protoobp -- protoobp-cluster-agent status

# распределение проверок уровня кластера по агентам
kubectl exec -it deploy/protoobp-cluster-agent -n protoobp -- protoobp-cluster-agent clusterchecks

# загруженные конфигурации проверок
kubectl exec -it deploy/protoobp-cluster-agent -n protoobp -- protoobp-cluster-agent configcheck

# журнал
kubectl logs deploy/protoobp-cluster-agent -n protoobp --since=1h

На агенте ноды, которому назначена проверка, она видна в выводе agent status (раздел Collector) и agent configcheck.

Частые проблемы:

Признак	Причина
В журнале агентов на нодах ошибки подключения или авторизации при обращении к Cluster Agent	Токены не совпадают — например, после `helm upgrade` без заданного токена перезапустились не все поды. Задайте постоянный токен
Проверка есть в `configcheck` Cluster Agent, но не назначена ни одному агенту	Не включены `protoobp.clusterChecks.enabled` или в файле нет `cluster_check: true`
Поды приложений не получают трейсер	Нет лейбла `admission.proto.group/enabled: "true"` на поде или API-сервер не достучался до порта `8000/tcp` — см. автоматическое подключение трейсеров

Общие команды и журналы агента — на страницах Команды и проверка работы и Журналы агента.

Документация Proto Observability Platform – cluster checks