Версия: 8.6

Управление агентами

Основная информация

Агент — это специальная программа, которую можно установить на удаленное устройство с целью сбора данных и выполнения каких-либо действий (полный список поддерживаемых платформ).

Агент получает задания от сервера Monq, выполняет их и собранную информацию передает по защищенному сетевому протоколу на сервер.

Задания могут быть самого разного рода: запустить bash или PowerShell - скрипт, обратиться к HTTP REST интерфейсу, выполнить запрос к СУБД.

Для ускорения работы и упрощения написания заданий для агентов, используются плагины.
Плагины бывают как встроенные (например, плагин для работы с HTTP или плагины работы с наиболее популярными версиями СУБД), так и устанавливаемые на агенте отдельно (например, для сбора данных из Zabbix).

Также следует отметить, что мы предоставляем возможность разрабатывать собственные плагины самостоятельно, что бывает полезно в ряде случаев. Например, написать кастомный плагин для взаимодействия со специфической системой бронирования билетов.
Инструкция по написанию плагинов (github).

Подключение агентов к платформе Monq осуществляется через координатор по HTTPS протоколу, используя API-ключ для авторизации.

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

Основные возможности агентов:

Обработка поступающих сценариев заданий
Генерация результирующего артефакта и отправка его в потоки данных
Прямой запуск команд взаимодействия с консолью ОС (sh, bash, windows command, powershell)
Запуск параллельного выполнения нескольких заданий
Подключение плагинов интеграций, таких как Zabbix, Kubernetes, vCenter, PostgreSQL, SCOM, Nagios и другие

По умолчанию все задания выполняются на системном агенте

Системный агент получает задания от системного координатора, имеющего метку SharedAgents

Подключение внешних агентов к системному координатору недоступно

Экран «Управление агентами»

Экран управления агентами и координаторами находится в разделе главного меню «Сбор данных (ETL)» → «Управление агентами» и содержит следующие вкладки:

Координаторы
Агенты

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

Доступ к экрану регулируется ролевой моделью: права зависят от назначенной пользователю роли.

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

Координаторы

На вкладке «Координаторы» пользователю доступны следующие возможности:

Просматривать список с уже созданными координаторами
Выполнять действия с координаторами из списка
Перейти в карточку координатора
Создать новый координатор
Поиск координаторов в списке
Фильтрация координаторов в списке

Список координаторов

На вкладке «Координаторы» представлена таблица со списком существующих координаторов. Таблица имеет следующие поля:

Название: рядом с названием расположена иконка-индикатор активности координатора
Метки: рядом с названием метки присутствует иконка , говорящая о принадлежности метки координатору. Также отображается числовая индикация общего количества меток координатора. Клик по ней раскрывает список всех меток.
API-ключ
Состояние: одновременно отображает текущее состояние ВКЛ/ВЫКЛ и позволяет его переключить

Системный координатор в списке не отображается

Поиск координаторов

Для быстрого поиска и фильтрации координаторов пользователю доступны 2 инструмента, способных работать в паре:

Строка поиска
Позволяет фильтровать список по полям «Имя», «Описание» и «API-ключ»
Рубрикатор
Предоставляет возможности фильтрации по параметрам:
- Состояние: запущен или остановлен
- Метки: отображается до 5 меток текущего контекста (с возможностью развернуть полный список или найти через строку поиска)

Между собой блоки рубрикатора связаны логическим «И», что позволяет комбинировать фильтры для более точного поиска.
Рядом с каждым выбранным параметром отображается количество координаторов, соответствующих фильтру.

Создание координаторов

Нажмите в верхнем правом углу экрана «Создать координатор».
Заполните поля:
- Владелец
- Название координатора
- Добавьте метки
  Метки используются для распределения заданий потоков данных между координаторами
  При добавлении метки на координатор, она автоматически присваивается всем подключенным к нему агентам.
  при добавлении метки SharedAgents к созданному координатору
  планировщик распределит запуск заданий с меткой SharedAgents (установленной по умолчанию) также и на подключенные агенты.
  При подключении агента, координатор также запоминает и хранит в себе набор персональных меток всех подключенных к нему агентов.
Нажмите «Создать»

Готово, новый координатор создан, API-ключ для подключения агентов скопирован в буфер обмена.

Настройка координаторов

Для управления настройками координаторов необходимо перейти в карточку одного из них, кликнув по нему в общем списке.

В верхней части карточки пользователю отображается:

«Хлебные крошки» с возможностью вернуться на вкладку «Координаторы»
Название координатора с иконкой-индикатором состояния: «Запущен» / «Остановлен»
API-ключ (с возможностью копирования)
Количество активных агентов координатора с возможностью перехода к ним
При переходе откроется вкладка «Агенты» с выбранным координатором и состоянием «Запущен» (даже если агентов 0)
Управление состоянием
Дополнительные действия , такие как остановка координатора, копирование API-ключа, перевыпуск API-ключа и удаление координатора

Основная информация

Владелец: выбирается из списка РГ, в которых у пользователя есть право на редактирование раздела «Координаторы агентов»
Название: должно быть уникальным в рамках РГ
Описание
Метки: позволяют назначать координатору собственные идентификаторы, которые автоматически распространяются на все подключенные к нему агенты, обеспечивая их удобную идентификацию и фильтрацию.
Особенности работы с метками:
- Добавление меток возможно из списка уже доступных в контексте владельца координатора или создание собственных уникальных меток
- Метки чувствительны к регистру: «Метка» и «метка» - считаются разными
- Нельзя добавить одинаковую метку дважды на один координатор
- При смене РГ координатора уже назначенные метки сохраняются
- Установленные на координаторе метки автоматически наследуются всеми подключенными к нему агентами
- Чтобы метка добавилась, после ее ввода нажмите Enter или пробел
- Чтобы добавить метку с пробелом в названии, используйте copy-paste

Для удаления метки просто снимите её в интерфейсе, после чего она перестанет применяться к координатору и его агентам.

Конфигурации агентов

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

Конфигурация распределяется на агент по аналогии с заданиями, однако выполняется непрерывно, занимая слот агента.

Все изменения применяются динамически, без перезапуска агентов

Создание новой конфигурации

Нажмите «Создать конфигурацию»
После создания конфигурация сразу появляется в списке и отрывается боковая панель с настройками:
- Состояние конфигурации — по умолчанию выключено
- Название — автоматически присваивается «Новая конфигурация агента [N]», где N — порядковый номер новой конфигурации. Название должно быть уникальным в пределах одного координатора
- Описание — произвольный текст для удобства идентификации
- Метки агентов — определяют, каким агентам будет выдаваться конфигурация
  - «Агент содержит любую метку из списка» - применяется логический оператор «ИЛИ»
  - «Агент содержит все метки из списка» - применяется логический оператор «И»
    - Если агент имеет все указанные метки + еще какие-то - он все равно получит такую конфигурацию
    - Если хоть одна метка не существует - конфигурация не будет выдана т.к. агент не найдется
  - Несуществующая метка помечается особым образом, и при сохранении пользователь увидит предупреждение
  - Такая метка может стать валидной, если впоследствии подключится агент с этой меткой
  - Можно указать одну или несколько меток
  - Метки чувствительных к регистру
- Содержимое файла конфигурации - YAML-скрипт, который определяет логику работы на стороне агента. По умолчанию пустой. Доступна проверка корректности заполнения с точки зрения синтаксиса YAML
По завершении настройки сохраните конфигурацию

Сразу после сохранения новая конфигурация отображается в конце списка. При обновлении страницы конфигурации сортируются по алфавиту

Запуск и остановка координаторов

После создания нового координатора он переходит в состояние «Запущен» автоматически. Координатор сразу начинает распределять задания на подключенные к нему агенты.

Запуск и остановка могут выполняться как из общего списка координаторов, так и из личной карточки одного из них.

Кнопка запуска в списке координаторов находится в столбце «Состояние», а в личной карточке - в правом верхнем углу экрана.

При остановке работы координатора

агенты останутся подключенными к нему, но задания на них распределяться больше не будут

Перевыпуск API-ключа

Перевыпуск API-ключа доступен как из общего списка координаторов, так и из личной карточки одного из них.

Кнопка перевыпуска находится в меню дополнительных действий → «Перевыпустить API-ключ»

После перевыпуска API-ключа

все подключенные к координатору агенты потеряют связь с системой, для их подключения необходимо будет заменить API-ключ в конфигурациях агентов на новый

Удаление координаторов

Удаление координатора доступно как из общего списка координаторов, так и из его личной карточки.

Кнопка удаления находится в меню дополнительных действий → «Удалить»

при удалении координатора

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

Агенты

Список агентов

На вкладке «Агенты» представлена таблица со списком существующих агентов. Таблица имеет следующие поля:

Название: рядом с названием расположена иконка-индикатор активности агента
Тип: статический/динамический
IP-адрес
Координатор
Метки: рядом с названием метки присутствует иконка, говорящая о типе конфигурации. Также отображается числовая индикация общего количества меток агента. Клик по ней раскрывает список всех меток.
Конфигурации
Слоты

Поиск агентов

Для быстрого поиска и фильтрации агентов пользователю доступны 2 инструмента, способных работать в паре:

Строка поиска
Позволяет фильтровать список по полям «Имя», «Описание» и «API-ключ»
Рубрикатор
Предоставляет возможности фильтрации по параметрам:
- Состояние: запущен или остановлен
- Тип: статический или динамический
- Координатор, к которому подключен искомый агент
- Метки: отображаются личные метки агентов, а также метки координаторов с отличительной иконкой
- Конфигурации: отображаются конфигурации агентов с соответствующими их типу отличительными иконками

Между собой блоки рубрикатора связаны логическим «И», что позволяет комбинировать фильтры для более точного поиска.
Рядом с каждым выбранным параметром отображается количество агентов, соответствующих фильтру.

Состояние подключенных агентов

Чтобы увидеть подключенные, на текущий момент, агенты к координатору, выполните следующие действия:

Перейдите через основное меню в раздел Сбор данных → Агенты
Откройте вкладку Агенты
На вкладке Агенты отображается информация о подключенных к координатору агентах:
- Последний контакт – время, когда агент был активен
- Название агента – имя агента, указанное в конфигурационном файле агента
- Тип – Динамический или Статический (подробнее о типах агентов)
- Состояние – Активен или Недоступен
- Версия – версия подключенного агента
Цифра возле названия вкладки информирует о количестве подключенных агентов к координатору.

Статические агенты, которые не активны в данный момент – могут быть удалены из списка подключенных к координатору.

Чтобы удалить эти агенты, нажмите кнопку Удалить расположенную следом за версией агента.

Состояние выполнения заданий

Для просмотра информации о назначенных для выполнения заданиях на координаторе, выполните следующие действия:

Перейдите через основное меню в раздел Сбор данных → Агенты.
Откройте вкладку Задания.
На вкладке Задания отображается информация о назначенных для выполнения заданий из шаблона конфигурации потока данных:
- Последний запуск – время последнего запуска задания на агенте
- Последний статус – статус выполнения последнего задания на агенте
- Владелец задания – поток данных, которому принадлежит задание
- Название – название задания в шаблоне конфигурации потока данных
- Метки – информация о метках, связывающих координатор с заданием шаблона конфигурации
Произведите сортировку списка заданий по полям:
- Последний запуск
- Последний статус
- Владелец задания
- Название

Поиск на вкладке Задания осуществляется по полям: Название и Владелец задания.

Подключение агента

Перед подключением агента его необходимо загрузить и произвести конфигурацию.

Загрузка агента

Агенты Monq доступны для загрузки по следующим ссылкам:

Агент для Windows

Агент для Linux

Для подключения агента необходимо иметь API-ключ координатора. Если координатор не создан вернитесь к его созданию.

Агент подключается к координатору Monq по протоколу HTTPS (SignalR) c указанием API-ключа и базового URL системы.

Установка в Linux

Создайте рабочую директорию для агента и перейдите в нее:
```
mkdir -p /opt/monq-agent && cd /opt/monq-agent
```

Загрузите актуальную версию monq-agent:

wget https://downloads.monq.ru/tools/monq-agent/latest/linux-x64/monq-agent.zip

Разархивируйте загруженный архив в текущую директорию:
```
unzip monq-agent.zip && rm -f monq-agent.zip
```
Сделайте двоичный файл monq-agent исполняемым:
```
chmod +x ./monq-agent
```

Установите зависимости libicu, совместимой с вашей версией Linux:

CentOS/RHEL
```
yum install libicu
```

Debian/Ubuntu

# найти актуальную версию
apt search '^libicu[0-9]*$'

# выполнить установку найденной версии, например 66
apt install libicu66

Далее произведите настройку конфигурационного файла

Установка в Windows

Загрузите актуальную версию monq-agent.
Извлеките содержимое архива в папку, например: C:\monq-agent\monq-agent.exe.
Далее произведите настройку конфигурационного файла

Конфигурация агента

Создайте в директории с исполняемым файлом файл конфигурации monitoring-agent.conf, следующего содержания:

# Базовый URI системы Monq
BaseUri="https://monq.domain.com"
# API-ключ координатора для авторизации агента
ApiKey="fc63b95b-0393-430a-b8d0-46a8c4813675"
FileStorage=""
Timeout=100
[Plugins]
CSharpPath="/opt/monq-agent/plugins"
[Connection]
Timeout=100
RetryCount=12
[Agent]
Description=""
SlotsCount=2

Полное описание параметров конфигурации агента смотрите в таблице:

Параметр конфигурации	Описание	Обязательный параметр	Значение по умолчанию
BaseUri	Базовый URL системы (https://monq.domain.com)	да	нет
ApiKey	API-ключ координатора для авторизации агента	да	нет
FileStorage	Путь к хранилищу файлов	нет	нет
Timeout	Таймаут выполнения заданий, в секундах	нет	100
[Plugins]	Секция управления плагинами
CSharpPath	Путь к директории с плагинами агента	нет	нет
Autoload	Автозагрузка плагинов с хранилища	нет	false
[Connection]	Секция управления настройками подключения
Timeout	Таймаут на установку соединения, в секундах	нет	30
RetryCount	Количество попыток установки соединения	нет	12
[Agent]	Секция конфигурации агента
Name	Название агента	нет	нет
Description	Описание	нет	нет
SlotsCount	Количество слотов для выполнения заданий	нет	2
Labels:1-N	Персональная метка агента с порядковым номером от 1 до N	нет	2
[WorkConfigs]	Секция настройки "рабочих" конфигураций
Path	Путь к "рабочим" конфигурациям	нет	нет
[Serilog:MinimumLevel]	Секция настройки уровня логирования
Default	Уровень логирования	нет	Information
[Buffer]	Секция настройки буфера (только при использовании рабочих конфигураций)
BufferPath	Путь к директории, в которой хранить буфер приема	нет	нет
BufferTotalLimitSize	Максимальный размер выделяемой памяти на диске для хранения очереди, в байтах	нет	134217728
FlushTime	Частота отправки файлов очереди	нет	"00:00:01"
MaxChunksInMemory	Максимальное количество порций для отправки в систему за одну операцию	нет	128
BacklogMemoryLimit	Лимит размера всех порций	нет	5242880

Рабочие конфигурации агентов

Начиная с версии агента 2.1.0 появилась возможность настройки непрерывного выполнения заданий на агенте. Это удобно для прослушивания TCP/UDP портов, приема логов в формате syslog и других подобных задач.

Настройка таких заданий выполняется при помощи рабочих конфигураций агента.

Формат, используемый в файлах рабочих конфигураций - YAML.

Каталог хранения рабочих конфигураций задается в основном конфигурационном файле в секции [WorkConfigs], параметр Path. При запуске агента считываются все конфигурационные файлы *.yaml и *.yml в указанном каталоге.

Для каждой рабочей конфигурации требуется выделение 1 слота агента. Если количество слотов на агенте будет меньше, чем количество конфигураций, часть конфигураций будет проигнорирована.

Пример файла рабочей конфигурации агента:

continuous-jobs:
  - init-step:
      plugin: tcp
      with:
        listen: 0.0.0.0
        port: 5170
        separator: \n
        bufferType: memory
        bufferInputName: tcp.job1
        bufferSize: 20
        chunkSize: 20
        format: none
        streamKey: "ключ потока"

На текущий момент имеются следующие встроенные плагины для настройки рабочих конфигураций: tcp, udp, syslog.

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

Персональные метки агентов

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

В файле конфигурации можно добавить любое количество персональных меток в формате:

...
[Agent]
# Название
# Name="monq-agent-hostname"
# Описание
# Description=""
# Количество слотов для выполнения заданий
# SlotsCount=2
# Метки агента
Labels:1 = "Agent2"
Labels:2 = "GeneralLabel"
...

После подключения агента к координатору, все указанные метки будут доступны для выбора в поле «Агент» в задании потока данных.

Типы агентов

Агент может быть сконфигурирован как статический или динамический:

Статические агенты - это агенты, состояние которых контролирует координатор. При подключении статического агента координатор регистрирует его в списке подключенных агентов и контролирует его состояние.
Динамические агенты - видны в системе до тех пор, пока они активны. При отключении динамического агента, он пропадает из списка подключенных к координатору.

Для управления типом агента, служит параметр конфигурации Name - название агента:

Если параметр Name не задан - координатор устанавливает агенту тип динамический и присваивает автоматически сгенерированное название.
Если параметр Name задан - координатор устанавливает агенту тип статический и регистрирует его с заданным названием.

⚠️ Подключение нескольких агентов с одинаковыми названиями недопустимы. Названия агентов при подключении проверяются в рамках пользовательского пространства.

Подключение плагинов

Плагины доступны для загрузки по ссылке.

Для подключения плагина к агенту, извлеките архив с плагином в директорию, указанную в конфигурационном файле агента (CSharpPath=/opt/monq-agent/plugins).

Информацию по настройке плагинов можно найти по ссылке.

Начиная с версии Monq 8.3.0 плагины на агенты могут загружаться автоматически. Для включения этой опции необходимо добавить параметр Autoload со значением True в секции "[Plugins]".

Автоматическая загрузка плагинов на агент работает следующим образом: При получении нового задания, агент проверяет наличие необходимого плагина в указанной в файле конфигурации директории CSharpPath (например, /opt/monq-agent/plugins). Если в директории нужный плагин есть - задание выполняется. Если нужного плагина в директории нет - агент запросит плагин из хранилища (при условии, что включен параметр Autoload=True), сохранит его в свою директорию CSharpPath и без перезапуска продолжит исполнение полученного задания.

Запуск

Поддерживаемые команды

start - Запуск агента.

Использование: monq-agent [options] start

Параметры запуска:

--config <config> - путь к конфигурационному файлу, по умолчанию конфигурационный файл monitoring-agent.conf.
--insecure - не использовать проверку SSL сертификата, по умолчанию выключено.
-?, -h, --help - показать справку.

Запуск агента в Linux
Запуск агента в Windows
Запуск агента в Kubernetes

Запуск в Linux

Для запуска агента в качестве сервиса необходимо в директории /etc/systemd/system/ разместить файл конфигурации monq-agent.service:

Пример конфигурации для запуска службы от имени суперпользователя:

[Unit]
Description=Monqlab Agent Service
Documentation=https://docs.monq.ru/

[Service]
Type=notify
WorkingDirectory=/opt/monq-agent
ExecStart=/opt/monq-agent/monq-agent start --config /opt/monq-agent/monitoring-agent.conf
StandardOutput=syslog
User=root

[Install]
WantedBy=multi-user.target
Alias=monq-agent.service

Пример конфигурация для обычного пользователя

Создание пользователя и назначение владельцем директории с monq-agent

useradd --no-create-home --shell /bin/false -d /opt/monq-agent monq
chown -R monq:monq /opt/monq-agent 

Пример конфигурации Unit Systemd:

[Unit]
Description=Monqlab Agent Service
Documentation=https://docs.monq.ru/
[Service]
Type=notify
WorkingDirectory=/opt/monq-agent
Environment="DOTNET_BUNDLE_EXTRACT_BASE_DIR=/opt"
ExecStart=/opt/monq-agent/monq-agent start --config /opt/monq-agent/monitoring-agent.conf
User=monq
[Install]
WantedBy=multi-user.target
Alias=monq-agent.service

Управление сервисом осуществляется через команды systemctl:

Загрузить новый файл конфигурации systemd (выполняется при изменении файла monq-agent.service)
```
sudo systemctl daemon-reload 
```
Проверить статус сервиса monq-agent.service
```
sudo systemctl status monq-agent.service 
```
Запустить сервис monq-agent.service
```
sudo systemctl start monq-agent.service 
```
Открыть логи сервиса monq-agent.service
```
sudo journalctl -u monq-agent.service -f 
```

Запуск в Windows

Для запуска monq-agent в качестве службы Windows необходимо от имени Администратора создать и зарегистрировать службу с помощью утилиты для командной строки Диспетчер управления службами Windows.

Пример:

# Создать службу
sc.exe create MonqAgent binPath= "C:\monq-agent\monq-agent.exe start --config C:\monq-agent\monitoring-agent.conf" 
# Запустить службу
sc.exe start MonqAgent 
# Остановить службу
sc.exe stop MonqAgent 
# Удалить службу
sc.exe delete MonqAgent

Запуск в Kubernetes

Репозиторий Monq agent в GitHub

Установка Monq agent через Helm

Должен быть установлен Helm для использования чартов.

Пожалуйста, обратитесь к документации по Helm, чтобы начать.

Когда Helm будет настроен правильно, установите последнюю версию чарта с именем релиза monq-agent следующей командой:

kubectl create namespace monq

helm upgrade --install monq-agent monq-agent --repo https://monqdl.github.io/monq-agent --namespace monq \
--set config.baseUri="https://monq.mydomain.com" --set config.apiKey="<my coordinator key>"

Удаление Monq agent через Helm

Для удаления monq-agent выполните следующую команду:

helm delete monq-agent -n monq

Данная команда удаляет все компоненты Kubernetes, связанные с чартом, и удаляет релиз.

Параметры конфигурация агента при установке через Helm

Ключ	Тип	Значение по умолчанию	Описание
`config.baseUri`	string	`nil`	Полностью определенное доменное имя (FQDN) экземпляра Monq
`config.apiKey`	string	`nil`	API ключ координатора Monq
`config.fileStorage`	string	`nil`	Путь к хранилищу файлов агента
`config.timeout`	int	`100`	Таймаут для подключения к экземпляру Monq
`config.pluginsPath`	string	`agent-plugins`	Путь к хранилищу плагинов агента
`config.retryCount`	int	`10`	Количество попыток повторного подключения к экземпляру Monq
`config.slotsCount`	int	`2`	Количество активных слотов агента
`replicas`	int	`1`	Количество реплик агента
`image.repository`	string	`ghcr.io/MONQDL`	Репозиторий образов контейнеров
`image.name`	string	`monq-agent`	Название образа
`image.pullPolicy`	string	`IfNotPresent`	Политика загрузки образа
`image.tag`	string	`nil`	Тэг образа, используется `AppVersion`, если не определено
`imagePullSecrets`	list	`[]`	Необязательный массив imagePullSecrets, содержащий учетные данные для доступа к закрытому реестру образов # Справка: https://kubernetes.io/docs/tasks/configure-pod-container/pull-image-private-registry/
`resources.limits.cpu`	string	`nil`	Лимит использования ЦПУ
`resources.limits.memory`	string	`nil`	Лимит использования памяти
`resources.requests.cpu`	string	`250m`	Запрашиваемые ресурсы ЦПУ
`resources.requests.memory`	string	`256Mi`	Запрашиваемые ресурсы памяти
`nodeSelector`	object	`{"kubernetes.io/os":"linux"}`	Метки `nodeSelector` для распределения пода на ноде # Справка: https://kubernetes.io/docs/user-guide/node-selection/ #

Установка при помощи манифеста

Установите Monq-agent в качестве развертывания (Deployment) на ваш кластер Kubernetes, применив манифест:

export MONQ_URI="https://monq.mydomain.com"
export MONQ_KEY="<my coordinator key>"

curl https://raw.githubusercontent.com/MONQDL/monq-agent/master/manifests/monq-agent/monq-agent.yaml -o monq-agent.yaml 

envsubst < monq-agent.yaml | kubectl apply -f -

Этот манифест также создает ClusterRole, ClusterRoleBinding, ServiceAccount и Secret для работы с компонентами кластера.

Траблшутинг при подключении

Подключение в legacy-mode

В случае если необходимо подключить monq-agent, работающий на операционной системе:

Windows Server 2008
Windows 7
Windows Server 2012
Windows 8
Windows 8.1

Cистемному администратору инфраструктуры Monq необходимо разрешить в конфигурации ingress-nginx-controller использование cipher поддерживаемых устаревшими ОС.

Для этого в configMap ingress-nginx-controller необходимо добавить следующую опцию:

kubectl edit cm -n ingress-nginx ingress-nginx-controller
...
  ssl-ciphers: "ECDHE-ECDSA-AES256-GCM-SHA384:ECDHE-RSA-AES256-GCM-SHA384:ECDHE-ECDSA-CHACHA20-POLY1305:ECDHE-RSA-CHACHA20-POLY1305:ECDHE-ECDSA-AES128-GCM-SHA256:ECDHE-RSA-AES128-GCM-SHA256:ECDHE-ECDSA-AES256-SHA384:ECDHE-RSA-AES256-SHA384:ECDHE-ECDSA-AES128-SHA256:ECDHE-RSA-AES128-SHA256"
... 

При возникновении ошибок с загрузкой DLL при запуске monq-agent в данной ОС Windows необходимо дополнительно установить Microsoft Visual C++ 2015 Redistributable (x64)

Проверка подключения

Об успешном запуске и подключении агента к платформе, свидетельствует запись в лог-файле:

sudo journalctl -u monq-agent.service -f 
Nov 23 13:37:39 elk monq-agent[102088]: [2021-11-23 13:37:39 +03:00 INF]  Establishing connection.
Nov 23 13:37:44 elk monq-agent[102088]: [2021-11-23 13:37:44 +03:00 INF]  Connection established.

Перейдите в раздел Сбор данных - Агенты.
Откройте координатор к которому выполнялось подключение агента.
Перейдите на вкладку «Агенты» и убедитесь в том, что агент подключен.

⚠️ Если домен на котором работает Monq подписан self-signed сертификатом безопасности необходимо добавить параметр --insecure в строке запуска агента.

Внимание

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

Настройка логирования

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

...
[Serilog:WriteTo:0]
Name="File"

[Serilog:WriteTo:0:Args]
path="D:\\monq-log.txt"
rollingInterval="Day"

[Serilog:MinimumLevel]
Default="Debug"

[Serilog:MinimumLevel:Override]
Microsoft="Debug"
System="Debug"
...

Дополнительную информацию по конфигурации Serilog можно найти по ссылке.

Тонкая настройка соединения

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

Пример записи из лога:

[2024-02-08 13:10:59 +00:00 INF]  Establishing connection.
[2024-02-08 13:11:14 +00:00 ERR]  The server disconnected before the 
handshake could be started.System.IO.IOException: The server disconnected before the handshake could be 
started.
   at 
Microsoft.AspNetCore.SignalR.Client.HubConnection.HandshakeAsync(ConnectionState 
startingConnectionState, CancellationToken cancellationToken) 

Изменить параметры соединения можно с помощью клиента управления monqctl через команду monqctl registry apply применительно к сервису pl-agents-service (объект Hub).

Список свойств, доступных для настройки:

Свойство	Описание	Формат	Пример	По умолчанию
KeepAliveInterval	Интервал, используемый сервером для периодической проверки связи с клиентами. При изменении значения здесь, следует также изменить `ServerTimeout` в настройках клиентов	D.HH:mm:ss (string)	"0.00:00:10"	10 секунд
HandshakeTimeout	Интервал таймаута входящих запросов подтверждения от клиентов. Менять этот параметр стоит только в случае возникновения ошибок по таймауту из-за серьезной задержки в сети	D.HH:mm:ss (string)	"0.00:00:15"	15 секунд
ClientTimeoutInterval	Интервал, за который клиенты должны обработать сообщение, прежде чем сервер разорвет соединение. Рекомендуемое значение: как минимум х2 от KeepAliveInterval сервера	D.HH:mm:ss (string)	"0.00:00:30"	30 секунд
EnableDetailedErrors	Флаг отправки клиенту подробных сообщений об ошибках	boolean	true	false
MaximumReceiveMessageSize	Максимальный размер одного входящего сообщения в байтах	number	1048576	1МБ
StreamBufferCapacity	Максимальный размер буфера для клиентских потоков загрузки данных	number	10	10
MaximumParallelInvocationsPerClient	Количество параллельно выполняемых клиентами методов концентратора	number	2	1

Применяемая настройка обновляет все свойства!

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

Поэтому перед применением изменений рекомендуется сначала проверить исходную настройку, полностью скопировать всю выданную структуру, в ней изменить необходимые значения свойств на желаемые и/или добавить новые, после чего применить конфигурацию:

Проверка текущей конфигурации:

monqctl registry get microservice-parameters pl-agents-service --output json | jq '.[] | select(.Name == "Hub") | .Value'

Пример ответа, выводимого в консоль:

{
  "MaximumReceiveMessageSize": 1048576
}

Применение новой конфигурации с обновленными свойствами:

monqctl registry apply microservice-parameter pl-agents-service \
--name=Hub \
--settingsKey="appsettings-scheduler.json" \
--value='
{
  "MaximumReceiveMessageSize": 9999999999,
  "EnableDetailedErrors": true,
  "MaximumParallelInvocationsPerClient": 2
}
'

Кроме того, расширена конфигурация самого агента, т.к. соединение по веб-сокетам двухстороннее и требует настройки как на клиенте, так и на сервере одновременно:

[Connection]
# Глобальный таймаут установки и регистрации соединения в секундах.
# Значение по умолчанию - 30 секунд.
Timeout=30
# Количество попыток установки соединения.
# Значение по умолчанию - 12.
RetryCount=12
# Таймаут активности сервера.
# Если сервер не отправил сообщение за этот интервал, клиент считает, что сервер отключен, и закрывает соединение.
# Это значение должно быть достаточно большим, чтобы ping-сообщение могло быть получено клиентом за данный интервал.
# Рекомендуемое значение — по меньшей мере удвоенное значение KeepAliveInterval сервера.
# Значение по умолчанию - 30 секунд.
ServerTimeout="00:00:30"
# Таймаут запросов подтверждения с сервера.
# Если сервер не отправил ответ на handshake-сообщение в течение этого интервала, то клиент закрывает соединение.
# Менять этот параметр стоит только в случае возникновения ошибок по таймауту из-за серьезной задержки в сети.
# Рекомендуемое значение - не меньше, чем значение Timeout.
# Значение по умолчанию - 15 секунд.
HandshakeTimeout="00:00:15"
# Интервал, с которым клиент отправляет ping-сообщения для проверки связи.
# Если клиент не отправил сообщение за ClientTimeoutInterval, установленном на сервере, то сервер считает, что клиент отключен.
# Значение по умолчанию - 10 секунд.
KeepAliveInterval="00:00:10"

Основная информация​

Экран «Управление агентами»​

Координаторы​

Список координаторов​

Поиск координаторов​

Создание координаторов​

Настройка координаторов​

Основная информация​

Конфигурации агентов​

Создание новой конфигурации​

Запуск и остановка координаторов​

Перевыпуск API-ключа​

Удаление координаторов​

Агенты​

Список агентов​

Поиск агентов​

Состояние подключенных агентов​

Состояние выполнения заданий​

Подключение агента​

Установка в Linux​

Установка в Windows​

Конфигурация агента​

Рабочие конфигурации агентов​

Персональные метки агентов​

Типы агентов​

Подключение плагинов​

Запуск​

Запуск в Linux​

Запуск в Windows​

Запуск в Kubernetes​

Установка Monq agent через Helm​

Удаление Monq agent через Helm​

Параметры конфигурация агента при установке через Helm​

Установка при помощи манифеста​

Траблшутинг при подключении​

Подключение в legacy-mode​

Проверка подключения​

Настройка логирования​

Тонкая настройка соединения​

Основная информация

Экран «Управление агентами»

Координаторы

Список координаторов

Поиск координаторов

Создание координаторов

Настройка координаторов

Основная информация

Конфигурации агентов

Создание новой конфигурации

Запуск и остановка координаторов

Перевыпуск API-ключа

Удаление координаторов

Агенты

Список агентов

Поиск агентов

Состояние подключенных агентов

Состояние выполнения заданий

Подключение агента

Установка в Linux

Установка в Windows

Конфигурация агента

Рабочие конфигурации агентов

Персональные метки агентов

Типы агентов

Подключение плагинов

Запуск

Запуск в Linux

Запуск в Windows

Запуск в Kubernetes

Установка Monq agent через Helm

Удаление Monq agent через Helm

Параметры конфигурация агента при установке через Helm

Установка при помощи манифеста

Траблшутинг при подключении

Подключение в legacy-mode

Проверка подключения

Настройка логирования

Тонкая настройка соединения