2. Инструкция по развертыванию

2.1. Обновление платформы

Если вы получили новую версию платформы и при этом уже используете развернутую версию, последовательно выполните описанные ниже команды, в противном случае пропустите пункт 2.1.

Важно: Перед обновлением платформы с версии 1.11.0 (и ниже) на версию 1.12.0 (и выше) для сохранения доступа к данным в базе данных, необходимо выполнить следующие шаги:

1. Загрузите и распакуйте новую версию платформы.
2. Перенесите существующие учетные данные для доступа к СУБД в конфигурационный файл новой версии платформы в папке on_premise. Для этого откройте конфигурационный файл ./setup/settings.env предыдущей версии платформы и перенесите значения параметров POSTGRES_USER, POSTGRES_PASSWORD и POSTGRES_DB в конфигурационный файл ./deploy/services_db_config.json новой версии платформы в блок storage-engine-db.
3. Используя значения из файла, создайте базы данных и пользователей для каждого блока (за исключением storage-engine-db) в СУБД предыдущей версии платформы. Для этого можно воспользоваться скриптом ./setup/db-create.sh, поставляемым с новой версией платформы.

Пример использования скрипта указан ниже:

$ db-create.sh <POSTGRES_USER> <POSTGRES_USER_BLOCK> <POSTGRES_PASSWORD_BLOCK> <POSTGRES_DB_BLOCK>

где <POSTGRES_USER> - это пользователь базы данных, созданный в предыдущей версии платформы (указывается в файле ./setup/settings.env), а <POSTGRES_USER_BLOCK>, <POSTGRES_PASSWORD_BLOCK> и <POSTGRES_DB_BLOCK> - данные БД и пользователя блока для соответствующего сервиса.

Удаление предыдущей версии платформы

1. Перейдите в папку on_premise развернутой версии платформы и остановите платформу, выполнив команду:

$ ./setup/uninstall-platform.sh

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

$ watch 'kubectl get pods'

Статус сервисов из состояния Running должен перейти в состояние Terminating. В результате, все сервисы должны пропасть из отображаемой таблицы.

3. Удалите развернутый Kubernetes кластер, выполнив команду:

$ sudo kubeadm reset

4. Удалите вспомогательные файлы Kubernetes кластера с помощью команды:

$ sudo rm -rf ~/.kube/

5. Выполните сброс таблиц IPVS вашей системы, используя команду:

$ sudo ipvsadm --clear

примечание

При удалении платформы вся база данных сохраняется в директории /kv/pgdata. Для дальнейшего использования базы в процессе установки новой версии платформы необходимо указать те же авторизационные данные и имя базы данных. В противном случае, удалите папку /kv/pgdata (sudo rm -rf /kv/pgdata) для создания новой базы данных в процессе развертывания платформы.

примечание

После обновления платформы требуется произвести настройки платформы заново, либо сохранить текущие настройки перед обновлением. В последнем случае после обновления будет достаточно заменить файлы с настройками по умолчанию на файлы с сохраненными значениями (в случае полного совпадения полей в старой и новой версиях файлов). Под настройками в данном случае имеются в виду значения переменных окружения, указанные в файле ./setup/settings.env (См. подробнее в п. 2.2.3), а также настройки масштабирования, указанные в файле ./deploy/values.yaml (См. подробнее в п. 2.4.4).

2.2 Подготовка: загрузка образов и создание Kubernetes кластера

2.2.1 Подготовка

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

Далее переместите файл лицензии face_sdk.lic (файл прикреплен к электронному письму) в папку on_premise.

Откройте системную консоль, перейдите в директорию on-premise внутри дистрибутива и проверьте содержимое папки, используя команду:

$ find -maxdepth 1

Файлы и папки, содержащиеся в дистрибутиве, будут выведены в консоль. Пример вывода:

./deploy
./face_sdk.lic
./ingress-nginx-4.2.0.tgz
./OMNIAgent_Linux_x64.run
./OMNIAgent_Windows_x64.exe
./integration_tests
./kube-flannel.yml
./license_server
./nvidia-device-plugin-0.12.2.tgz
./pdf_docs
./platform_images.tar.gz
./setup 
./upload_script 

Основные элементы дистрибутива:

• ./pdf_docs/administrator_guide.pdf - руководство администратора, содержит информацию необходимую для развертывания OMNI Platform;
• ./pdf_docs/user_guide.pdf - руководство пользователя, содержит информацию необходимую для использования платформы;
• ./pdf_docs/integration_api.pdf - справочник по API;
• ./pdf_docs/release_notes.pdf - описание изменений, включая информацию о новом функционале, исправленным ошибкам и улучшениям;
• ./pdf_docs/agent_user_guide.pdf - руководство пользователя OMNI-агента;
• ./OMNIAgent_Linux_x64.run и ./OMNIAgent_Windows_x64.exe - установочные файлы агента для Windows и Linux соответственно;
• ./license_server - файлы необходимые для запуска лицензионного сервера, с помощью которого осуществляется лицензирование платформы;
• ./integration_tests - скрипты для автоматического тестирования платформы после развертывания;
• ./setup/settings.env - файл конфигурации экземпляра платформы.
• ./upload_script - папка, в которой находится скрипт загрузки изображений из датасета для создания профилей на платформе.

Дальнейшие команды выполняются в системной консоли из директории on_premise.

2.2.2 Загрузка образов

Загрузите в локальный registry образы из архива:

$ sudo docker load -i platform_images.tar.gz

Загрузка образов может занять около пяти минут.

2.2.3 Ввод переменных окружения

Откройте файл конфигурации ./setup/settings.env, используя текстовый редактор, и установите значения следующих переменных:

• MASTER_NODE_IP_ADDRESS - IP-адрес машины, на которой выполняется развертывание. Вы можете узнать его у Вашего системного администратора. DOMAIN - корневое доменное имя. После развертывания доступ к API и веб-интерфейсу платформы будет осуществляться по адресу http://platform.$DOMAIN. IP-адрес для доменного имени platform.$DOMAIN должен быть сконфигурирован на DNS-сервере (подробнее в пункте 2.3.2 данного руководства).
• RABBIT_USER и RABBIT_PASSWORD - имя пользователя и пароль для доступа к брокеру сообщений, используется для внутреннего взаимодействия сервисов платформы. Задайте произвольное имя, состоящее из латинских букв, без пробелов и пароль, состоящий из латинских букв и цифр, без пробелов.
• POSTGRES_USER, POSTGRES_PASSWORD и POSTGRES_DB - параметры подключения к базе данных. При первом развертывании платформы задайте произвольное имя пользователя и название базы данных, состоящих из латинских букв, без пробелов и сгенерируйте пароль, состоящий из латинских букв и цифр. База данных будет создана автоматически.
• SERVICE_KEY - секретный ключ, необходимый для внутреннего взаимодействия сервисов платформы. Сгенерируйте произвольную строку, состоящую из латинских букв и цифр без пробелов.
• LIC_KEY - лицензионный ключ. Обычно ключ отправляется в сопроводительном письме с дистрибутивом. При отсутствии ключа обратитесь к вашему менеджеру по продажам.
• PLATFORM_ADMIN_EMAIL и PLATFORM_ADMIN_PASSWORD - учетные данные, которые будут использоваться для доступа в панель администратора платформы. При первом развертывании пользователь с правами администратора будет создан автоматически. Укажите корректный email и сгенерируйте пароль состоящий из латинских букв и цифр длиной не менее 8-ми символов.
• PLATFORM_DEFAULT_EMAIL, PLATFORM_DEFAULT_PASSWORD - учетные данные пользователя для доступа в веб-интерфейс платформы. При первом развертывании пользователь будет создан автоматически. Укажите корректный email и сгенерируйте пароль состоящий из латинских букв и цифр длиной не менее 8-ми символов.
• EMAIL_HOST, EMAIL_PORT, EMAIL_HOST_USER, EMAIL_HOST_PASSWORD - параметры доступа к SMTP-серверу. SMTP-сервер используется для отправки писем, например при сбросе пароля или для оповещений. Чтобы отключить отправку писем, оставьте данные поля пустыми. Для получения параметров доступа к SMTP-серверу обратитесь к администратору вашей сети.
• EMAIL_USE_SSL - включение/отключение SSL-протокола, укажите значения true/false, соответственно. Если не используется SMTP-сервер укажите значение false.
• EMAIL_FROM - значение, которое будет отправлятся в заголовке FROM и отображаться в качестве отправителя письма. Требования к формату данного поля могут зависеть от SMTP-сервера. Пример значения поля FROM - "Bob Example" bob@example.org.
• QUERY_LIMIT - ограничение количества возвращаемых элементов в API запросах для получения сущностей системы. Увеличение данного лимита не рекомендуется, т.к. время выполнения API запроса может увеличиться в несколько раз. Также, обратите внимание, что увеличение лимитов приведет к ухудшению работы системы.
• INDEX_UPDATE_PERIOD - значение в секундах, описывающее через какое время добавленный профиль появится в поисковом индексе. По умолчанию установлено значение 60 секунд. Если требуется, чтобы индексы обновлялись чаще, значение параметра можно уменьшить.
• ENABLE_PROFILE_AUTOGENERATION - авто-создание профилей для приходящих активностей с агента. Необходимо учитывать, что при включении данной опции будет увеличенный расход ресурсов лицензии (размер базы данных). Если функция не требуется, то нужно оставить поле пустым, в противном случае установить значение 1.
• USE_CUDA - отвечает за использование CUDA ядер в сервисах обработки изображений. 0 - отключить GPU, 1 - включить GPU для сервиса processing.

Сохраните изменения в файле.

2.2.4 Расширенная конфигурация системы

В комплекте поставки находится конфигурационный файл ./deploy/values.yaml. В разделе env присутствует возможность изменить конфигурацию элементов системы.

примечание

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

Параметры конфигурационного файла values.yaml

• ACTIVITY_TTL: Время хранения активностей в базе данных. Значение задается в секундах. Например, 2592000 секунд (30 дней)
• SAMPLE_TTL: Время хранения сэмплов в базе данных. Значение задается в секундах. Например, 2592000 секунд (30 дней)
• FACE_SDK_PARAMETERS: Параметры используемого детектора:
  • score_threshold - порог детекции, от 0 до 1. Чем выше значение порога, тем больше лиц способен распознать детектор;
  • min_size, max_size - минимальный и максимальный размер лица для детекции в пикселях. Примечание: параметр нужно добавить в конфигурационный файл вручную.

2.2.5 Установка и настройка кластера

note::: Если у вас уже есть развернутый кластер, перейдите к пункту 2.2.7. :::

Запустите команду для создания и настройки кластера.

$ ./setup/init-cluster.sh

Эта команда выполняет следующие действия:

• Инициализация узла для развертывания кластера
• Создание секретов
• Создание необходимых папок
• Установка ingress-controller
• Установка nvidia-device-plugin, если включено использование видеокарты

2.2.6 Проверка работоспособности кластера

После инициализации главного узла убедитесь, что все узлы готовы к работе и имеют статус Ready. Для проверки выполните следующую команду:

$ kubectl get nodes

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

NAME          STATUS      ROLES                   AGE     VERSION
master-node   Ready       control-plane,master    11d     v1.23.8

Для проверки всех элементов кластера запустите следующую команду:

$ kubectl get all --all-namespaces

2.2.7 Использование локальной СУБД

примечание

По умолчанию используется локальная СУБД.

Для использования локальной СУБД, убедитесь, что на сервере, на котором будет развернута база данных, создана директория /kv/pgdata, в противном случае, создайте ее, выполнив следующие команды:

$ sudo mkdir -p /kv/pgdata
$ sudo chmod -R 777 /kv/pgdata

2.3 Настройка лицензирования

примечание

Если вы обновили платформу, используя команды из пункта 2.1, пропустите пункт 2.3 и перейдите к пункту 2.4.

2.3.1 Активация пробного периода

Важно:

• требуется подключение к сети Интернет;
• не допускается запуск OMNI Platform на виртуальной машине.

Активация пробного периода происходит при первом запуске OMNI Platform. Чтобы активировать пробный период, переходите к пункту 2.4.

2.3.2 Установка сервера лицензий

Перед установкой откройте файл ./setup/settings.env и задайте IP адрес машины, на которой будет установлен сервер лицензий, в переменной LICENSE_SERVER_IP_ADDRESS. Если сервер лицензий запускается на той же машине, где развернут кластер, то LICENSE_SERVER_IP_ADDRESS будет совпадать с MASTER_NODE_IP_ADDRESS.

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

$ ./setup/install-lic-server.sh

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

$ ./setup/status-license-server.sh

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

floatingserver.service - Floating License Server
    Loaded: loaded (/etc/systemd/system/floatingserver.service; enabled; vendor preset: enabled)
    Active: active (running) since Tue 2022-12-20 12:25:54 +05; 1min 48s ago

Убедитесь, что сервер лицензий доступен. Для этого перейдите по адресу http://<LICENSE_SERVER_IP_ADDRESS>:8090 в вашем браузере, на странице должна отобразиться форма входа.

2.3.3 Онлайн активация лицензии

Если у машины, на которой установлен сервер лицензий, нет доступа в глобальную сеть, пропустите этот пункт и перейдите к пункту 2.3.3.

Перед активацией убедитесь, что в переменной LIC_KEY (файл ./setup/settings.env ) записан лицензионный ключ.

Запустите команду активации лицензии:

$ ./setup/activate-lic-server.sh

Пример вывода в консоль при успешной активации лицензии:

[2022-12-20 12:25:53+05:00] INF Activating license key...
[2022-12-20 12:25:54+05:00] INF License activated successfully!

После успешной активации перейдите к пункту 2.4.

2.3.4 Офлайн активация лицензии

Перед активацией убедитесь, что в переменной LIC_KEY (в файле ./setup/settings.env ) записан лицензионный ключ.

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

$ ./setup/activate-lic-server.sh --generate-offline

В результате выполнения команды в директории on_premise должен появиться файл request-offline.license.

Отправьте сгенерированный файл запроса request-offline.license на почту support-platform@3divi.com. В ответном письме будет отправлен файл лицензии.

Поместите полученный лицензионный файл в папку on_premise.

Откройте файл конфигурации ./setup/settings.env, используя текстовый редактор, и заполните значение переменной OFFLINE_LICENSE_FILE именем файла лицензии и его расширением, если присутствует, через точку.

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

$ ./setup/activate-lic-server.sh --activate-offline

Пример вывода в консоль при успешной активации лицензии:

[2022-09-08 01:30:36+05:00] INF Offline activating license key...
[2022-09-08 01:30:36+05:00] INF License activated successfully!

2.4. Развертывание платформы

2.4.1 Запуск развертывания

Запустите скрипт для развертывания платформы в кластере:

$ ./setup/deploy.sh

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

$ watch 'kubectl get pods'

Наличие у всех pods статуса Running означает, что платформа запущена.

2.4.2 Настройка DNS

Для обеспечения доступа к платформе DNS сервер вашей сети должен содержать запись о том, что домен platform.<DOMAIN> доступен по адресу <MASTER_NODE_IP_ADDRESS>. Значения переменных можно получить из файла ./setup/settings.env, заполненного в пункте 2.1.3. Обратитесь к администратору вашей сети, чтобы выполнить данную конфигурацию.

Для целей тестирования можно указать IP-адрес и домен в файле /etc/hosts на Linux или C:\Windows\System32\drivers\etc\hosts на Windows.

Для этого добавьте в конец данного файла новую строку вида <MASTER_NODE_IP_ADDRESS> platform.<DOMAIN>, подставив значения соответствующих переменных, и сохраните файл. Обратите внимание, что для редактирования файла hosts необходимо обладать правами администратора.

Для использования платформы с той же машины, где выполнено развертывание, можно воспользоваться скриптом. Он автоматически добавит необходимую запись в файл /etc/hosts.

$ ./setup/add-dns.sh

2.4.3 Описание элементов развернутой системы

Для получения статуса сервисов платформы выполните команду:

$ kubectl get pods

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

NAME                                                        READY          STATUS         RESTARTS         AGE
activity-matcher-dep-6fdc8bfbd5-pl8ql                        1/1           Running         2 (24h ago)     24h
age-estimator-dep-544cdfd7c-4khhh                            1/1           Running         0               24h
agent-sync-dep-854474ddc9-ntd2w                              1/1           Running         2 (24h ago)     24h
backend-dep-74c5d86d77-wldcn                                 1/1           Running         2 (24h ago)     24h
body-detector-dep-788dc59547-5jqtf                           1/1           Running         0               24h
broker-dep-f6dfdf55b-kl76k                                   1/1           Running         0               24h
cache-dep-7dbc644bcf-6qpzb                                   1/1           Running         0               24h
db-dep-cf96d8d4c-btmbf                                       1/1           Running         0               24h
emotion-estimator-dep-764c8d8669-wzssn                       1/1           Running         0               24h
face-detector-face-fitter-dep-8585d54d67-j2k88               1/1           Running         0               24h
face-detector-liveness-estimator-dep-66c8789ddb-x4h95        2/2           Running         0               24h
face-detector-template-extractor-dep-6b844fdfd9-tjprf        1/1           Running         0               24h
gateway-dep-67c7d6f4c7-5lpsb                                 1/1           Running         0               24h
gender-estimator-dep-7b7d859c6f-n9f76                        1/1           Running         0               24h
image-api-dep-6dc7f868f6-gz56v                               1/1           Running         0               24h
licensing-dep-967cc7b65-wg6jq                                1/1           Running         0               24h
mask-estimator-dep-7db6779bc5-nnwt5                          1/1           Running         0               24h
matcher-dep-696d66b65b-fqn9z                                 1/1           Running         2 (24h ago)     24h
processing-dep-f7d7867f6-25tjl                               1/1           Running         0               24h
quality-assessment-estimator-dep-76fcfdf6cf-zjldq            1/1           Running         0               24h
quality-dep-86cc5488d9-22tkn                                 1/1           Running         0               24h
redis-dep-5d8cd4d657-7vw8c                                   1/1           Running         0               24h
securos-integration-service-dep-77f98b497d-66q               1/1           Running         0               24h
verify-matcher-dep-85ddfdfd4f-7t7br                          1/1           Running         0               24h

Ниже приведено краткое описание сервисов:

• activity-matcher-dep - сервис используется для поиска людей по активностям;
• age-estimator-dep - сервис используется для оценки возраста человека по изображению лица;
• agent-sync-dep - сервис отвечает за синхронизацию данных о профилях с OMNI-агентами;
• backend-dep - основной контейнер платформы, отвечает за работу большей части API;
• body-detector-dep - сервис предназначен для детекции силуэтов на изображении;
• broker-dep - сервис RabbitMQ, используется для работы асинхронной очереди задач;
• cache-dep - сервис Memcached, используется для кэширования данных;
• db-dep - экземпляр СУБД PostgreSQL, хранит всю информацию платформы;
• emotion-estimator-dep - сервис используется для оценки эмоций человека по изображению лица;
• face-detector-face-fitter-dep - сервис используется для детекции лиц и определения антропометрических точек лица и углов наклона/поворота головы;
• face-detector-liveness-estimator-dep - сервис используется для детекции лиц и оценки принадлежности лица на изображении реальному человеку;
• face-detector-template-extractor-dep - сервис предназначен для детекции лиц и извлечения биометрического шаблона лица;
• gateway-dep - cервис nginx, отвечает за доступ к платформе и за работу веб-интерфейса платформы;
• gender-estimator-dep - сервис используется для оценки пола человека по изображению лица;
• image-api-dep - сервис ImageAPI, доступный по URL /image-api/ (является устаревшим, используется для обратной совместимости);
• licensing-dep - сервис, ограничивающий работу платформы согласно параметрам лицензии;
• mask-estimator-dep - сервис позволяет определить наличие/отсутствие медицинской маски на лице человека;
• matcher-dep - сервис используется для поиска людей по профилям;
• processing-dep - сервис аккумулирует результаты работы сервисов-обработчиков (age-estimator-dep, emotion-estimator-dep, gender-estimator-dep,face-detector-face-fitter-dep, mask-estimator-dep
• face-detector-liveness-estimator-dep);
• quality-assessment-estimator-dep - сервис предназначен для оценки качества изображения лица;
• quality-dep - сервис отвечает за расчет качества изображения (является устаревшим, используется для обратной совместимости);
• redis-dep - сервис Redis, используется для работы WebSockets;
• securos-integration-service-dep - отвечает за интеграцию с продуктом SecurOS;
• verify-matcher-dep - сервис отвечает за сравнение двух лиц с изображений.

2.4.4 Масштабирование

В случае, когда нагрузка возрастает, для стабилизации работы платформы предусмотрено масштабирование следующих сервисов в ручном режиме:

• processing-dep
• quality-dep
• face-detector-liveness-estimator-dep
• backend-dep
• gateway-dep
• ingress-nginx-controller

Описание сервисов указано в пункте 2.4.3.

Для масштабирования сервиса необходимо выполнить следующую команду:

$ kubectl scale deployment <SERVICE_NAME> --replicas <COUNT>

где <SERVICE_NAME> - наименование сервиса (например, gateway-dep), а <COUNT> - количество экземпляров сервиса.

примечание

Для масштабирования сервиса ingress-nginx-controller необходимо в конец команды добавить аргумент “-n ingress-nginx”.

примечание

При использовании GPU ускорения сервис processing-dep поддерживает только один экземпляр, а значит его нельзя масштабировать.

При масштабировании необходимо руководствоваться следующей информацией:

Для обработки большего числа одновременно поступающих запросов, следует масштабировать backend-dep, ingress-nginx-controller, gateway-dep. Количество экземпляров сервисов необходимо указывать согласно формуле: <REQUESTS>/<CPU_COUNT>, где <REQUESTS> - это желаемое количество запросов, одновременно находящихся в обработке, а <CPU_COUNT> - это количество логических ядер ЦП.

Если большая часть запросов связана с обработкой изображений, необходимо масштабировать processing-dep и quality-dep. Количество экземпляров сервисов не должно превышать количество физических ядер ЦП.

Пример: Для поддержания нагрузки в A запросов/сек, направленной на обработку изображений, на сервере с физическим количеством ядер ЦП равным B и логическим количество ядер равным C, следует масштабировать сервисы следующим образом:

processing-dep - min(A, B) экземпляров quality-dep - min(A, B) экземпляров face-detector-liveness-estimator-dep - min(A, B) экземпляров backend-dep - A/C экземпляров gateway-dep - A/C экземпляров ingress-nginx-controller - A/C экземпляров

Для сохранения параметров масштабирования, откройте файл ./deploy/values.yaml, найдите блок service_replicas и укажите для сервисов новые подобранные значения.

При следующих установках Платформы сервисы будут автоматически масштабироваться до указанных значений.

примечание

Для сохранения параметров масштабирования сервиса face-detector-liveness-estimator-dep воспользуйтесь конфигурационным файлом ./deploy/services.json

2.4.5 Резервное копирование и восстановление базы данных

Примечание: Не поддерживается для внешних баз данных.

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

$ ./setup/db-backup.sh <dump_path>

Для восстановления базы данных выполните следующую команду:

$ ./setup/db-restore.sh <dump_path>

к сведению

Для восстановления данных из резервной копии необходимо иметь развернутый экземпляр платформы той же версии, с которой была создана резервная копия, и использовать скрипт ./setup/db-restore.sh поставляемый с ней же. dump_path - путь до дампа базы данных