Usm poller (as satellite)

en | ru

Описание

Начиная с версии 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) или Python3 любой поддерживаемой на данный момент версии и 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

Установка зависимостей

Необходим Python3 любой поддерживаемой на данный момент версии. Статус версий можно посмотреть здесь: "Status of Python versions". Рекомендуется использовать версию с состоянием "security" или "bugfix". Версии отмеченные как "end-of-life" не поддерживаются. Отмеченные как "feature" не рекомендуется использовать. Если у вас на хосте неподдерживаемая версия ("end-of-life"), то нужно обязательно установить дополнительно более свежую версию Python.

Убедитесь, что версия Python3 актуальна:

python3 --version

Все последующие команды будут показаны с указанием явной версии 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