Usm poller (as satellite)
Описание
Начиная с версии USERSIDE 3.18 для взаимодействия с телекоммуникационным оборудованием используются специальные службы usm_poller, запускаемые в нескольких копиях на серверах оператора для увеличения доступности, отказоустойчивости и распределения нагрузки между серверами. Между ядром USERSIDE и этими службами передаются специальные сообщения, содержащие сетевые задания, которые через брокер сообщений RabbitMQ распределяются между всеми службами usm_poller и таким же образом через брокер службы сообщают ядру USERSIDE о результатах работы. Использование более подходящих для сетевого взаимодействия инструментов, а также внесенная в систему асинхронность позволяет использовать ранее недоступные протоколы связи, ускорить многие сценарии взаимодействия по существующим протоколам и не заставлять пользователя ждать результата в открытом окне браузера.
С учетом особенностей запуска служб usm_poller создается возможность использования этих поллеров вместо пркси-модулей usm_satellite, которые использовались в USERSIDE версиях 3.13-3.17 для проксирования команд взаимодействия с оборудованием между ядром USERSIDE и недоступным по сети оборудованием по протоколу HTTP-API. Для этого в модули usm_poller была добавлена простая настройка, идентифицирующая конкретный экземпляр usm_poller как "сателлит".
Начиная с версии USERSIDE 3.18 в качестве "сателлита" на удалённых узлах используется модуль usm_poller.
Требования
Для запуска usm_poller на удалённом узле связи требуется наличие Docker (и опционально Compose plugin v2) или Python 3.9 и supervisor для запуска без Docker.
Версии
По мере развития системы, может возникать ситуация, когда новая версия USERSIDE не совместима со старой версией usm_poller. Например, когда внесены изменения в API или структуру данных или что либо еще.
Все версии USERSIDE начиная с 3.18.0 и по 3.18.19 включительно работают с usm_poller версий 3.18.0 и по 3.18.7 включительно.
Версии USERSIDE 3.18.20 и более новые требуют минимальную версию usm_poller 3.18.8.
Установка, настройка и запуск с использованием Docker
Несмотря на то, что также возможен запуск без Docker, мы настоятельно рекомендуем использовать Docker контейнер для запуска поллера в качестве сателлита. Если по каким-то причинам вы не можете использовать Docker, ниже дана инструкция по запуску без Docker.
Установка Docker и Compose plugin
В большинстве поддерживаемых операционных систем достаточно запуска команды:
curl -fsSL get.docker.com | sh
Эта команда установит Docker Engine и Compose Plugin последних версий на большинстве поддерживаемых операционных систем. Если для вашей системы это невозможно, команда выдаст рекомендации по ручной установке. Вы также можете обратиться к официальной инструкции по установке на сайте проекта Docker. Обратите внимание на то, что версия DockerIO, которая поставлялась с некоторыми дистрибутивами Linux, считается устаревшей и не подходит. Одновременно с этим, версия Docker Desktop, предназначенная для десктопных операционных систем, поддерживается и вы сможете также использовать и ее, но предпочтение лучше отдать Docker Engine (серверной версии Docker).
Если вам необходимо запускать команды к Docker без использования sudo, то добавьте своего пользователя в группу docker следующими командами:
sudo gpasswd -a $USER docker newgrp docker
Теперь проверьте, что все установилось корректно, выполнив команды:
docker version docker compose version
Организация связи поллера с брокером
При использовании usm_satellite сервером являлся сам модуль, в то время как клиентом являлось ядро Userside, которое выполняло HTTP-API запросы к usm_satellite.
Теперь сервером для всех потребителей сообщений является брокер RabbitMQ, не зависимо от того, отправляет приложение сообщение либо его принимает. Это означает, что удалённый сервер, на котором устанавливается usm_poller в качестве сателлита, должен иметь доступ по сети к брокеру RabbitMQ, установленному на сервере с Userside (либо на каком-то отдельном сервере, если в этом была необходимость). В то же время удаленный сервер теперь вообще может не иметь открытых портов, что повышает его безопасность.
Для подключения к брокеру RabbitMQ по умолчанию используется TCP-порт 5672 (протокол AMQP). Мы рекомендуем открыть доступ к этому порту из внешней сети только с известных вам IP-адресов, коим является IP-адрес удаленного сервера-сателлита, на котором вы запускаете usm_poller.
Если вы используете и USERSIDE в Docker-бандле, то раскомментируйте строку в ports сервиса rabbitmq, отвечающую за трансляцию порта 5672 (подписан в комментариях как AMQP) и перезапустите Docker-бандл.
Также альтернативой порту 5672 (AMQP) может быть порт 5671 (AMQPS), который по умолчанию не используется. Вы можете настроить AMQPS (TLS) самостоятельно в дополнение к порту 5672 (AMQP). Инструкции по настройке TLS можно получить в официальной документации RabbitMQ.
Т.к. сообщения, передаваемые между брокером RabbitMQ и его потребителями передаются в открытом виде, рекомендуемым вариантом организации связи является использование туннелирования с шифрованием между узлами RabbitMQ и удалённым сервером с usm_poller.
Запуск Docker-контейнеров usm_poller
Рекомендуемым способом запуска является использование плагина compose. В этом случая вся конфигурация контейнера прописывается в специальном compose-файле, что облегчает последующую эксплуатацию.
Вы можете создать compose-файл где угодно, но чтобы не потерять его расположение в будущем, рекомендуем расположить его, например, в /opt/usm_poller. Создайте каталог:
sudo mkdir -p /opt/usm_poller
Затем создайте файл с именем compose.yaml в этом каталоге и следующим содержимым (обратите внимание на отступы - они имеют значение):
services:
poller:
image: erpuserside/usm_poller:3.18.8
restart: unless-stopped
environment:
US_AMQP_DSN: amqp://имя_пользователя:пароль@адрес_хоста_rabbitmq:5672/%2f
USM_POLLER_SATELLITE_ID: id_вашего_satellite
deploy:
replicas: 1
Для работы с USERSIDE 3.18.x используется образ erpuserside/usm_poller:3.18.x. Версия usm_poller должна быть совместима с конкретной версией USERSIDE (см. выше).
Значением для US_AMQP_DSN является URL-строка, которую вы можете скопировать из файла .env, расположенного в корневом каталоге с USERSIDE: /var/www/userside, но вместо IP-адреса RabbitMQ, указанного там, вам нужно указать тот IP-адрес, по которому доступен сервер RabbitMQ (зависит от того, какой способ доступа вы используете).
Значением для USM_POLLER_SATELLITE_ID является идентификатор "сателлита", который вы можете взять со страницы: Настройка - Основная - Оборудование - Настройка сателлитов.
Сохраните файл composer.yaml и запустите для теста следующим образом:
docker compose up
Вы должны увидеть, как загружается образ, затем происходит запуск Docker-контейнера usm_poller и подключение к серверу RabbitMQ по протоколу AMQP. Если подключение к RabbitMQ серверу произошло корректно, то остановите работу контейнера сочетанием Ctrl+C, измените количество реплик (значение replicas) до 5 и запустите контейнеры в фоновом режиме:
docker compose up -d
Если пяти копий контейнера будет мало, увеличьте это значение. Чтобы определить, достаточно ли контейнеров, откройте WEB-консоль RabbitMQ используя протокол http, адрес домена вашего userside и порт 15672. Например, вот так: http://userside.mycompany.com:15672 и затем перейдите на страницу Queues. Найдите там очередь с именем usm_poller-sat-7 (где 7 — это идентификатор сателлита), откройте ее и понаблюдайте за заполнением очереди. Смысл заключается в том, чтобы поллеры успевали забирать задания в пределах нормального для вас времени. В идеале, очередь должна быть практически пустой всегда (задания сразу же отдаются свободному поллеру), либо количество сообщений должно доходить до нуля (количество поллеров достаточно). Не стоит увеличивать количество реплик просто так — это приведет к ненужному накладному расходу ресурсов и в итоге может даже отрицательно сказаться на производительности, если ресурсов системы будет не хватать.
После изменения количества реплик, нужно выполнить перезапуск командой:
docker compose restart
Посмотреть состояние контейнеров можно командой:
docker compose ps
Чтобы остановить все контейнеры, используйте команду:
docker compose stop
Чтобы обновить версию Docker-образа в пределах его версии (это желательно делать после каждого обновления USERSIDE), нужно сначала остановить контейнеры, затем отредактировать файл, указав номер новой версии usm_poller и затем снова запустить их в фоне:
docker compose down nano compose.yaml docker compose up -d
Чтобы не засорять систему не используемыми образами, их можно удалять, указывая образ целиком с версией:
docker rmi erpuserside/usm_poller:3.18.2
Если вам кажется, что что-то работает не так как нужно, посмотрите логи контейнеров командой:
docker compose logs poller
Либо же можно добавить опцию -f чтобы наблюдать follow за логами в реальном времени.
Запустить один контейнер можно и без использования compose, выполнив всего лишь одну команду (состоящую из нескольких строк). Однако такой способ хоть и является более простым, все же не так удобен для последующей эксплуатации:
docker run --detach \ --restart unless-stopped \ --name usm_poller \ --env US_AMQP_DSN=amqp://имя_пользователя:пароль@адрес_хоста_rabbitmq:5672/%2f \ --env USM_POLLER_SATELLITE_ID=id_вашего_satellite \ erpuserside/usm_poller:3.18.8
Установка, настройка и запуск без Docker
Рекомендуемым способом является использование поллера в качестве Docker контейнера. В этом случае все необходимые зависимости находятся внутри контейнера и вам не нужно дополнительно ни о чем заботиться. Также и обновления выполняются одной командой. Но, если по какой-то причине вы не можете использовать Docker, то единственным способом является запуск поллера прямо на хосте.
Создание копии поллера для сателлита
Для начала вам нужно скопировать поллер на сателлит-сервер. Для этого вам нужно создать архив с файлами поллера на сервере с USERSIDE и затем скопировать и разархивировать их на сателлит-сервере.
На сервере USERSIDE выполните:
cd /var/www/userside/microserice tar --exclude="venv" -czf usm_poller.tgz poller/
Скопируйте файл usm_poller.tgz на сателлит-сервер. Например, в каталог /opt и выполните следующие команды:
tar xzf usm_poller.tgz cd poller
Установка зависимостей
Убедитесь, что версия Python не ниже 3.9 (желательно 3.11):
python3 --version
Если версия ниже 3.9, то установите версию 3.11 (как альтернативную версию, не заменяя существующую) по этой инструкции.
Все последующие команды будут показаны с указанием явной версии Python. Если у вас версия отличается от указанной в командах - указывайте вашу версию.
Установите все необходимые зависимости:
sudo apt install -y supervisor libsnmp-dev sudo -H python3 -m venv venv sudo -H venv/bin/pip install -U pip wheel sudo -H venv/bin/pip install -U -r requirements.txt
Конфигурация и запуск
Создайте файл .env в который поместите следующие переменые:
US_AMQP_DSN=amqp://имя_пользователя:пароль@адрес_хоста_rabbitmq:5672/%2f USM_POLLER_SATELLITE_ID=id_вашего_satellite USM_POLLER_LOGFILE=stdout
Выполните тестовый запуск:
sudo -H venv/bin/python worker.py
Вы должны увидеть, что поллер подключился к брокеру. Убедитесь в отсутствии каких либо ошибок. Запущенный поллер постоянно выполняется и ожидает сообщений от брокера. На USERSIDE выполните какой либо опрос оборудования, которое находится в зоне обслуживания этого сателлита, и убедитесь что все сработало успашно. Например, можно открыть какой-то коммутатор и убедиться, что информация с коммутатора была снята поллером и в пользовательском интерфейсе USERSIDE вы увидели результат этой работы.
Остановите работу поллера, запущенного вручную, комбинацией клавиш Ctrl+C. Придется подождать около 5 сек, пока поллер завершит все свои задачи и корректно закроет подключение к брокеру.
Из файла .env удалите строку с переменной USM_POLLER_LOGFILE. По умолчанию логи пишутся в файл /var/log/usm_poller/poller.log. Если вас не устраивает этот путь, то вместо удаления переменной, измените ее значение на нужный вам файл.
Скопируйте пример настроек супервизора и пример настроек ротации логов из подкаталога etc:
sudo cp etc/usm_poller.conf-example /etc/supervisor/conf.d/usm_poller.conf sudo cp etc/logrotate-example /etc/logrotate.d/usm_poller
Отредактируйте файл /etc/supervisor/conf.d/usm_poller.conf. В нем измените путь к поллеру: вместо /var/www/userside/microservice/poller укажите /opt/poller или тот, куда вы скопировали поллер. Также укажите количество запускаемых копий в параметре numprocs. В зависимости от количества оборудования и количества задач, обслуживаемых сателлитом. Начните с 2 и по мере необходимости в будущем изменяйте это значение. Запускать сразу 15 копий нет смысла. К тому же, если ваш сателлит-сервер недостаточно мощный, то это может привести к деградации производительности.
Отредактируйте файл /etc/logrotate.d/usm_poller если вы изменили путь к логам в переменной окружения USM_POLLER_LOGFILE файла .env.
Перезапустите супервизор, чтобы он перечитал конфигурацию:
sudo systemctl restart supervisor
И спустя несколько секунд понаблюдайте за процессами, которые он контролирует - все копии поллера должны быть в состоянии RUNNING.
sudo supervisorctl status
На этом настройка закончена.
Обновление
Для обновления вам придется снова делать архив поллера с сервера USERSDIE и переносить его на сателлит-сервер, где разархивировать и снова устанавливать (обновлять) зависимости.
Для этого на сервере USERSIDE создайте архив:
cd /var/www/userside/microserice tar --exclude="venv" -czf usm_poller.tgz poller/
Скопируйте его на сателлит сервер в каталог /opt и разархивируйте:
tar xzf usm_poller.tgz cd poller
Обновите зависимости:
sudo -H venv/bin/pip install -U pip wheel sudo -H venv/bin/pip install -U -r requirements.txt
Перезапустите супервизор:
sudo supervisorctl restart usm_poller:* sudo supervisorctl status