Руководство по системному администрированию#

Сценарии администрирования#

Для выполнения сценариев администрирования не требуется какая-либо роль согласно ролевой модели Компонента.

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

• в секретах системы управления контейнерами;

• в файловой системе pod. Все токены, пароли, сертификаты и иная чувствительная информация получена из внешней системы хранения секретов Secret Management System.

Стратегия снятия резервных копий зависит от критичности данных, подлежащих сохранению, и определяется группой сопровождения.

Компонент BPM User Plane (далее по тексту – BPMU) продукта Platform V Flow состоит из следующих модулей:

• bpmu-data-index;

• bpmu-console;

• bpmu-testing;

• один из модулей для режима аутентификации и авторизации bpmu-server-sudir/bpmu-server-token/bpmu-server-spas.

Для каждого из модулей есть файл application.properties, который содержит блоки для настроек. Основные настройки для сервисов:

bpmu-data-index

• блок kafka – настройки подключения к kafka (настройки описаны в разделе «Блок настроек BPMU»);

• блок mp.messaging – настройки topics чтения истории;

• блок auth — настройки, связанные с аутентификацией пользователя (рекомендуемые режимы и настройки);

• блок audit – настройки для подключения к сервису аудита;

• блок tracing – настройки для подключения к сервису tracing;

• блок metric – настройки Spring actuator, необходимые для получения метрик;

• блок oidc — настройки для аутентификации и авторизации.

Модули bpmu-console и bpmu-testing воспроизводятся на базовом образе Nginx. Особенности администрирования отсутствуют.

Для каждого из модулей для режима аутентификации и авторизации – bpmu-server-sudir/bpmu-server-token/bpmu-server-spas также есть файл application.yml. Информация о доступных настройках описана в документе «Настройки режимов аутентификации и авторизации пользователей».

К сценариям администрирования относятся все действия и настройки, указанные в этом разделе, а также просмотр журналов (logs) и метрик мониторинга.

Сценарий «Управление конфигурацией»#

Настройка аутентификации и авторизации#

Подробнее о каждом режиме аутентификации и авторизации описано в документе «Настройки режимов аутентификации и авторизации пользователей».

Если валидация не прошла успешно, приложение не запускается. В log-файл приложения добавляется соответствующая запись.

Блок настроек BPMU#

Настройка Prometheus/Объединенный мониторинг Unimon (MONA) Platform V Monitor (OPM)#

Для подключения компонента Объединенный мониторинг Unimon (MONA) Platform V Monitor (OPM) требуется указание дополнительных аннотаций в service.

prometheus.io.port = '8180' prometheus.io.path = '/q/metrics'

Список метрик доступен в разделе «События мониторинга».

Настройка подключения к БД#

Настройки bpmu-data-index осуществляются через файл application.properties.

Настройка подключения к БД осуществляется в блоке datasource:

• db-kind – тип подключаемой БД;

• secretName – Имя секрета БД в SecMan;

• jdbc.url – адрес подключения к БД.

Создание структуры БД происходит автоматически во время инициализации (запуска) приложения.

Важно! Необходима установка расширения pg_trgm для конкретной схемы БД используемой сервисом индексирования

CREATE EXTENSION pg_trgm with schema bpmx_data_index_schema;

Отключение функционала автоматического обновления БД возможно с помощью настройки:

quarkus.liquibase.migrate-at-start: true

Настройка подключения к БД осуществляется в модуле bpmu-data-index компонента BPMU в блоке "PostgreSQL" документа «Используемые параметры bpmu-data-index.conf».

Настройка работы с PostgreSQL версии 12 и выше#

Активация режима работы с PostgreSQL версии 12 и выше осуществляется с помощью настройки:

data-index.enable-postgres-12-features

В случае, если фактически используется версия 12 и выше, но значение параметра равно false, приложение может работать нестабильно, и тогда будет отброшено соответствующее предупреждение в логи. В случае, если значение параметра равно true, но фактически используется версия PostgreSQL ниже 12, приложение будет принудительно приведено в режим работы как при параметре равном false, а в лог-файлы будет отброшено соответствующее предупреждение.

Настройка подключения к Kafka#

Настройка подключения к Kafka осуществляется в блоке kafka

• kafka.bootstrap.servers – адрес kafka брокера.

Настройка topics чтения истории осуществляется в блоке mp.messaging

• incoming.process-instance-update-event.topic – имя topic для чтения событий по экземплярам процессов;

• incoming.process-instance-update-event.group.id – идентификатор группы потребителей;

• incoming.process-instance-update-event.partitions – количество партиций topic.

Чтение событий может осуществляться посредством брокера сообщений Kafka и подробно описаны в блоках "Kafka Channel Process Instance" и "Kafka Channel Process" документа «Используемые параметры bpmu-data-index.conf».

Далее будут описаны схемы событий.

Схема события для экземпляров процессов

Информация, доступная о контексте процесса:

• GlobalInstanceID – ID процесса (в формате UUID), который пользователи могут передавать со стартовым сообщением. Если GlobalInstanceID не задан явно, то он генерируется произвольно, также в формате UUID (BusinessKey не выводится в Контекст процесса, но фактически имеет то же значение, что и GlobalInstanceID);

• FLOW_PID – служебное поле контекста (processInstanceID – идентификатор экземпляра процесса).

Настройка отправки сообщений в компонент продукта Platform V Audit SE (AUD) – Аудит (AUDT)#

Настройка отправки сообщений в компонент Аудит (AUDT) продукта Platform V Audit SE (AUD) осуществляется в блоке audit

• proxyUri — адрес сервиса Аудит (AUDT) продукта Platform V Audit SE (AUD);

• proxyVersion — версия протокола взаимодействия (строка, возможное значение v1);

• eventMode — тип передачи данных в Аудит (AUDT) продукта Platform V Audit SE (AUD): Быстрый/Надежный (Speed/Reliability). По умолчанию Reliability;

• nodeId — имя namespace, в который устанавливается модуль, для передачи в Аудит (AUDT) продукта Platform V Audit SE (AUD) (ex. hostname);

• retryTimeout — время ожидания перед повторной отправкой сообщения (мс);

• maxQueueSize — максимальное количество сообщений в очереди на отправку в Аудит (AUDT) продукта Platform V Audit SE (AUD);

• timeout:

  • connection-request — время ожидания подключения к сервису (мс);

  • connect — время ожидания соединения (мс);

  • read — время ожидания чтения сокета (мс).

Более подробно настройки указаны в разделе «Настройки аудита» документа «Используемые параметры bpmu-data-index.conf».

Настройка работы трейсинга#

Настройка работы трейсинга осуществляется в блоке quarkus.jaeger

• metrics.enabled — включение/выключение трейсинга;

• endpoint — URL трейсинг-коллектора;

• service-name — наименование сервиса data-index в системе трейсинга;

• zipkin.compatibility-mode — формат отправки span (true – отправка span в формате zipkin).

Более подробно настройки указаны в разделе «Трейсинг» документа «Используемые параметры bpmu-data-index.conf».

Настройка отправки метрик#

Настройка отправки метрик осуществляется в блоке quarkus.smallrye-metrics

• micrometer.compatibility — включение/выключение отправки метрик;

• jaxrs.enabled — включение jvm метрик.

Более подробно настройки указаны в разделе «Настройки метрик» документа «Используемые параметры bpmu-data-index.conf».

Настройки очистки истории и партиционирования#

Настройка механизма очистки удаленных данных из БД осуществляется в блоке kogito.data-index.history.

Механизм очистки удаляет данные из БД партициями по дате завершения родительского процесса.

• clear.enabled — включение/выключение автоматической очистки истории;

• clear.schedule — настройка расписания в формате Cron;

• storage-depth-in-days — глубина партиций в днях, которые будут оставлены. Дата, с которой будут удаляться партиции = текущая дата – storage-depth-in-days;

• partition-size-in-days — количество партиций в сутках;

• create-partitions.schedule — настройка периодичности запуска механизма партиционирования данных в cronlike формате;

• create-partitions.days-to-create — количество дней, на которое будут созданы партиции.

Более подробно настройки указаны в разделе «Настройки очистки истории и партиционирования» документа «Используемые параметры bpmu-data-index.conf».

Настройка ограничения доступности процессов по бизнес-ролям#

Настройка ограничения доступности процессов по бизнес-ролям осуществляется в блоке data-index

• owner-role-restriction — включение/выключение разграничения видимости процессов/экземпляров процессов по бизнес-ролям пользователя.

data-index:
  owner-role-restriction: true

Настройка доступности контекста#

Настройка доступности контекста осуществляется в блоке data-index

• context-visible — включение/выключение доступности контекста при выполнении graphQL запросов получения информации об экземпляре процесса.

data-index:
  context-visible: true

Настройка работы с пользовательскими задачами#

Настройка интеграции с UTSK для завершения задачи осуществляется в блоке htm

• enabled — включение интеграции с UTSK.

• url — url для обращения к system API UTSK.

htm:
  enabled: true
  url: http://some-host:8080/

Настройка работы с массовыми операциями#

Настройка работы с массовыми операция повтора и прерывания экземпляров процессов осуществляется в блоке bulk-operations:

• timeout — максимальное доступное время для выполнения массовых операций (мс);

• count-limit — максимальное количество экземпляров для массовой операции.

bulk-operations:
  timeout: 10000
  count-limit: 10000

Настройка URL ресурса с документацией продукта Platform V Flow#

Настройка URL для перехода на ресурс с документацией продукта Platform V Flow осуществляется в блоке data-index:

• documentation-url — url ресурса с документаций продукта Platform V Flow;

data-index:
  documentation-url: https://example-doc-link/index.html

Варианты импорта моделей процессов#

Импорт через графический интерфейс тестовой консоли (bpmu-testing)#

1. В тестовой консоли (bpmu-testing) перейти в раздел Процессы и нажать на кнопку Загрузить.

2. Ввести Endpoint для загрузки (укажите URL модуля bpmx-gateway компонента Engine (BPMX) продукта Platform V Flow (BPN)), загрузить файл с моделью или архив через кнопку Загрузить.

3. Нажать на кнопку Загрузить.

4. В результате файл/архив с моделями будет загружен в BPMX.

Импорт с помощью CURL через GraphQL (для загрузки файлов)#

1. Необходимо выполнить запрос к bpmu-testing:

POST https://укажите Endpoint URL bpmu-data-index/graphiql

–form 'operations="{"query":"\n mutation uploadProcessesArchive($endpoint: String, $file: [Upload!]!) {\n ProcessesUploadArchive(endpoint: $endpoint, file: $file)\n}\n ","variables":{"endpoint":"http://укажите URL bpmx-gateway:8080","file":null},"operationName":"uploadProcessesArchive"}"'
–form 'map="{"1":["variables.files.0"],"2":["variables.files.1"],"3":["variables.files.2"]}"'
–form '1=@"…/simpleMessage-no-owner.bpmn"'
–form '2=@"…/simpleMessage-owner1.bpmn"'
–form '3=@"…/simpleMessage-owner2.bpmn"'

В данном случае Endpoint указывается в самом теле запроса.

Импорт с помощью CURL через GraphQL (для загрузки архива)#

1. Необходимо выполнить запрос к bpmu-testing:

POST https://укажите Endpoint URL bpmu-data-index/graphiql

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

–form 'operations="{"query":"\n mutation uploadProcessesArchive($endpoint: String, $file: [Upload!]!) {\n ProcessesUploadArchive(endpoint: $endpoint, file: $file)\n}\n ","variables":{"endpoint":"http://bpmx-svc-bpmx-gateway-standID-unver:8080","file":null},"operationName":"uploadProcessesArchive"}"'
–form 'map="{"1":["variables.file"]}"'
–form '1=@"…/archivename.zip"' (полный путь до архива)

В данном случае Endpoint указывается в самом теле запроса.

Интеграция с внешними системами#

Интеграция с компонентом Аудит (AUDT) продукта Platform V Audit SE (AUD)#

В связи с требованиями безопасности рекомендуется осуществлять передачу информации о произведенных действиях в компонент Аудит (AUDT) продукта Platform V Audit SE (AUD).

Журнал регистрации событий, отправляемых в компонент Аудит (AUDT) продукта Platform V Audit SE (AUD), хранится в компоненте Аудит (AUDT) продукта Platform V Audit SE (AUD).

В файле конфигурации application.properties в сервисе bpmu-data-index в блоке audit представлены настройки подключения к аудиту.

Взаимодействие производится через Rest API.

Среда исполнения осуществляет отправку следующих данных для фиксации события в компоненте Аудит (AUDT) продукта Platform V Audit SE (AUD):

1. Метамодель;

2. Событие.

Вызываемое API зависит от режима работы Аудит:

• Регистрация метамодели:

  • $audit_URL/v1/metamodel;

  • $audit_URL/v1/rn/{rn}/metamodel;

• Отправка события:

  • $audit_URL/v1/event;

  • $audit_URL/v1/rn/{rn}/event.

Интеграция с компонентом Журналирование (LOGA) продукта Platform V Monitor (OPM)#

Протоколирование операций для их дальнейшего анализа осуществляется в следующую директорию:

-DloggingDir = home/logs
-DloggingJSONFile = log.json

Для отправки событий журнала в Logger sidecar-контейнер должен быть подключен к тому же каталогу, что обеспечит ему возможность чтения и обработки событий.

Для корректного разбора событий необходимо, чтобы формат событий соответствовал шаблону разбора fluent-bit. Формат событий описан в xml-файле конфигурации для библиотеки logback-spring.xml.

Рекомендации по использованию механизмов безопасности#

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

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

2. Разделять среды разработки, тестирования и эксплуатации.

3. Администраторам системы осуществлять контроль использования средств защиты информации.

4. Использовать компоненты аутентификации, авторизации и аудита в качестве внешних средств защиты.

События системного журнала#

Все события, собираемые компонентом во время работы, публикуются в компоненте Журналирование (LOGA) продукта Platform V Monitor (OPM), далее по тексту – Журналирование.

Настройки интеграции с компонентом описаны в разделе «Интеграция с внешними системами».

События регистрируются в формате json. Журнал регистрации событий располагается в АРМ Журналирование (LOGA) продукта Platform V Monitor (OPM). Местоположение АРМ сервиса Журналирования необходимо уточнять у администраторов сред.

Регистрируются события уровней:

• TRACE – менее приоритетные записи (logs) для отладки, с наименьшим уровнем логирования;

• DEBUG – записи (logs), необходимые для отладки приложения. Для уверенности в том, что приложение делает именно то, что от нее ожидают, или описания действия приложения;

• INFO – записи (logs), которые записывают важные действия в приложении. Это не ошибки, это не предостережение, это ожидаемые действия приложения;

• WARN – обозначаются записи (logs), которые содержат предостережение. Произошло неожиданное действие, несмотря на это приложение устояло и выполнило запрос;

• ERROR – уровень ошибок, когда есть проблемы, которые нужно решить. Ошибка не останавливает работу приложения в целом. Остальные запросы могут работать корректно;

• FATAL – ошибка, после которой приложение уже не сможет работать и будет остановлено.

Перечень событий модуля bpmu-data-index:

Трассировка запросов#

В некоторые события логирования после включения и настройки сервиса трассировок (группа настроек tracing) будут добавлены заголовки x-request-chain-id входящих HTTP-запросов.

• По умолчанию данные категории имеют уровень логирования "ERROR".

События мониторинга#

Настройки интеграции с компонентом описаны в разделе «Настройка Prometheus/Объединенный мониторинг Unimon (MONA) Platform V Monitor (OPM)».

Предварительно потребитель должен создать подключение к компоненту Объединенный мониторинг Unimon (MONA) Platform V Monitor (OPM), используя соответствующий resourceName.

Метрики выставляются в формате prometheus. Подробная информация о выставляемых метриках в документации:

• hikaricp;

• JVM;

• Kafka.

Для отключения сбора метрик производительности UI необходимо отключить настройку data-index.metrics.ui.publish=false (по умолчанию прописано значение true)

Метрики bpmu-data-index

Часто встречающиеся проблемы и пути их устранения#

Проблемы поведения модуля bpmu-data-index#

Диагностирование и решение проблем поведения модуля bpmu-data-index:

• Если после запуска процесса на UI не отображается информация о запущенном экземпляре и в лог-записях модуля bpmx-engine компонента Engine (BPMX) продукта Platform V Flow (BPM) присутствует запись [WARN] "There is a difference in assigned asyncJobs and asyncStart partition numbers!" – необходимо сверить количество партиций в topics asyncJobs и asyncStart – оно должно быть одинаковым. В случае расхождения необходимо привести количество партиций к одному значению.

• Если изменение параметра pidPrefix не приводит к ожидаемым изменениям в генерации PID процесса, то проверьте наличие настройки параметра pidPrefix для двух модулей компонента BPMX: bpmx-gateway, bpmx-engine (файлы темплейтов bpmx-gateway-config.yaml и bpmx-engine-config.yaml).

Ошибки в лог-записях модуля bpmu-data-index:

• "Can't deserialize message. In topic: {}. Error: {}".

• "Problem with deserialization or received the message with null body".

• "Can't save the message to history …".

Появление данных ошибок свидетельствует о том, что модуль bpmu-data-index получает сообщения в неверном формате. Требуется установить источник сообщения и проверить настройки модуля-источника.

В случае возникновения ошибки вида "no healthy upstream" (отсутствует сетевая доступность с bpmu-dataindex) необходимо:

1. проверить pod bpmu-data-index;

2. поднять pod bpmu-data-index в случае необходимости;

3. проверить корректность настройки route.

Проблемы при старте процессов#

При старте процесса экземпляр не отображается на UI, а в лог-файлах присутствует запись [WARN] "Context cache size limit exceeded ({} > {}). New instances will not be started." Необходимо освободить текущий кеш (завершив процессы, находящиеся в статусе "Инцидент", если это возможно) или увеличить размер параметра engine.instanceCacheSoftLimit компонента BPMX в совокупности с лимитами памяти pod 'bpmx-engine'.

Проблемы в работе БД#

• Приложение работает нестабильно, а в лог-файлах присутствует запись The Postgres version in the application settings does not match the one actually used. The application is forced to work with Postgres version below 12. Причина в том, что при включенном режиме работы с PostgreSQL версии 12 и выше фактически используется PostgreSQL меньшей версии. Приложение было принудительно переведено к режиму работы с PostgreSQL ниже 12 версии.

• Приложение работает нестабильно, а в лог-файлах присутствует запись You are using Postgres version 12 or higher, but the corresponding data-index setting is not enabled. For stable operation, it is recommended to set the data-index.enable-postgres-12-features parameter to true. Причина в том, что используется версия PostgreSQL 12 или выше, но не активирована соответствующая настройка. Необходимо осуществить корректную настройку параметра data-index.enable-postgres-12-features. Подробнее можно прочитать в разделе «Настройка работы с PostgreSQL версии 12 и выше».

Проблемы при создании партиций#

При автоматическом создании партиций по cron может появиться ошибка из-за которой партиции не будут создаваться:

Caused by: org.postgresql.util.PSQLException: ERROR: updated partition constraint for default partition "processes_running" would be violated by some row
Where: SQL statement "create table processes_2023_10_17 partition of processes for values from ('2023-10-17') to ('2023-10-20')"

• Необходимо проверить таблицы processes_running и nodes_running на наличие записей, имеющих end_time не равный null. Эти экземпляры с их node необходимо перенести в отдельные, буферные таблицы, и удалить перенесенные экземпляры из *_running.

• Далее дождаться автоматического создания партиций, либо создать их с учетом настроек в data-index для партиционирования. Важно учесть, чтобы на все экземпляры были созданы партиции. Это можно узнать, посмотрев время завершения экземпляра и диапазон партиции.

• Из буферных таблиц перенести данные в созданные таблицы с учетом времени завершения.

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

create table processes_{DATE_FROM} partition of processes for values from ('DATE_FROM') to ('DATE_TO');

Скрипт для создания партиций node:

create table nodes_{DATE_FROM} partition of nodes for values from ('DATE_FROM') to ('DATE_TO');

Ошибка в случае большого количества операций с процессом/экземпляром#

В случае большого количества выполненных операций с процессом/экземпляром возникает ошибка сохранения данных в БД модуля bpmu-data-index компонента BPMU:

2023-10-18 08:17:49,346 WARN  [org.hib.eng.jdb.spi.SqlExceptionHelper] (pool-17-thread-1) SQL Error: 0, SQLState: 54000
2023-10-18 08:17:49,347 ERROR [org.hib.eng.jdb.spi.SqlExceptionHelper] (pool-17-thread-1) ERROR: index row size 2720 exceeds btree version 4 maximum 2704 for index "operation_ids_index"
  Detail: Index row references tuple (5,5) in relation "process_definition".
  Hint: Values larger than 1/3 of a buffer page cannot be indexed.
Consider a function index of an MD5 hash of the value, or use full text indexing.

Для устранения проблемы необходимо воспользоваться sql скриптом очистки операций clean_operation_ids.sql, поставляемом в дистрибутиве.