2. Инструкция по развертыванию
2.1. Обновление платформы
Если вы получили новую версию платформы и при этом уже используете развернутую версию, последовательно выполните описанные ниже команды, в противном случае пропустите пункт 2.1.
Важно: Перед обновлением платформы с версии 1.11.0 (и ниже) на версию 1.12.0 (и выше) для сохранения доступа к данным в базе данных, необходимо выполнить следующие шаги:
- Загрузите и распакуйте новую версию платформы.
- Перенесите существующие учетные данные для доступа к СУБД в конфигурационный файл новой версии платформы в папке
on_premise. Для этого откройте конфигурационный файл./setup/settings.envпредыдущей версии платформы и перенесите значения параметровPOSTGRES_USER,POSTGRES_PASSWORDиPOSTGRES_DBв конфигурационный файл./deploy/services_db_config.jsonновой версии платформы в блокstorage-engine-db. - Используя значения из файла, создайте базы данных и пользователей для каждого блока (за исключением
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> - данные БД и пользователя блока для соответствующего сервиса.
Удаление предыдущей версии платформы
- Перейдите в папку
on_premiseразвернутой версии платформы и остановите платформу, выполнив команду:
$ ./setup/uninstall-platform.sh
- Убедитесь, что все контейнеры сервисов остановлены. Для этого используйте команду:
$ watch 'kubectl get pods'
Статус сервисов из состояния Running должен перейти в состояние Terminating. В результате, все сервисы должны пропасть из отображаемой таблицы.
- Удалите развернутый Kubernetes кластер, выполнив команду:
$ sudo kubeadm reset
- Удалите вспомогательные файлы Kubernetes кластера с помощью команды:
$ sudo rm -rf ~/.kube/
- Выполните сброс таблиц 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 запроса может увеличиться в несколько раз. Также, обратите внимание, что увеличение лимитов приведет к ухудшению работы системы.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 - путь до дампа базы данных