Перейти к основному содержимому
Версия: 8.2

Агенты

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

Что такое агент в архитектуре 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.baseUristringnilПолностью определенное доменное имя (FQDN) экземпляра Monq
config.apiKeystringnilAPI ключ координатора Monq
config.fileStoragestringnilПуть к хранилищу файлов агента
config.timeoutint100Таймаут для подключения к экземпляру Monq
config.pluginsPathstringagent-pluginsПуть к хранилищу плагинов агента
config.retryCountint10Количество попыток повторного подключения к экземпляру Monq
config.slotsCountint2Количество активных слотов агента
replicasint1Количество реплик агента
image.repositorystringghcr.io/MONQDLРепозиторий образов контейнеров
image.namestringmonq-agentНазвание образа
image.pullPolicystringIfNotPresentПолитика загрузки образа
image.tagstringnilТэг образа, используется AppVersion, если не определено
imagePullSecretslist[]Необязательный массив imagePullSecrets, содержащий учетные данные для доступа к закрытому реестру образов # Справка: https://kubernetes.io/docs/tasks/configure-pod-container/pull-image-private-registry/
resources.limits.cpustringnilЛимит использования ЦПУ
resources.limits.memorystringnilЛимит использования памяти
resources.requests.cpustring250mЗапрашиваемые ресурсы ЦПУ
resources.requests.memorystring256MiЗапрашиваемые ресурсы памяти
nodeSelectorobject{"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 можно найти по ссылке.