Руководство администратора

Настройка DevOps

Определение наименования проекта DevOps

Перед началом настройки необходимо определить имя для проекта DevOps. Данное имя будет использоваться в дальнейших инструкциях, поэтому его необходимо запомнить.

Правила формирования имени проекта DevOps:

• название должно состоять только из символов английского алфавита, должно быть в нижнем регистре, не содержать каких-либо специальных символов (включая "-", "_") и пробелов. Допустимо использование цифр, если они не являются первыми символами названия;
• в качестве названия необходимо указать либо название продукта (не модуля), либо название банка, для конфигурации которых создаётся проект.

Запрещено использование следующих наименований для проекта: dev, usr, release, rc.

Создание эталонной базы данных проекта

Перед созданием проекта необходимо подготовить эталонную базу данных проекта. Для этого необходимо определить список существующих схем БД, которые будут использоваться в проекте.

Список модулей и их БД:

1. QBPD - Дизайнер бизнес-процессов и бизнес-правил (Business Process Designer): qbpmdesigner
2. QC - Управление бизнес-процессами (Cockpit): qbpmcockpit
3. QHT - Пользовательские задания (Human Task): dqhumantask
4. QBPET - Средства исполнения бизнес-процессов (Q.BPM Player): qbpetqbpmplayer
5. QAL - Список заявок (Application List): qbpmapplist

Формирование списка образов для установки на стенд

Инструмент установки приложений поддерживает два варианта установки Docker-образов на стенд:

• установка образа по ссылке (на базовый образ);
• установка образа из соответствующей проекту ветки реестра образов.

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

• все смежные модули (системное окружение и другие смежные модули, не разрабатываемые командой) необходимо устанавливать из готового образа;
• модули, разрабатываемые командой, необходимо устанавливать из отдельной ветки реестра образов.

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

• в config.yml ветки проекта в devops_configs (opens in a new tab) добавить/изменить следующий параметр: module_list_from_file: "combo";
• добавить файл module-list.yml в ту же папку, где размещён файл config.yml, с содержанием используемых модулей.

Образы в проектной ветке реестра образов создаются автоматически при первоначальной настройке DevOps в соответствующем модуле.

На ВМ devops по пути папки проекта необходимо разместить sh файл для получения образов из реестра.

Создание Namespace

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

Для создания неймспейса требуется предоставить следующую информацию:

• devopsProject – ветка проекта в репозитории devops_configs;
• stage - этап в ветке проекта в репозитории devops_configs;. По умолчанию – dev;
• registryStage - этап в реестре Docker-образов. Для обычных стендов обычно равен dev, а для персональных – логину пользователя, для которого создаётся стенд;
• namespace - наименование создаваемого Namespace в Q.RunneR;
• team – наименование производственной команды, ответственной за Namespace;
• devops - EMail сотрудника, ответственного за Namespace.

Создание ветки в репозитории devops_configs

Запросить права на работу в репозитории GIT devops_configsи авторизоваться.

Перейти в интерфейс создания новой ветки в репозитории GIT devops_configs. В открывшемся интерфейсе в поле Branch nameввести название новой ветки, соответствующее наименованию проекта DevOps, для которого производится настройка (см. п. 1). Если ветка создаётся для проекта, основанного на микросервисной, либо гибридной архитектуре, в поле Create from необходимо ввести значение template_micro_pg.

Нажать кнопку Create branch.

Создание репозитория и сборки микросервиса на базе Q.BPM Player

Для создания прикладных микросервисов на базе Q.BPM Player должен быть использован базовый образ Q.BPM Player. Алгоритм создания репозитория и сборки для прикладного микросервиса следующий:

• Для каждого разворачиваемого микросервиса на базе Q.BPM Player (далее модуль) в GitLab должен быть создан собственный отдельный репозиторий;

  Структура репозитория микросервиса должна быть следующая: Каталог модуля

  • Проект (main)
    • Ресурсы (resource)
      • Схемы (schemas)
        • Схема – файл .json
      • Процесс – файл .bpmn
  • Docker
    • Dockerfile-database.txt
    • Dockerfile-service.txt
    • properties.properties
  • pom.xml

• В репозитории модуля должен быть расположен каталог проекта «main», где нет java кода, каталог «Docker» и файл pom.xml;

• В каталоге «main» должен быть расположен каталог «resource», где должны содержаться только ресурсы (процесс + схема (объект)). Для хранения схем в каталоге «resource» должен быть выделен каталог «schemas». Хранение схем (объектов) в отдельном каталоге необходимо для обеспечения однозначной идентификации бизнес-объекта, необходимого для запуска модуля. Таким образом, библиотека динамических атрибутов однозначно определяет схему, необходимую для запуска модуля. В частных случаях сервис может стартовать без схем;

• В каталоге «Docker» должны быть расположены Dockerfile-database.txt и Dockerfile-service.txt - инструкции для сборки docker-образа Q.BPM Player. В файлах Dockerfile-database.txt и Dockerfile-service.txt должно быть указано расположение хранилища, где хранится образ Q.BPM Player определенной версии, указано расположение файл.jar и параметры запуска;

• Пример GIT QHT/qhtbpm (opens in a new tab);

• Далее настройка Jenkins файла полностью идентична настройка MSA и процесс выпуска построен точно так же.

Обновление базового образа Q.BPM Player

Для обновления базового образа плеера необходимо:

1. Перейти в репозиторий плеера в каталог docker
2. В файлах Dockerfile-database.txt и Dockerfile-service.txt указать актуальную версию образа из registry-new.diasoft.ru/release

3. Зафиксировать изменения. Начнется сборка модуля на обновленном образе
4. Если в docker указана версия release, достаточно перезапустить сборку
5. Обновить модуль на стенде

Установка прикладного сервиса на базе образа Q.BPM Player

В девопс репозитории необходимо добавить конфигурационный файл разворачиваемого (создаваемого) МС в формате namesService.property.

В конфигурационном файле описаны стандартные параметры относящиеся к DigitalQ платформе, например: AUTH_SERVER_URL, AUTH_PROVIDER, AUTH_SERVER_CONTEXT, DATASOURCE_URL, KAFKA_URL и т.д.)

Параметры Q.BPM Player:

• QBPM_PROCESS_INPUT_TOPICS - через точку с запятой топики для подписки
• QBPM_PROCESS_OUTPUT_TOPICS - через точку с запятой топики, в которые разрешена отправка (Пример: QBPM_PROCESS_OUTPUT_TOPICS = dsTaskCreateEvent;dsTaskCancelEvent;dsTaskActionEvent)
• QBPM_MODE - режим работы плеера dev/prod/run
• QBPM_DLQ_TOPICS - создание топиков с постфиксом dlq - по умолчанию false (true - создание включено; false - создание выключено)
• QBPM_LIMIT_DEFINITION_VERSIONS_ENABLED - автоудаление бизнес-процессов - по умолчанию false (true - автоудаление включено; false - автоудаление выключено)
• QBPM_LIMIT_DEFINITION_VERSIONS_COUNT - количество сохраненных процессов (по умолчанию 10)

Режим работы плеера dev/prod/run

Реализовано разделение диаграмм по областям/неимспейсам/профилям на два режима работы (в каждом из режимов у диаграмм параметр tenantId будет соответствующий):

1. DEV - все версии диаграмм помечаются специальной меткой. Активизируется job, который "чистит" активные процессы - завершает (будут иметь статус "Внешне завершенный") все активные экземпляры процессов, если они исполняются более 12ч. Также спустя один день исполнения экземпляра процесса по нему очищается история - удаляются записи в сервисе qbpetqbpmplayer таблицы: act_hi_*
2. PROD - режим по умолчанию, платформа работает, как и раньше. Публикуются диаграммы, хранится полная история и т.п.
3. RUN - все версии диаграмм помечаются специальной меткой. Активизируется job, который "чистит" активные процессы - завершает (будут иметь статус "Внешне завершенный") все активные экземпляры процессов, если они исполняются более 5 минут. Очищается история - удаляются записи в сервисе qbpetqbpmplayer таблицы: act_hi_*

При этом контроллеры в Swagger также разделены по профилям и не пересекаются.

Режим, настройка конфигурации QBPM_MODE, устанавливается вручную через конфиги Kubernetes. Эта доработка дает несколько плюсов и решает ряд проблем:

1. Проведение показов и важных презентаций в режиме PROD. Избавляет от демонстрации множества версий, на которых происходила отладка (мусор).
2. В режиме DEV можно удалять версии, как и сколько угодно. Режим PROD для использования финальной, рабочей, стабильной версии диаграммы (без возможности всякого удаления версий диаграмм).
3. Уменьшение потребления памяти сервисом.

Дополнительные возможности - реализация функционала тестового запуска экземпляра диаграммы. Кнопка Play открывает модальное окно, в котором указываются входные и выходные параметры, после чего можно запустить на исполнение экземпляр диаграммы в режиме RUN. Данный режим позволяет отлаживать небольшие "кусочки" большой диаграммы, которые разбиваются на подмножество диаграмм. Таким образом позволяя найти и устранить все дефекты при проектировании. При таком тестовом запуске все активные экземпляры диаграмм будут завершены, если исполняются более 5 минут. Также спустя один день исполнения экземпляра процесса по нему очищается история - удаляются записи в сервисе qbpetqbpmplayer таблицы:act_hi_*.

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

Хранение истории выполнения процессов

Для экономии памяти в БД можно настроить очистку истории выполненных процессов. Количество дней хранения истории выполнения процессов записывается в act_re_procdef.history_ttl_

Задать значение history_ttl_ - History Time To Live можно несколькими способами:

1. Можно полностью выключить хранение истории. В Дизайнере бизнес-процессов в свойствах процесса включить параметр Не хранить историю выполнения процесса. Настраивается отдельно на каждом процессе.
2. Задать количество дней хранения истории. В Дизайнере бизнес-процессов в свойствах процесса задать значение для параметра Время жизни истории. Настраивается отдельно на каждом процессе.
3. Задать в Q.BPM Player режим работы через параметр QBPM_MODE
4. Добавить в Мониторинг бизнес-процессов (qbpmcockpit) параметр QBPM_HISTORY_TIME_TO_LIVE и указать ему значение в днях. (Пример QBPM_HISTORY_TIME_TO_LIVE: P1D)

Возможности логирования и уровни

logging:
    config: classpath:log4j2.xml
level:
    root: ${LOGGING_ROOT_LEVEL:INFO} // логирование абсолютно всего
    ru.diasoft.micro: ${LOGGING_DIASOFT_LEVEL:${LOGGING_ROOT_LEVEL:INFO}} // логирование классов Диасофта
    org.hibernate.type: ${LOGGING_HIBERNATE_LEVEL:INFO} #To log values set TRACE // логирование запросов в БД
    org.apache.kafka.clients: ${LOGGING_KAFKA_LEVEL:INFO} // логирование кафка-клиента
    org.springframework.kafka.listener: ${LOGGING_KAFKA_LEVEL:INFO} // логирование лиснеров
    org.camunda.bpm.engine: ${LOGGING_CAMUNDA_LEVEL:INFO} // логирование всех действий камунды
    org.springframework.transaction: ${LOGGING_TRANSACTION_LEVEL:INFO} // логирование транзакций

Логирование всегда должно быть включено. По умолчанию логирование устанавливает в уровень ERROR, допускается использование всех модулей. Для режима PROD- рекомендуется выставлять уровень ERROR и только на необходимый модуль. Для режима DEV или RUN- рекомендуется выставлять уровень ALL, модуль "root".

Доступные режимы логирования:

• INFO - только информативные сообщения и то, что логируется в коде с уровнем INFO;
• ERROR - выводится информация по всем ошибкам;
• WARN - информация о различных предупреждениях;
• ALL - максимальный уровень, который выводит абсолютно все;
• DEBUG - режим отладки

Q.BPM Руководство по установке и запуску сервисов

Настройка проектного стенда и конфигурации для него в репозитории

devops_configs (opens in a new tab)

Настраивать можно по аналогии с веткой [omniplatform] (https://gitflex.diasoft.ru/devops/devops_configs/-/tree/omniplatform/devops/stages/dev (opens in a new tab)) Необходимо создать свою ветку: название ветки = название неймспейса

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

Примеры общих настроек неймспейса (БД PostgreSQL):

• config.yml - config.yml (opens in a new tab)
• Настройки БД всего стенда - dbservers.properties (opens in a new tab)
• Настройки шлюза - mdpgateway.properties (opens in a new tab)
• Настройки rulelist для работы шлюза в новом формате (opens in a new tab) - rulelist.yaml (opens in a new tab)

Примеры необходимых настроек для модулей:

1. Q.BPM UI (Рутовое приложение)
   • Настройки QBPM UI (стандартная авторизация через mdpauth)
   Пример содержимого конфигурационного файла
   • Настройки QBPM UI (Keycloak авторизация)
   Пример содержимого конфигурационного файла
2. QBPD - Дизайнер бизнес-процессов и бизнес-правил (Business Process Designer)
   qbpmdesigner.properties
3. QC - Управление бизнес-процессами (Cockpit)
   qbpmcockpit.properties
4. QHT - Пользовательские задания (Human Task)
   dqhumantask.properties
5. QHT - Пользовательские задания UI (Human Task UI)
   humantaskui.properties
6. QBPET - Средства исполнения бизнес-процессов (Q.BPM Player)
   qbpetqbpmplayer.properties

Копирование образов

Последние релизные версии образа:

• registry-new.diasoft.ru/release/qbpmui:24050501
• registry-new.diasoft.ru/release/qbpmdesigner:24042206
• registry-new.diasoft.ru/release/qbpmcockpit:24042501
• registry-new.diasoft.ru/release/dqhumantask:24042708
• registry-new.diasoft.ru/release/humantaskui:24042711
• registry-new.diasoft.ru/release/qbpetqbpmplayer:24042703

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

После 10.03.2023 в сервисах Q.BPM включена проверка на лицензирование.
Для оформления лицензии необходимо направить запрос на «CTL - входящие обращения ctl@diasoft.ru»

Модули, которые должны быть указаны в лицензии:

• QBPD - Управление бизнес процессами (qbpmdesigner)
• QC - Мониторинг бизнес-процессов (qbpmcockpit)
• QHT - Пользовательские задачи (dqhumantask)
• QBPET - Средства исполнения бизнес-процессов (qbpetqbpmplayer)

Настройка в неймспейсе через Kubernetes

1. Открыть Kubernetes, раздел Config Maps
2. Найти конфигурацию с наименованием share-config-volume
3. Открыть на редактирование
4. 
5. Найти в разделе data параметр license.xml:
6. 
7. Если данный параметр отсутствует - добавить параметр с названием license.xml
8. В значение параметра добавить все содержимое полученного файла license.xml
9. Сохранить конфигурацию share-config-volume по кнопке Update
10. В system-config либо в конфигурацию сервиса добавить параметр LPATH: /share/config/
11. Проверить значение параметра LPATH в сервисах Q.BPM. При необходимости изменить значение на корректное, либо отключить (удалить) параметр
12. После настройки параметра перезапустить сервисы Q.BPM

Настройка аутентификации в Kafka через SSL (Secure Sockets Layer)

Описание параметров

• KAFKA_SECURITY_PROTOCOL - протокол, по которому сервис подключается к брокеру, по умолчанию ”PLAINTEXT для включения SSL необходимо задать значение ”SSL”.
• KAFKA_TRUSTSTORE_LOCATION - путь до хранилища доверенных сертификатов, по умолчанию пустой, значение должно начинаться с указания протокола ”file:// после этого указывается полный путь до файла.
• KAFKA_TRUSTSTORE_PASSWORD - пароль от хранилища доверенных сертификатов, по умолчанию пустой.
• KAFKA_KEYSTORE_LOCATION - путь до хранилища приватных ключей, по умолчанию пустой, правила заполнения аналогично KAFKA_TRUSTSTORE_LOCATION.
• KAFKA_KEYSTORE_PASSWORD - пароль от хранилища приватных ключей, по умолчанию пустой.
• KAFKA_KEY_PASSWORD - пароль от приватного ключа, по умолчанию пустой.

Параметры необходимо добавить в файл с настройками сервиса на стенде и в файл, который загружается на стенд при установке/обновлении сервиса (application.properties или application.yaml)

Настройка сервисов для работы с Keycloak-авторизацией

Для использования ВPM-сервисов на стенде с Keycloak необходимо:

1. Выполнить шаги согласно инструкции (opens in a new tab)

2. Установить актуальные версии сервисов

• qbpmdesigner
• qbpetqbpmplayer
• dqhumantask
• qbpmcockpit
• qunnotification
• mdpemployee
• mdpdepartments
• mdpusers
• mdproles
• mdprefs

3. Если необходим справочник сотрудников и подразделений с qwork - в платформенных сервисах mdpemployee и mdpdepartments в dbsecret настроить подключение к БД qwork

4. В Kubernetes в сервисных конфигурационных файлах добавить параметры

• QOAUTH_MODE
• RESOURCE_SERVER_ID
• AUTH_SERVER_PUBLIC_KEY

5. Убрать параметр AUTH_PROVIDER=digitalq

6. В системной конфиг-мапе добавить параметр KUBERNETES_LEGACY_MOD=true

7. В BPM-сервисах включить параметр SECURITY_ENABLED=true

8. Параметры для добавления технического пользователя в Q.BPM Player

• KEYCLOAK_AUTH_URL
• KEYCLOAK_CLIENT_ID
• KEYCLOAK_CLIENT_SECRET
• KEYCLOAK_SCOPE
• KEYCLOAK_GRANT_TYPE
• TECH_AUTH_SERVICE_NAME // имя сервиса авторизации
• TECH_USERNAME // логин технического пользователя
• TECH_PASSWORD // пароль технического пользователя

9. После выполнения настроек перезапустить сервисы Пример настроенного стенда (opens in a new tab)

Завершающий этап

После выполненных настроек необходимо запустить сборку пересоздания стенда (RecreateNamespace), которая была создана для вашего неймспейса. Должен подняться стенд.

Запуск сервисов

Рекомендуемые значения ресурсов для запуска сервиса:

Проверить настройки в Deployment сервиса в разделе resources/limits. Рекомендуемые лимиты для сервисов Q.BPM:

          resources:
            limits:
              cpu: '2'
              memory: 2Gi

Параметры пула выделения памяти:

JAVA_XMS: 1g
JAVA_XMX: 2g

• JAVA_XMS - начальный пул выделения памяти
• JAVA_XMX - максимальный пул выделения памяти

Сколько выделено памяти, будет видно при запуске сервиса. Если не настроить параметры JAVA_XMS и JAVA_XMX, по умолчанию их значения следующие:

JAVA_XMS: 64m
JAVA_XMX: 512m

Сервис перезапускается с ошибкой Killed в логах:

• Решение: Поднять лимиты в деплойменте сервиса

Сервис перезапускается с ошибкой Java heap space в логах:

• Решение: Проверить настройки JAVA_XMS и JAVA_XMX согласно описанию выше

Статус ImagePullBackOff у пода:

Failed to pull image "registry-new.diasoft.ru/dvt/development/dev/qbpmdesigner:24010101": rpc error: code = NotFound desc = failed to pull and unpack image "registry-new.diasoft.ru/dvt/development/dev/qbpmdesigner:24010101": failed to resolve reference "registry-new.diasoft.ru/dvt/development/dev/qbpmdesigner:24010101": registry-new.diasoft.ru/dvt/development/dev/qbpmdesigner:24010101: not found

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

JPA_DIALECT

Failed to initialize JPA EntityManagerFactory: Unable to load class [jsonb-node]

Решение: Неправильно задано значение параметра JPA_DIALECT

Лицензия:

Error creating bean with name 'LStart': Invocation of init method failed; nested exception is java.lang.Exception: Signature is invalid

Решение: Неправильно задан параметр LPATH. Проверить значение параметра LPATH. Также данная ошибка может возникать, если файл лицензии неправильной структуры

Error creating bean with name 'LStart': Invocation of init method failed; nested exception is java.lang.Exception: Expired

Решение: Истек срок лицензии. Лицензию необходимо обновить.

Error creating bean with name 'LStart': Invocation of init method failed; nested exception is java.lang.Exception: Error reading file

Решение: Раздел license.xml на стенде пустой либо имеент некорректное содержание. Необходимо проверить его содержимое на стенде.

При невыполненной проливке БД или некорректной проливке в интерфейсе будет возникать ошибка:

ResultSet; SQL [n/a]; nested exception is org.hibernate.exception.SQLGrammarException: could not extract ResultSet

Решение: Проверить лог проливки database. При необходимости выполнить проливку заново. Успешно выполненной проливкой является наличие сообщения: The DB-manager worked SUCCESSFULLY

Q.BPM Player не запускается

The deployment contains definitions with same key '<key value>' (id attribute), this is not allowed

Решение: Открыть репозиторий с bpm-плеером. Проверить процессы в каталоге src/main/resources на наличие повторяющихся ключей. Убрать повторение. Пересобрать bpm-плеер.

Сервис не может создать топики:

Failed to create topics. error: Creating topics with default partitions/replication factor are only supported in CreateTopicRequest version 4+. The following topics need values for partitions and replicas: [qpbcd-pbc-ext-bussiness-platform-platform-type-reply]

Решение: В Config Maps сервиса добавить параметр spring.cloud.stream.kafka.binder.replication-factor: '1'

Авторизация

Failed to instantiate [javax.servlet.Filter]: Factory method 'springSecurityFilterChain' threw exception; nested exception is org.springframework.beans.factory.BeanCreationException: Error creating bean with name 'mdpAuthJwtDecoder' defined in class path resource [ru/diasoft/micro/mdp/lib/qoauth/QSecurityConfig.class]

Решение: обновить версию mdpauth