Агенты

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

Что такое агент в архитектуре Monq?

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

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

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

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

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

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

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

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

• Обработка поступающих сценариев Заданий.

• Генерация результирующего артефакта и отправка данных в поток.

• Прямой запуск команд взаимодействия с консолью ОС (sh, bash, windows command, powershell).

• Запуск параллельного выполнения нескольких заданий.

• Подключение плагинов интеграций:

  • Zabbix

  • SCOM

  • vCenter

По умолчанию все Задания выполняются на системном Агенте Monq, который входит в поставку системы.

Системный Агент получает задания через системный Координатор (метка SharedAgents).

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

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

Управление Координаторами подразумевает под собой возможность выполнить следующие действия:

• Создать или удалить координатор
• Остановить или запустить Координатор
• Произвести основные настройки Координатора
• Перевыпустить API-ключ для подключения агентов
• Добавить или удалить общие метки для агентов
• Настроить права доступа к Координатору.

Информация

Права доступа к системному Координатору ограничены:

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

Добавление координатора

1. Перейдите через основное меню в раздел Сбор данных → Агенты.

2. Нажмите в верхнем правом углу экрана Добавить координатор.

3. Заполните поля:

   • Владелец
   • Название координатора
   • Добавьте метки

     Метки используются для распределения Заданий Потоков данных между Координаторами

     При добавлении метки на сам координатор данная метка автоматически присваивается всем агентам подключенным к нему.

     ⚠️ Если добавить метку SharedAgents созданному Координатору, планировщик распределит запуск Заданий с меткой SharedAgents (установленной по умолчанию) также и на подключенные Агенты.

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

4. Нажмите Добавить

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

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

1. Перейдите через основное меню в раздел Сбор данных → Агенты.
2. Найдите координатор, который необходимо удалить.
3. Используя контекстное меню, выберите Удалить.
4. В диалоговом окне подтвердите удаление координатора.

Координатор можно также удалить со страницы управления координатором. Для этого откройте нужный координатор и в верхнем правом углу нажмите Удалить.

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

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

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

1. Перейдите через основное меню в раздел Сбор данных → Агенты.
2. Перейдите на страницу настройки необходимого координатора.
3. В правом верхнем углу нажмите на ︙ и выберите пункт меню Перевыпустить API-ключ.
4. В диалоговом окне подтвердите перевыпуск API-ключа.
5. Новый API-ключ будет скопирован в буфер-обмена, а также виден возле названия координатора.

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

После добавления Координатора в систему – состояние Координатора по умолчанию Запущен – координатор распределяет Задания для выполнения на подключенные к нему Агенты.

Остановка работы Координатора означает, что:

• Задания больше не будут распределяться на Агенты, подключенные к Координатору.
• Агенты могут подключаться к координатору, но заданий на исполнение получать не будут.

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

1. Перейдите через основное меню в раздел Сбор данных → Агенты.
2. Найдите координатор, который необходимо запустить.
3. Используя контекстное меню – выберите Запустить.
4. В случае успешного запуска вы увидите соответствующее сообщение.

Координатор также можно запустить со страницы управления координатором. Для этого откройте нужный координатор и в верхнем правом углу нажмите Запустить.

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

1. Перейдите через основное меню в раздел Сбор данных → Агенты.
2. Найдите координатор, который необходимо остановить.
3. Используя контекстное меню – выберите Остановить.
4. В случае успешной остановки вы увидите соответствующее сообщение.

Координатор также можно остановить со страницы управления координатором. Для этого откройте нужный координатор и в верхнем правом углу нажмите Остановить.

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

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

1. Перейдите через основное меню в раздел Сбор данных → Агенты.
2. Откройте вкладку Настройки.
3. Измените при необходимости:
   • Владельца
   • Название координатора
   • Добавьте или удалите необходимые метки

     Добавление меток осуществляется посредством кнопки "Enter", нажимаемой после ввода названия метки

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

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

• Последний контакт – время, когда агент был активен

• Название агента – имя агента, указанное в конфигурационном файле агента

• Тип – Динамический или Статический (подробнее о типах агентов)

• Состояние – Активен или Недоступен

• Версия – версия подключенного агента

Цифра возле названия вкладки информирует о количестве подключенных агентов к координатору.

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

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

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

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

1. Перейдите через основное меню в раздел Сбор данных → Агенты.

2. Откройте вкладку Задания.

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

   • Последний запуск – время последнего запуска задания на агенте

   • Последний статус – статус выполнения последнего задания на агенте

   • Владелец задания – поток данных, которому принадлежит задание

   • Название – название задания в шаблоне конфигурации потока данных

   • Метки – информация о метках, связывающих координатор с заданием шаблона конфигурации

4. Произведите сортировку списка заданий по полям:

   • Последний запуск
   • Последний статус
   • Владелец задания
   • Название

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

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

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

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

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

Справка

Схема работы агентов

Координатор распределяет Задания подключенным к нему Агентам.

Агенту может быть одновременно выдано количество Заданий, не превышающее параметр SlotsCount конфигурационного файла Агента.

Типы агентов

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

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

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

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

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

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

Агент для Windows

Агент для Linux

Установка

Установка в Linux

1. Создайте рабочую директорию для агента и перейдите в нее:

   mkdir -p /opt/monq-agent && cd /opt/monq-agent

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

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

3. Разархивируйте загруженный архив в текущую директорию:

   unzip monq-agent.zip && rm -f monq-agent.zip

4. Сделайте двоичный файл monq-agent исполняемым:

   chmod +x ./monq-agent

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

   • CentOS/RHEL

     yum install libicu

   • Debian/Ubuntu

     # найти актуальную версию
     apt search '^libicu[0-9]*$'
     
     # выполнить установку найденной версии, например 66
     apt install libicu66

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

Установка в Windows

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

Настройка

Конфигурационный файл агента

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

# Базовый URI системы Monq
BaseUri="https://monq.domain.com"
# API-ключ координатора для авторизации агента
ApiKey="fc63b95b-0393-430a-b8d0-46a8c4813675"
# Путь к хранилищу файлов (опционально)
FileStorage=""
# Таймаут выполнения заданий в миллисекундах (опционально)
Timeout=100

# Настройки плагинов (опционально)
[Plugins]
# Путь к DLL плагинам C# linux
CSharpPath="/opt/monq-agent/plugins"
# Путь к DLL плагинам C# windows
# CSharpPath="c:\monq-agent\plugins\"

# Настройки соединения с координатором (опционально)
[Connection]
# Таймаут установки соединения в миллисекундах
Timeout=100
# Количество попыток установки соединения
RetryCount=12

# Информация об агенте (опционально)
[Agent]
# Название
# Name="monq-agent-hostname"
# Описание
Description=""
# Количество слотов для выполнения заданий
SlotsCount=2

Замените значения параметров конфигурационного файла на свои:

• BaseUri - базовый URI системы Monq

• ApiKey - API-ключ координатора для авторизации агента

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

У пользователя есть возможность установить любую метку на агент.

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

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

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

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

В текущей версии агентов поддерживаются следующие плагины:

• nagiosCheckConnection - плагин проверки соединения с системой мониторинга Nagios.
• nagiosEventsDataFlow - плагин сбора данных с системы мониторинга Nagios.
• scomCheckConnection - плагин для проверки соединения с системой мониторинга SCOM.
• scomEventsDataFlow - плагин сбора данных с системы мониторинга SCOM.
• vmwareEventsDataFlow - плагин сбора данных об изменениях в топологии VmWare vCenter.
• vmwareTopologySync - плагин синхронизации топологии с VmWare vCenter.
• zabbixCheckConnection - плагин проверки соединения с системой мониторинга Zabbix.
• zabbixCheckVersion - плагин проверки версии Zabbix.
• zabbixEventsDataFlow - плагин сбора данных с системы мониторинга Zabbix.
• K8sMetricsDataFlow - плагин автообнаружения и сбора метрик с Kubernetes.
• K8sTopologySync - плагин синхронизации топологии с Kubernetes.

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

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

Запуск

Справка

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

• start - Запуск агента. (Использование: monq-agent [options] start)

Поддерживаемые параметры

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

Запуск в 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]
  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, связанные с чартом, и удаляет релиз.

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

Ключ	Тип	Значение по умолчанию	Описание
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.

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

⚠️ Если домен на котором работает 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 можно найти по ссылке.