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

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

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

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

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

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

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

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

Настройка способа получения конфигурации выполняется в файле <src/main/resources/bootstrap.yml>.

Если используется Spring Cloud, необходимо его включить и указать адрес сервера конфигурации:

spring.cloud.config.uri: http://localhost:8080
spring.cloud.config.enabled: true

Если используется локальная конфигурация, Spring Cloud необходимо отключить:

spring.cloud.config.enabled: false

В зависимости от текущего профиля настройки могут быть переопределены в файлах конфигурации профиля <src/main/resources/application-{profile}.yml>.

Файл application.yml должен содержать следующие конфигурационные блоки:

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

• блок oidc — настройки аутентификации и авторизации на backend-сервисе;

• блок logging — настройки требуемого уровня логирования в системе;

• блок spring — настройки spring-приложения;

• блок сallback — настройки, связанные с реализацией Callback;

• блок api — настройки пользовательского API;

• блок events — настройки отправки событий бизнес-мониторинга;

• блок audit — настройки аудита;

• блок tracing — настройки отправки сообщений в систему tracing (трейсинга);

• блок index — настройки интеграции с сервисом индексирования;

• блок transport — настройки асинхронного взаимодействия с внешними системами.

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

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

Настройка режима работы#

Предусмотрено 2 режима:

• без поддержки мультитенантности;

• с поддержкой мультитенантности – один потребитель в одной инсталляции (multiinstance);

Режим работы определяется переменной multitenancy.mode в файле application.yml:

При валидации конфигурационного файла должны быть соблюдены следующие правила:

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

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

Для работы компонента TaskList (UTSK) продукта Platform V Flow (BPM) необходимо настроить подключение к БД. Для настройки подключения к БД необходимо указать соответствующие опции в файле application.yml. Работа с БД осуществляется через pg_bouncer. Для этого в URL для подключения должен быть указан не порт БД, а порт pg_bouncer.

В данный момент используется две БД – master и StandIn.

Список рекомендуемых БД представлен в Руководстве по установке, «Системное программное обеспечение».

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

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

spring.liquibase.enabled: false

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

• username — имя пользователя БД (пароль хранится в разделе secrets).

• driver — имя драйвера;

• jdbc-url — путь к БД, в качестве порта должен быть указан порт pg_bouncer;

  • prepareThreshold=0 в конце строки отключает механизм prepared statement, так как этот механизм временно не работает с pg_bouncer.

• maximumPoolSize — максимальный размер pool соединений;

• jpa — блок настройки взаимодействия с БД.

spring:
  datasource:
    username: htm-test
    driver: org.postgresql.Driver
    jdbc-url: jdbc:postgresql://vm.esrt.cloud.ru:5433/bdtl?prepareThreshold=0
    maximumPoolSize: 60
  jpa:
    show-sql: false
    hibernate.dll-auto: validate
    properties.hibernate.dialect: org.hibernate.dialect.PostgreSQL95Dialect
  liquibase:
    enabled: true

Настройки механизма очистки БД#

Настройка механизма очистки удаленных данных из БД осуществляется через файл application.yml, блок cleanup.

Доступные настройки:

• enabled — включение/выключение механизма очистки данных;

• frequency — настройка периодичности запуска механизма очистки данных из БД в cronlike формате;

• lifetime — настройка (в секундах) срока восстановления удаленных данных (время нахождения в статусе DELETED, во время которого запись можно восстановить).

cleanup:
  enabled: true
  frequency: 0 0 */2 ? * *
  lifetime: 86400

Настройка Spring actuator#

Блок Management содержит настройки spring actuator, необходимые для получения метрик.

Для настройки доступа к данным Spring actuator необходимо указать порт, на котором будут доступны данные: server.port 8086, а также список endpoint, по которым необходимо получать данные.

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

• rn – соответствует resourceName потребителя.

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

Настройка Callback#

Настройка Callback производится через файл application.yml, блок callback.

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

• start — полный URL внешней системы для подтверждения старта задачи;

• abort — полный URL внешней системы для подтверждения прерывания назначения задачи;

• complete — полный URL внешней системы для подтверждения выполнения задачи;

• assign — полный URL внешней системы для подтверждения назначения задачи;

• discharge — полный URL внешней системы для подтверждения снятия назначения задачи.

Настройка тайм-аутов и повторных вызовов в случае неуспешного результата исполнения callback производится в блоке timeout. Значение -1 не вносит изменений в значение по-умолчанию netty.

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

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

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

• timeout.write — время ожидания записи сокета в мс;

• timeout.retry.maxAttempts — количество повторных вызовов в случае неуспешного ответа или тайм-аута;

• timeout.retry.minBackOffMills — начальный интервал повтора в случае неуспешного ответа или тайм-аута, в мс. Последующий интервал = (начальный интервал) * 2 ^ (номер повтора).

callback:
    start: http://...
    abort: http://...
    complete: http://...
    assign: http://...
    discharge: http://...
    timeout: 
        connection-request: 1
        connect: 1
        read: 1
        write: 1
        retry:
            maxAttempts: 3
            minBackOffMills: 300

Настройка трейсинга (tracing)#

Настройка отправки Span (специализированный термин, обозначающий событие трейсинга) в систему трейсинга (tracing). Span отправляются в формате OpenZipkin при входящих и исходящих вызовах UTSK.

Настройка работы трейсинга (tracing) осуществляется через файл application.yml, блок tracing.

Доступные настройки:

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

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

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

• max-queue-size — максимальный размер очереди;

• batch-size — максимальный размер отправляемой партии (количество span отправляемых в одном запросе);

• delay-ms — задержка отправки очереди span;

• timeout:

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

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

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

tracing:
  enabled: false
  url: http://localhost:9321/spans 
  service-name: htm-app
  max-queue-size: 1000
  batch-size: 5
  delay-ms: 10000
  timeout:
    connection-request: 5000
    connect: 10000
    read: 30000

Схема сообщения Span:

Настройка бизнес-мониторинга#

Публикуемые события:

• Создание задачи;

• Назначение задачи на исполнителя менеджером;

• Взятие задачи исполнителем в работу;

• Снятие задачи с исполнителя;

• Старт задачи;

• Завершение задачи;

• Прерывание задачи;

• Изменение параметров задачи.

Настройки отправки событий:

• enabled — отвечает за включение отправки событий;

• bam-project-id: urn:sbrfsystems:99-tasklist — параметр bamProjectId (по требованию Platform V Monitor);

• format — формат сообщения kogito|synapse;

• kafka:

  • bootstrap-servers — адрес Kafka брокера;

  • client-id — префикс клиента Kafka. Строка идентификатора, передаваемая на сервер при выполнении запросов:

    • properties.reconnect.backoff.ms — базовое время ожидания перед попыткой повторного подключения к узлу;

  • template.default-topic: EventsTaskList — топик по умолчанию;

  • producer:

    • retries — количество попыток повторной отправки в случае ошибки;

    • key-serializer: org.apache.kafka.common.serialization.StringSerializer — класс сериализатора для ключа;

    • value-serializer: org.apache.kafka.common.serialization.StringSerializer — класс сериализатора для значения.

events:
  enabled: true  
  bam-project-id: urn:sbrfsystems:99-tasklist
  format: kogito
  kafka:
    bootstrap-servers: localhost:9092
    client-id: @project.name@
    properties.reconnect.backoff.ms: 10000
    template.default-topic: EventsTaskList
    producer:
      retries: 0
      key-serializer: org.apache.kafka.common.serialization.StringSerializer
      value-serializer: org.apache.kafka.common.serialization.StringSerializer

Схема события Kogito

Пример:

{
  "bamProjectId": "urn:sbrfsystems:99-tasklist",          
  "id": "df180b56-2e81-4aa4-a16e-72c7c9194a15",          
  "kogitoProcessId": "4d899471-19dd-485d-b7f4-b31318d",  
  "kogitoProcessinstanceId": "63c297cb-f5ac-4e20-8254-02f37bd72b80",  
  "specversion": "1.1",                               
  "time": "2021-04-28T15:58:37.811541+03:00",            
  "type": "UserTaskInstanceEvent",                       
  "source": "http://localhost:8080/userTask",            
  "kogitoUserTaskinstanceId": "4d899471-19dd-485d-b7f4-b313185d430d", 
  "kogitoUserTaskinstanceState": "COMPLETED",                         
  "data": {
    "processInstanceId": "4d899471-19dd-485d-b7f4-b313185d430d",      
    "id": "4d899471-19dd-485d-b7f4-b313185d430d",                     
    "taskListId": "4d8fe443-19dd-485d-b7f4-72c7c9194a15",             
    "taskName": "Apply for visa",   
    "taskDescription": null,       
    "taskPriority": "1",            
    "referenceName": "Task",        
    "state": "COMPLETED",           
    "created": "1645163501",       
    "assigned": "1645163501",     
    "started": "1645163501",     
    "completed": "1645163501",    
    "aborted": "1645163501",        
    "abortReason": "value",          
    "potentialUsers": [
    ],      
    "potentialGroups": [
        "TestGroup"
    ],      
    "excludedUsers": [
        "TestActor"
    ],     
    "adminUsers": [
    ],      
    "adminGroups": [
        "TestAdmin"
    ],      
    "inputs": {
        "parameter1": "value",
        "parameter2": "value"      
    },      
    "outputs": {
        "parameter1": "value",
        "parameter2": "value" 
    }      
  }
}

Схема события Synapse

header

body

Тело сообщения генерируется аналогично схеме сообщения для Kogito, представленной выше.

Настройка marketplaces для плеера форм#

Настройка marketplaces для плеера форм осуществляется через файл application.yml, блок app:

• marketplaces.name — наименование marketplace.

• marketplaces.baseUrl — url marketplace.

app:
  marketplaces:
    - name: marketplace/list
      baseUrl: http://marketplace.space/marketplace/
    - name: marketplacesandbox/list
      baseUrl: http://marketplace.space/marketplacesandbox/

Настройка ограничения количества задач#

Для массовых операций#

Настройка ограничения максимального количества задач для массовых операций осуществляется через файл application.yml, блок app:

• massOperationsLimit — максимальное количество задач, передаваемое API массовой операции. По умолчанию 20, максимум 100. В случае если значение 0, то массовые операции перестанут работать (в ответе АПИ массовых операций будет возвращаться сообщение, что они отключены).

app:
    massOperationsLimit: 20

Для назначения#

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

Настройка ограничения количества задач для назначения осуществляется через файл application.yml, блок app:

• linked.limit — глобальное ограничение количества задач для назначения при отсутствии явно заданного значения. Ограничение распространяется на общее количество задач, включая исходную, по которой происходит поиск связанных. По умолчанию 30.

• linked.max — максимально допустимое количество задач для назначения. По умолчанию 100.

app:
    linked:
        limit: 30
        max: 100

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

Настройка ограничения количества задач при выборках осуществляется через файл application.yml, блок app:

• dictionaryLimit — максимальное количество уникальных значений для атрибута с типом DICTIONARY, возвращаемое в ответе запроса получения списка атрибутов. По умолчанию 100.

app:
    dictionaryLimit: 100

Настройка ограничения payload в запросах к API#

Настройка ограничения максимального размера payload в запросах к API UTSK осуществляется через файл application.yml, блок app:

• payloadLimit — максимальный размер payload в запросах к API UTSK в байтах. По умолчанию null (функционал отключен). При указании значений null, 0 или пустого значения функционал лимитирования будет отключен.

app:
    payloadLimit: 3000

Настройка индексирования#

Настройка индексирования пользовательских задач в Elasticsearch (ES) осуществляется через файл application.yml, блок index.

Доступные настройки:

• enabled — включение/выключение сервиса индексирования;

• host — список адресов сервисов индексирования;

• resource — имя индекса. При отсутствии значения будет использоваться имя "tasks";

• connectTimeout — тайм-аут подключения к сервису индексирования;

• socketTimeout — тайм-аут сокета подключения;

• chunkSize — количество записей, отправляемых одним пакетом для индексирования в ES. По умолчанию: 500;

• username — логин пользователя для авторизации в ES;

index:
  enabled: false
  host: http://localhost:9200/, http://localhost:9222/
  resource: tasks
  connectTimeout: 3000
  socketTimeout: 3000
  chunkSize-size: 500
  username: test-user

При включенном сервисе индексирования:

1. Включен механизм синхронизации задач с ES. Механизм синхронизации задач с сервисом индексирования выполняется при запуске приложения htm-app или вручную через spring actuator.

   Ограничение: До завершения выполнения механизма синхронизации задач запросы получения задач могут работать некорректно (возвращать пустые или неполные списки задач).

   Доступные операции для ручного запуска через spring actuator:

   1. synchronize – синхронизацию задач с сервисом индексирования. При выполнении измененные, но не проиндексированные задачи, будут проиндексированы в ES.

   2. rebuild – перестроение индексов задач. При выполнении все задачи будут переиндексированы в ES (у всех задач будет очищена дата индексирования и ошибка индексирования, после чего запущен механизм индексирования задач).

   3. reset – сброс ошибок индексирования. При выполнении задачи с ошибкой индексирования будут переиндексированы в ES.

2. Выполняется индексация задач в ES при создании/изменении/удалении задач;

3. Поисковые запросы по задачам (получение задач менеджера, получение задач исполнителя, поиск связанных задач, поиск доступных задач однопоточного исполнителя выполняются в ES);

   Ограничение: При выполнении поисковых запросов по задачам (через API UTSK) количество задач в ответе будет ограничено значением по умолчанию – 10000 (конфигурация ES).

4. Поиск количественных значений по задачам для статистики менеджера и исполнителя выполняется в ES.

Настройка размера сообщения WebClient#

Настройка размера буфера сообщений WebClint осуществляется через файл application.yml в блоке spring.

• codec.max-in-memory-size — максимальный размер сообщений WebClient. По умолчанию 512 KB.

spring:
  codec:
    max-in-memory-size: 512KB

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

Настройка асинхронного взаимодействия с внешними системами#

Публикуемые события:

• Завершение задачи

• Прерывание задачи

Принимаемые события:

• Создание задачи

• Прерывание задачи

Настройки включения асинхронного взаимодействия:

• enabled — включение или выключение асинхронного взаимодействия;

• format — формат событий (cloud-events-spec);

• userTaskInboundEventsTopic — топик входящих событий по пользовательской задачи;

• userTaskOutboundEventsTopic — топик исходящих событий по пользовательской задачи;

• acceptedModuleIds — фильтрация сообщений по header 'moduleId', работает при наличии этого параметра;

• kafka:

  • bootstrap-servers — адрес Kafka брокера;

  • client-id — префикс клиента Kafka. Строка идентификатора, передаваемая на сервер при выполнении запросов:

  • properties.reconnect.backoff.ms — базовое время ожидания перед попыткой повторного подключения к узлу;

  • template.default-topic: EventsTaskList — топик по умолчанию;

  • producer:

    • retries — количество попыток повторной отправки в случае ошибки;

    • key-serializer: org.apache.kafka.common.serialization.StringSerializer — класс сериализатора для ключа;

    • value-serializer: org.apache.kafka.common.serialization.StringSerializer — класс сериализатора для значения.

  • consumer:

    • groupId — id группы потребителя;

    • auto-offset-reset — стратегия установки смещения курсора для чтения сообщения из topic;

    • properties

      • max.poll.interval.ms — максимальная задержка между запросами к брокеру;

      • session.timeout.ms — ttl сессии.

transport:
  enabled: true
  format: cloud-events-spec
  userTaskInboundEventsTopic: toHtmUserTaskEvents
  userTaskOutboundEventsTopic: fromHtmUserTaskEvents
  acceptedModuleIds:
    - bpmx
  kafka:
    bootstrap-servers: localhost:9092
    client-id: @project.name@
    properties.reconnect.backoff.ms: 10000
    template.default-topic: EventsTaskList
    producer:
      retries: 0
      key-serializer: org.apache.kafka.common.serialization.StringSerializer
      value-serializer: org.apache.kafka.common.serialization.StringSerializer
    consumer:
      groupId: htm_main
      auto-offset-reset: earliest
      properties:
        'max.poll.interval.ms': 35000
        'session.timeout.ms': 30000

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

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

Настройка интеграции с компонентом Прикладной журнал (APLJ) Platform V Backend (опционально)#

Для обеспечения возможности проведения технологических работ с БД без недоступности системы используется механизм функционального StandIn. Данный механизм предполагает наличие двух контуров БД (master и StandIn) и один набор отсеков (pods) htm-app и htm-app-replica, подключенных к обоим контурам БД. Master контур используется как основной, StandIn контур – как резервный. Компонент UTSK осуществляет логическую репликацию данных между контурами БД, используя внешний сервис – компонент Прикладной журнал (APLJ) продукта Platform V Backend (#BD), далее – ПЖ.

Для работы приложения UTSK в режиме StandIn необходимо настроить параметры подключения к БД для обоих экземпляров (htm-app и htm-app-replica) следующим образом:

standin:
  enabled: true
  serializerType: json_gson
  cloud:
    client:
      stub: false
      zoneId: test
      mmt-proxy-url: localhost
      kafka.bootstrapServers: localhost
      kafka.producerConfig.max.request.size=5242880
  datasource:
    username: htm-admin
    driver: org.postgresql.Driver
    jdbc-url: jdbc:postgresql://localhost:6544/bdpprb?prepareThreshold=0
  jpa:
    show-sql: false
    hibernate.dll-auto: validate
    properties.hibernate.dialect: org.hibernate.dialect.PostgreSQL95Dialect
  liquibase:
    enabled: true

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

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

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

Для настройки отправки сообщений в компонент AUDT необходимо в файле application.yml в блоке audit определить следующие переменные:

• enabled — включение/выключение Аудита;

• multitenant — режим работы Аудита: false – обычный, true – мультитенантный;

• proxyUri — адрес сервиса платформенного Аудита;

• proxyVersion — версия протокола взаимодействия;

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

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

• retryTimeout — время ожидания перед повторной отправкой сообщения (мс). По умолчанию 60000;

• maxQueueSize — максимальный размер сообщений в очереди на отправку в Аудит. По умолчанию 100;

• timeout:

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

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

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

Пример:

audit:
  enabled: true
  multitenant: false
  proxyUri: http://localhost:9321/audit 
  proxyVersion: v1
  nodeId: utsk.htm-app
  retryTimeout: 60000
  maxQueueSize: 100
  timeout:
    connection-request: 5000
    connect: 10000
    read: 30000

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

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

Настройка компонента LOGA осуществляется в sidecar-контейнере сервиса журналирования.

• serviceHostname — настройки хоста sidecar сервиса LOGA;

• image — образ sidecar сервиса LOGA;

• cluster — имя кластера для поля в сервисе LOGA;

• zoneId — идентификатор зоны для отправки событий;

• events — адрес отправки событий LOGA.

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

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

Для режима multiinstance файл logback-spring.xml содержит дополнительные атрибуты:

• RN – идентификатор ресурса (тип строка) – содержится в конфигурации экземпляра;

• CN из сертификата потребителя (тип строка) – содержится в конфигурации экземпляра;

• traceId – идентификатор трейса, с которым связана лог-запись (тип строка), получение из заголовка x-b3-traceid.

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

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

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

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

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

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

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

Компонент UTSK может быть развернут как с возможностью интеграции с сервисом OTT, так и без нее.

Подключение OTT производится в виде sidecar-контейнера dc Ingress. Конфигурация хранится в отельной ConfigMap.

Настройки, необходимые для подключения, описаны в документации на (OTTS) One-Time Password (OTP)/OTT Platform V Backend.

Для получения сертификатов приложения, публичного ключа OTT Service и их подключения:

• при помощи keytool сгенерируйте key-store c ключами с помощью алгоритма SHA256withECDSA, длина ключа 256 бит;

• отправьте файл с расширением .pem администратору OTT в заявке на генерацию сертификата для модуля. В заявке явно указать, что сертификат должен быть сгенерирован из приложенного запроса по инструкции. Администратор OTT подписывает/генерирует ключи, высылает их обратно;

• импортируйте полученные от администратора OTT ключи в key-store в формате p12.

• Создайте два секрета:

  • с сертификатами;

  • с паролями к ключам.

Для работы OTT-sidecar необходимо наличие в дистрибутиве ConfigMap с настройками сервиса. Создание ConfigMap выполняется на этапе установки сервиса.

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

Подключение Istio осуществляется в соответствии с документацией на него.

Выпуск и установка сертификатов Istio для Ingress/Egress

Выпустите и установите сертификаты Istio Ingress/Egress:

• istio-egressgateway-ca-certs;

• istio-egressgateway-certs;

• istio-ingressgateway-ca-certs;

• istio-ingressgateway-certs.

После чего будет создан набор необходимых артефактов, в том числе секреты с сертификатами cert, ca-cert.

Созданные секреты содержат, в том числе, наименования файлов tls.crt, tls.key, ca-chain.cert.pem.

В секретах istio-ingressgateway-ca-certs и istio-egressgateway-ca-certs должен присутствовать один файл ca-chain.cert.pem со всей цепочкой сертификатов. Если в секрете указаны два отдельных сертификата, то вызовы через Ingress по HTTP(S) не будут работать.

Возможен вариант, когда в секретах в файле ca-chain.cert.pem содержится вся цепочка сертификатов (т.е. добавлено содержимое из ca.pem), но сам файл ca.pem не удален. В этом случае все будет работать корректно.

Осуществление межсервисной аутентификации при входящем и исходящем запросе#

Запрос от клиента попадает на входящий граничный прокси (IGEG) Synapse Service Mesh.

После прохождения handshake устанавливается защищенное mTLS соединение (серверные сертификаты монтируются к граничному прокси (IGEG) Synapse Service Mesh). Если включена поддержка фильтров валидации входящих сообщений, происходит проверка совпадения информации из клиентского сертификата с содержимым фильтра валидации.

При совпадении – запрос проходит дальше, при несовпадении клиенту возвращается ошибка 403. Далее sidecar ОТТ проверяет валидность входящего запроса по информации из заголовков ОТТ.

Также возможна проверка разрешения через механизм ACL со стороны сервера ОТТ. Если все вышеозначенные требования удовлетворены – запрос маршрутизируется на pod приложения.

При исходящем запросе происходит маршрутизация на исходящий граничный прокси (IGEG) Synapse Service Mesh. Через sidecar ОТТ запрос подписывается ОТТ-токеном, после чего данные заголовки добавляются к запросу.

Также граничный прокси (IGEG) Synapse Service Mesh добавляет к запросу необходимые сертификаты для установки защищенного соединения по mTLS.

Настройки, связанные с использованием сервисов OTT, Synapse Service Mesh, описаны в документации на данные сервисы.

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

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

События регистрируются в формате json.

Настройки интеграции с компонентом описаны в разделе «Интеграция с компонентом Журналирование (LOGA) Platform V Monitor (OPM)». Журнал регистрации событий располагается в АРМ сервиса Журналирование (LOGA) продукта Platform V Monitor (OPM). Адрес сервиса Журналирования необходимо уточнять у администраторов сред.

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

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

  • Расширенная информация об этапах выполнения всех запросов к приложению. Включает в себя логи уровня ERROR, WARN, INFO, DEBUG.

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

  • Информация об этапах выполнения всех запросов к приложению (от информации о пользователе и параметрах запроса до результатов выполнения запроса). Включает в себя лог-записи уровня ERROR, WARN, INFO.

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

  • Информация о включении сервисов, блокировки связанные с индексами. Включает в себя логи уровня ERROR, WARN.

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

  • Информация об ошибках возникающих при некорректных запросах к приложению (например: ошибки отсутствия callback). Включает в себя лог-записи уровня ERROR.

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

  • Информация о всех ошибках приложения (например: bad request, ошибка отправки span в сервис трейсинга (tracing), ошибка оправки события в аудит, ошибки Kafka и т.д.).

Изменение корневого уровня логирования доступно через настройку logging.level.root. По умолчанию включен уровень INFO. Для изменения уровня логирования конкретной группы лог-записей, добавьте соответствующую строчку в параметры конфигурации.

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

• app — верхний уровень логов приложения;

• system — группа системных лог-записей jdk;

• server — лог-записи Catalina, Coyote, Tomcat;

• spring — лог-записи Spring Framework;

• hibernate — лог-записи Hibernate;

• sql — лог-записи SQL;

• elasticsearch — лог-записи elasticsearch;

• template — группа лог-записей по функциональности работы с шаблонами задач;

• task — группа лог-записей по функциональности работы с задачами;

• group — группа лог-записей по функциональности динамических групп;

• user — группа лог-записей по функциональности получения пользователей;

• stats — группа лог-записей по функциональности статистики;

• audit — лог-записи по функциональности отправки событий в компонент AUDT;

• monitoring — логи по функционалу отправки событий в Kafka бизнес-мониторинга;

• transport — лог-записи по функциональности асинхронного взаимодействия с внешними системами;

• tracing — логи по функционалу отправки span в Сервис трассировки (TRAS) ;

• metrics — лог-записи по функциональности метрик;

• index — лог-записи по функциональности индексации задач;

• filter — лог-записи по фильтрации API запросов.

Пример:

logging:
    level: 
      root: INFO
      task: DEBUG
      group: ERROR

Пример перечня событий:

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

Приложение UTSK публикует метрики в формате prometheus.

Список метрик доступен администраторам среды контейниризации по URL приложения taskList – http://{tasklist-url}/actuator/metrics (доступны в формате prometheus ../actuator/prometheus).

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

Метрики, публикуемые приложением UTSK, можно разделить на следующие типы:

• Метрика готовности приложения UTSK;

• Метрики JVM (Java Virtual Machine);

• Метрики состояния БД;

• Метрики состояния сервиса индексирования;

• Метрики состояния Kafka клиента;

• Метрики состояния интеграции с внешними сервисами;

• Метрики состояния компонентов SpringBoot-приложения;

• Метрики HTTP клиента;

• Бизнес метрики приложения UTSK;

• Метрики событий журналирования.

Метрика готовности приложения UTSK#

application_ready_time_seconds — Время, необходимое (мс) для того, чтобы приложение было готово к обслуживанию запросов.

Метрики JVM (Java Virtual Machine)#

Включают основные метрики JVM (утилизация CPU, загруженность диска, используемая память и др.):

• jvm_memory_committed_bytes — объем памяти в байтах, выделенный для использования JVM;

• jvm_memory_max_bytes — максимальный объем памяти в байтах, который можно использовать для управления памятью;

• jvm_memory_used_bytes — объем памяти, используемой JVM;

• jvm_gc_pause_seconds_count — пауза работы сборщика мусора (garbage collector) в секундах;

• jvm_gc_pause_seconds_sum — суммарное время пауз работы сборщика мусора (garbage collector) в секундах;

• jvm_gc_pause_seconds_max — максимальное время сборщика мусора (garbage collector) в паузе в секундах;

• jvm_threads_live_threads — текущее количество активных потоков, включая демон-потоки;

• jvm_threads_daemon_threads — текущее количество активных демон-потоков;

• jvm_threads_peak_threads — максимальное количество активных потоков, зарегистрированное с момента запуска JVM или с момента последнего сброса данного значения;

• process_files_open_files — количество открытых файловых дескрипторов;

• process_files_max_files — максимальное количество файловых дескрипторов;

• process_start_time_seconds — время начала процесса, в секундах, по системе UNIX Epoch;

• process_cpu_usage — процент использования процессора за недавнее время процессом JVM;

• system_cpu_count — количество процессоров, доступных для виртуальной машины Java;

• system_cpu_usage — «Недавнее использование CPU» системы, в которой запущено приложение;

• disk_free_bytes — количество байтов, свободных на диске;

• disk_total_bytes — общее количество байт на диске.

Метрики состояния БД#

Включают основные метрики состояния БД HikariCP (утилизации дискового пространства базой данных и др.):

• hikaricp_connections_usage_seconds_max — максимальное время использования соединения;

• hikaricp_connections_usage_seconds_sum — суммарное время использования соединения;

• hikaricp_connections_usage_seconds_count — время использования соединения;

• hikaricp_connections_acquire_seconds_max — максимальное время установления соединения;

• hikaricp_connections_acquire_seconds_sum — суммарное время установления соединения;

• hikaricp_connections_acquire_seconds_count — время установления соединения;

• hikaricp_connections_creation_seconds_max — максимальное время создания соединения;

• hikaricp_connections_creation_seconds_sum — суммарное время создания соединения;

• hikaricp_connections_creation_seconds_count — время создания соединения;

• hikaricp_connections — общее количество соединений;

• hikaricp_connections_max — максимальное количество подключений;

• hikaricp_connections_min — минимальное количество соединений;

• hikaricp_connections_active — активные подключения;

• hikaricp_connections_pending — ожидание соединения;

• hikaricp_connections_timeout_total — общее количество тайм-аутов (время ожидания) подключения;

• hikaricp_connections_idle — неработающие соединения;

• hikaricp_connections_active — активные подключения.

Включают основные метрики jdbc (текущие активные, максимально допустимые и минимально разрешенные соединения в pool):

• jdbc_connections_max — максимальное количество активных подключений, которые могут быть выделены одновременно;

• jdbc_connections_min — минимальное количество незанятых подключений в pool;

• jdbc_connections_idle — количество установленных, но неработающих соединений;

• jdbc_connections_active — текущее количество активных подключений, выделенных из источника данных.

Метрики состояния сервиса индексирования#

• index_sync_status — метрика, отображающая статус синхронизации с сервисом индексирования: 0 – бездействует; 1 – в работе; 2 – завершена; -1 – ошибка;

• index_sync_total — общее количество проиндексированных задач;

• index_sync_successful — количество успешно индексированных задач;

• index_sync_errors — количество неудачных попыток индексирования задач;

• index_sync_deleted — количество удаленных из индекса задач.

Метрики состояния Kafka клиента#

Метрики состояния Kafka клиента бизнес-мониторинга:

• events_availability — метрика, отображающая состояние клиента: 0 – не инициализирован, 1 – доступен, -1 (минус 1) – не доступен;

• events_total — общее количество сообщений;

• events_successful_total — количество успешно отправленных сообщений;

• events_failure_total — количество неудачных попыток отправки сообщений.

Метрики состояния Kafka клиента асинхронного взаимодействия с внешними системами:

• transport_availability — метрика, отображающая состояние клиента: 0 – не инициализирован, 1 – доступен, -1 (минус 1) – не доступен;

• transport_total — общее количество сообщений;

• transport_successful_total — количество успешно отправленных сообщений;

• transport_failure_total — количество неудачных попыток отправки сообщений.

Метрики брокера Kafka:

• kafka_producer_ — группа метрик брокера Kafka (глобальные метрики запросов, метрики подключения, показатели брокера, метрики топиков).

Метрики состояния интеграции с внешними сервисами#

Метрики состояния интеграции с компонентом AUDT

• audit_availability — метрика, отображающая состояние клиента: 0 – не инициализирован, 1 – ошибка отправки, 2 – асинхронная отправка, 3 – синхронная отправка;

• audit_errors_connection_total — количество неудачных попыток подключения к серверу;

• audit_errors_service_total — количество незарегистрированных событий аудита;

• audit_total — общее количество событий;

• audit_successful_total — количество успешно отправленных событий.

Метрики состояния интеграции с системой Трейсинга (Tracing)

• tracing_availability — метрика, отображающая состояние клиента: 0 – не инициализирован, 1 – доступен, -1 (минус 1) – не доступен;

• tracing_total — количество сгенерированных span попавших в очередь;

• tracing_request_successful — количество успешных попыток отправки запросов в систему Трейсинга;

• tracing_request_failure — количество неуспешных попыток отправки запросов в систему Трейсинга;

• tracing_message_sent — количество успешно отправленных Span;

• tracing_message_dropped — количество просроченных Span – сообщения удаленные из очереди по причине переполнения буфера.

Метрики состояния компонентов SpringBoot-приложения#

• tomcat_sessions_expired_sessions_total — общее количество закончившихся по тайм-ауту подключений Tomcat;

• tomcat_sessions_created_sessions_total — общее количество созданных подключений Tomcat;

• tomcat_sessions_active_max_sessions — максимальное количество подключений Tomcat, с момента старта JVM, либо с момента последнего сброса значения данной метрики;

• tomcat_sessions_rejected_sessions_total — общее количество подключений Tomcat, которые не были приняты;

• tomcat_sessions_active_current_sessions — количество подключений Tomcat, активных на данный момент;

• tomcat_sessions_alive_max_seconds — максимальная продолжительность жизни подключения Tomcat, в секундах.

Метрики HTTP клиента#

Включают основные метрики сетевых запросов Reactor Netty:

• reactor_netty_http_client_data_sent_time_seconds_max — максимально допустимое время отправки данных во внешние сервисы;

• reactor_netty_http_client_data_sent_time_seconds_count — количество отправок данных во внешние сервисы;

• reactor_netty_http_client_data_sent_time_seconds_sum — время на отправку данных во внешние сервисы. Для получения среднего времени отправки данных, необходимо разделить значение reactor_netty_http_client_data_sent_time_seconds_sum на reactor_netty_http_client_data_sent_time_seconds_count;

• reactor_netty_http_client_data_received_bytes_max — максимально допустимый объем полученных данных в байтах;

• reactor_netty_http_client_data_received_bytes_count — количество полученных данных в байтах;

• reactor_netty_http_client_data_received_bytes_sum — объем полученных данных в байтах;

• reactor_netty_http_client_data_received_time_seconds_max — максимально допустимое время получения данных из внешних сервисов;

• reactor_netty_http_client_data_received_time_seconds_count — количество получений данных из внешних сервисов;

• reactor_netty_http_client_data_received_time_seconds_sum — время получения данных из внешних сервисов. Для получения среднего времени отправки данных, необходимо разделить значение reactor_netty_http_client_data_received_time_seconds_sum на reactor_netty_http_client_data_received_time_seconds_count;

• reactor_netty_http_client_response_time_seconds_max — максимально допустимое время обработки запроса;

• reactor_netty_http_client_response_time_seconds_count — количество обработок запроса;

• reactor_netty_http_client_response_time_seconds_sum — время обработки запроса. Для получения среднего времени обработки запроса, необходимо разделить reactor_netty_http_client_response_time_seconds_sum на reactor_netty_http_client_response_time_seconds_count;

• reactor_netty_http_client_connect_time_seconds_max — максимально допустимый объем отправленных данных в байтах;

• reactor_netty_http_client_connect_time_seconds_count — количество отправок данных;

• reactor_netty_http_client_connect_time_seconds_sum — объем отправленных данных в байтах;

• reactor_netty_http_client_data_sent_bytes_max — количество успешно обработанных соединений, которые активно используются;

• reactor_netty_http_client_data_sent_bytes_count — количество отправок данных;

• reactor_netty_http_client_data_sent_bytes_sum — объем отправленных данных в байтах;

• reactor_netty_connection_provider_active_connections — количество успешно обработанных соединений, которые активно используются;

• reactor_netty_connection_provider_max_pending_connections — максимальное количество запросов, которые будут поставлены в очередь в ожидании готового соединения;

• reactor_netty_connection_provider_total_connections — количество всех подключений, активных или неактивных;

• reactor_netty_connection_provider_idle_connections — количество незанятых соединений;

• reactor_netty_connection_provider_pending_connections — количество запросов, ожидающих установления соединения.

Метрики загрузки executor сервера API:

• executor_pool_max_threads — максимально допустимое количество потоков в pool;

• executor_pool_size — текущее количество потоков в pool;

• executor_active_threads — приблизительное количество потоков, активно выполняющих задачи;

• executor_completed_tasks_total — примерное общее количество задач, завершивших выполнение;

• executor_queued_tasks — примерное количество задач, поставленных в очередь на выполнение;

• executor_queue_remaining_tasks — количество дополнительных элементов, которые очередь может принять без блокировки.

Метрики длительности обработки запросов HTTP-сервера:

• http_server_requests_seconds_max — максимальное время обработки входящих запросов;

• http_server_requests_seconds_sum — время обработки входящих запросов. Разделив данное значение на http_server_requests_seconds_count, получим среднее время выполнения запроса;

• http_server_requests_seconds_count — количество входящих запросов.

Метрики обработки запросов HTTP-сервера так же публикуются с разбиением по типам исполняющихся запросов:

• htm_task_templates_seconds - операций с шаблонами пользовательских задач;

• htm_templates_seconds - операций с шаблонами пользовательских задач по коду и версии;

• htm_user_tasks_seconds - операций с пользовательскими задачами;

• htm_v2_tasks_seconds - операций с пользовательскими задачами API v2;

• htm_groups_seconds - операций с динамическими группами;

• htm_marketplaces_seconds - операций с маркетплейс;

• htm_appinfo_seconds - запросы получения информации о системе.

Бизнес метрики приложения UTSK#

utsk_tasks_status_total — количество операций изменений статусов задач. По метрике публикуются следующие лейблы:

• businessFamily — businessFamily в рамках которой создана задача;

• operation — тип операции (CREATE, ASSIGN, START, COMPLETE, ABORT);

• result — результат операции;

• success — флаг успешности выполнения операции.

Метрики событий журналирования#

• logback_events_total — количество событий журналирования по типам (trace, debug, info, warn, error).

Публикация метрик в режиме мультиинстанс#

В режиме «мультиинстанс» метрики отвечающие за работу приложения дополнены:

• rn – соответствует resourceName потребителя.

Предварительно потребитель должен создать подключение к компоненту MONA, используя соответствующий resourceName.

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

Общие рекомендации#

Алгоритм для диагностирования и решения проблем с внешними интеграциями:

• Проанализируйте журнал UTSK на наличие ошибок/успешных запросов.

• Проанализируйте журнал Istio Proxy в pod сервиса на наличие ошибок/успешных запросов.

• Проанализируйте журнал Egress Gateway на наличие ошибок/успешных запросов.

• Проанализируйте журнал OTT Sidecar на Egress на наличие ошибок/успешных запросов.

Проблема после изменения ограничение размера description#

Проблема:

После изменения ограничения размера параметра description на 10000 символов, в случае если у задачи в поле description хранится более 10000 символов - все операции с данной задачей (назначение, завершение, изменение, и тд.) будут возвращать ошибку.

Решение:

Для проблемных задач выполнить запрос обрезания размера description. Пример запроса:

UPDATE user_tasks
SET description = substring(description, 0, 10000)

Часто встречающиеся ошибки в лог-файлах#

Ошибка:

• Bad request exception: Невозможно обновить завершенную задачу.

• Access denied: Нельзя стартовать завершенную задачу.

Решение:

Задача находится в конечном статусе (COMPLETED, ABORTED). Через API UTSK из конечного статуса задачу перевести нельзя.