Version: 2024.1.0

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

Данное руководство администратора содержит описание настройки и разворачивания продукта «Дистрибутивы и лицензии», а также особенности администрирования и эксплуатации ИС.

План развертывания

Инструкция по развертыванию (установке) и обновлению ИС. Перечень возможных аварийных ситуаций и действия администратора в аварийной ситуации, план отката. Описание инсталляционных карт, необходимых для развёртывания ПО, БД и других элементов инфраструктуры.

Список сервисов

Сервис	Назначение	Образ (без версии)	Требуется ли файловая система и точки монтирования
ppbd-gateway	Маршрутизация трафика	ppdl/ppbd-gateway	нет
ppdl-back	Backend cервис репозиториев	ppdl/ppdl-back	/nexus-data
ppdl-fe	Front сервиса репозиториев	ppdl/ppdl-fe	нет
ppdl-fe-aggregator	Дополнительный UI для агрегации нескольких инсталяций в рамках одного канального приложения

Настройки

Ниже приведено описание настроек каждого сервиса через переменные окружения docker контейнеров.

ppbd-gateway

Переменные окружения для настройки сервиса

Переменная	Описание	Рекомендуемое значение (для конфигурации по умолчанию)
APPLICATION_AUTHENTICATION_SERVICE_URL	URL до сервиса аутентификации	http://common-gateway.ppch.svc.cluster.local:8000
APPLICATION_ROUTES_NEXUS_INNER_PREFIX	Путь сервиса репозиториев, должен соответствовать префиксу URL, заданному данной подсистеме в коллекции шлюзов канального приложения	/app/ppdl/api/
APPLICATION_ROUTES_NEXUS_OUTER_HOST	Доменное имя канального приложения
APPLICATION_ROUTES_NEXUS_OUTER_PORT	Порт канального приложения	443
APPLICATION_ROUTES_NEXUS_OUTER_PROTO	Протокол канального приложения (http/https)	https
APPLICATION_ROUTES_NEXUS_URL	URL до сервиса репозиториев	http://ppdl-back:80
SERVER_PORT	Порт данного сервиса	80
SERVER_SSL_ENABLED	Флаг включения https	false
SERVER_SSL_KEYSTORE	Путь к хранилищу ключей
SERVER_SSL_KEYSTORETYPE	Тип хранилища ключей (PKCS12 / JKS)	PKCS12
SERVER_SSL_KEYSTOREPASSWORD	Пароль от хранилища
SERVER_SSL_KEYALIAS	Название ключа в хранилище

Рекомендуемые лимиты ресурсов

Ресурс	Значение
CPU	500m
RAM	500Mi

Настройка SSL

Для настройки SSL необходимо

Добавить файл хранилища в контейнер.
Установить переменные окружения

SERVER_SSL_ENABLED=true
SERVER_SSL_KEYSTORE=<путь к файлу хранилища ключей>
SERVER_SSL_KEYSTOREPASSWORD=<пароль от хранилища>
SERVER_SSL_KEYALIAS=<название ключа в хранилище>

ppdl-back

Переменные окружения для настройки сервиса

Переменная	Описание	Рекомендуемое значение (для конфигурации по умолчанию)
NEXUS_CONTEXT	Путь к приложению. Должен соответствовать шаблону app//api	app/ppdl/api
SSL_ENABLED	Флаг включения https	false
SSL_KEYSTORE	Путь к хранилищу сертификатов (формат хранилища JKS)
SSL_KEYSTORE_PASSWORD	Пароль от хранилища сертификатов и ключей
LOGGING_CONFIG	Тип логирования. Если не указал - используется обычный plain text	json
JETTY_THREAD_POOL_MAX_SIZE	Размер пула потоков для обработки http запросов	600

Нередактируемые значения

Настройка	Значение
Порт сервиса в контейнере (http)	8081
Порт сервиса в контейнере (https)	8443

Рекомендуемые лимиты ресурсов

Ресурс	Значение
CPU	500m
RAM	4096Mi

После развертывания сервиса ppdl-back необходимо выполнить первоначальную настройку.

Для настройки необходимо запустить скрипт инициализации init-script.sh Параметры скрипта

Параметр	Описание	Значение по умолчанию
nexus_url	URL к установленному сервису. Данный URL используется этим скриптом для доступа к сервису.	http://host.docker.internal:8081
max_tries	Максимальное количество попыток подключения	200
admin_username	Имя пользователя учетки nexus с правами администратора, с помощью которой этот скрипт выполняет настройку	admin
default_admin_password	Пароль администратора до запуска этого скрипта	admin123
admin_password	Пароль администратора, устанавливаемый этим скриптом	123
anonymous_enabled	Разрешен ли доступ пользователям к ppdl-back без авторизации	false
anonymous_user	Имя неавторизованного пользователя, права которого действуют при доступе к ppdl-back без авторизации	anonymous
anonymous_realm	Realm неавторизованного пользователя	NexusAuthorizingRealm
auth_header	Заголовок авторизации, в котором api-gateway передает имя пользователя, должно быть идентичным значению, заданным в конфигурации api-gateway	X_AUTH_USER
auth_capability_comment	Комментарий к nexus capability, создаваемой по auth_header	Sfera proxy header
ldap_username	Имя пользователя LDAP, используемый ppdl-back для аутентификации пользователей
ldap_password	Пароль LDAP
ldap_host	Host LDAP
ldap_port	Порт LDAP	389
ldap_protocol	Протокол LDAP (LDAP/LDAPS)	LDAP
ldap_searchbase	LDAP query DN для поиска пользователей, например, dc=example,dc=com
tech_username	Имя пользователя технической учетки. Выполняется поиск пользователя в LDAP и задается роль этому пользователю в nexus.
tech_user_role	Роль nexus, которая выдается пользователю технической учетки данным скриптом	nx-admin
ldap_use_trust_store	Флаг использования доверенного хранилища для ldap	false

Настройка SSL

Для настройки SSL необходимо установить переменные окружения

SSL_ENABLED=true
SSL_KEYSTORE=<Путь к файлу хранилища>
SSL_KEYSTORE_PASSWORD=<пароль от хранилища>

Описание структуры монтируемых данных

Название папки	Назначение
blobs	Локальное хранилище блобов
cache	Выгружаемый на диск кэш приложения
db	База данных
elasticsearch	Данные поискового движка
etc	Переопределяемые пользователем настройки
keystores	Хранилища сертификатов добавляемых пользователями

ppdl-fe

Переменные окружения для настройки сервиса

Переменная	Описание	Рекомендуемое значение (для конфигурации по умолчанию)
ENABLE_LICENSE_MODULE	Флаг отключения модуля лицензий По умолчанию установлен в `true`	`true`
STANDALONE_MODE	Флаг запуска в режиме standalone (без канала) По умолчанию не используется, устанавливается STANDALONE_MODE=true
GATEWAY_URL	Используется только в standalone режиме для указания api gateway сервиса. Пример: http://ppbd-gateway:8080
SSL_ENABLED	Флаг включения https Подробнее в секции по настройке ssl	`false`
SSL_KEY_FILE	Путь к файлу приватного ключа
SSL_KEY_FILE_PASSWORD	Пароль от приватного ключа
SSL_CERT_FILE	Путь к файлу сертификата
SSL_TRUSTED_CERT_FILE	Путь к файлу доверенного сертификата (нужен только в standalone режиме, и при настройке GATEWAY_URL на сервис с самоподписным сертификатом

Нередактируемые значения

Настройка	Значение
Порт сервиса в контейнере	8000

Рекомендуемые лимиты ресурсов

Ресурс	Значение
CPU	500m
RAM	500Mi

Настройка SSL

Для настройки SSL необходимо установить переменные окружения

SSL_ENABLED=true
SSL_KEY_FILE=<Путь к файлу приватного ключа>
SSL_KEY_FILE_PASSWORD=<Пароль от приватного ключа>
SSL_CERT_FILE=<Путь к файлу сертификата

ppdl-fe-aggregator

Сервис устанавливается только в случае разделения "Дистрибутивов и Лицензий" на несколько экземпляров, для увеличения производительности, и является по сути разводящей страницей между этими инсталяциями.

Переменные окружения для настройки сервиса

Переменная	Описание	Рекомендуемое значение (для конфигурации по умолчанию)
SSL_ENABLED	Флаг включения https Подробнее в секции по настройке ssl	`false`
SSL_KEY_FILE	Путь к файлу приватного ключа
SSL_KEY_FILE_PASSWORD	Пароль от приватного ключа
SSL_CERT_FILE	Путь к файлу сертификата

Нередактируемые значения

Настройка	Значение
Порт сервиса в контейнере	8000

Конфигурация вложенных приложений

Для настройки нужно сформировать файл config.json и примонтировать его в контейнер в папку /usr/share/nginx/html.

Пример файла конфигурации

{
  "apps": [
    {"path": "/ppdl-maven", "title": "Дистрибутивы maven"},
    {"path": "/ppdl-npm", "title": "Дистрибутивы npm"}
  ]
}

В данном примере в агрегаторе будет 2 плитки с приложениями дистрибутивов.

Это значит что в канальном приложении должны быть загеристрированны 3 приложения.

/ppdl-aggregator - ведущее на данный сервис

/ppdl-maven - путь к инстансу "Дистрибутивов" отвечающему за работу с maven

/ppdl-npm - путь к инстансу "Дистрибутивов" отвечающему за работу с npm

(пути могут быть другим и указан для примера)

Рекомендуемые лимиты ресурсов

Ресурс	Значение
CPU	500m
RAM	500Mi

Настройка SSL

Для настройки SSL необходимо установить переменные окружения

SSL_ENABLED=true
SSL_KEY_FILE=<Путь к файлу приватного ключа>
SSL_KEY_FILE_PASSWORD=<Пароль от приватного ключа>
SSL_CERT_FILE=<Путь к файлу сертификата

Прокси для docker репозиториев

Для работы docker репозиториев нужно настроить проксирующие сервисы, так как docker протокол не поддерживает сложные составные урлы.

Пример конфигурации для ingress-а сферы. Может быть заменен на обычный proxy nginx

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
 name: ppdl-docker
 namespace: ppch
 annotations:
  cert-manager.io/cluster-issuer: sfera
  nginx.ingress.kubernetes.io/proxy-body-size: 10g
  nginx.ingress.kubernetes.io/rewrite-target: /app/ppdl/api/v2/$1
spec:
 ingressClassName: nginx
 rules:
  - host: docker-ppdl.sfera.org
   http:
    paths:
     - path: /v2/(.*)
      pathType: Prefix
      backend:
       service:
        name: sfera-gateway-service
        port:
         number: 8000

Добавление в канальное приложение

Добавление ДиЛ в канальное приложение

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

Добавление ДиЛ в канальное приложение

kubectl -n ppch get pods \
  -l app.kubernetes.io/instance=ppch-tenant-management-service \
  -o name | xargs -I{} kubectl -n ppch exec {} -- curl -X POST --location \
  'http://localhost:7079/actuator/productmanager/add-product-config' \
--header 'Content-Type: application/json' \
--data '{
    "code": "ppdl",
    "path": "/ppdl",
    "title": "Дистрибутивы и Лицензии",
    "description": "Храните",
    "groupTitle": "Инженерные инструменты",
    "icon": "app/ppdl/logo.svg",
    "favorite": false,
    "enabled": true,
    "isPublic": false,
    "internal": false,
    "options": {
        "type": "module",
        "remoteEntry": "app/ppdl/remoteEntry.js",
        "exposedModule": "microFrontend"
    },
    "apiRoute": {
        "url": "http://ppbd-gateway:8000",
        "filters": [
            "StripPrefix=3"
        ],
        "predicates": [
            "/app/ppdl/api/**"
        ]
    },
    "mfRoute": {
        "url": "http://ppdl-fe:8000",
        "filters": [
            "StripPrefix=2"
        ],
        "predicates": [
            "/app/ppdl/**"
        ]
    },
    "widgetApiRoute": null,
    "widgetMfRoute": null,
    "fileRoute": null
}'

В случае если планируется использовать несколько инсталяций ДиЛ то каждый из них нужно зарегистрировать с уникальными значениями полей code, path, options.remoteEntry, apiRoute.url, apiRoute.predicates

Скрытие лишних плиток ДиЛ в интерфейсе канального приложения (опциональный шаг)

При использовании группировки плиток на UI можно скрыть лишние плитки ДиЛ через настройку базы данных tenant сервиса Канального приложения.

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

UPDATE app_config SET enabled = false WHERE url in ('/ppdl-maven', '/ppdl-npm')

где /ppdl, /ppdl-2 - это пути по которым зарегистрированы конкретные экземпляры ДиЛ из предыдущего шага.

Добавление группировки фронтовых плиток в канальное приложение (опциональный шаг)

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

Добавление ДиЛ в канальное приложение

kubectl -n ppch get pods \
  -l app.kubernetes.io/instance=ppch-tenant-management-service \
  -o name | xargs -I{} kubectl -n ppch exec {} -- curl -X POST --location \
  'http://localhost:7079/actuator/productmanager/add-product-config' \
--header 'Content-Type: application/json' \
--data '{
    "code": "ppdl-aggregator",
    "path": "/ppdl-aggregator",
    "title": "Дистрибутивы и Лицензии",
    "description": "Храните",
    "groupTitle": "Инженерные инструменты",
    "icon": "app/ppdl-aggregator/logo.svg",
    "favorite": false,
    "enabled": true,
    "isPublic": false,
    "internal": false,
    "options": {
        "type": "module",
        "remoteEntry": "app/ppdl-aggregator/remoteEntry.js",
        "exposedModule": "microFrontend"
    },
    "apiRoute": null,
    "mfRoute": {
        "url": "http://ppdl-fe-aggregator:8000",
        "filters": [
            "StripPrefix=2"
        ],
        "predicates": [
            "/app/ppdl-aggregator/**"
        ]
    },
    "widgetApiRoute": null,
    "widgetMfRoute": null,
    "fileRoute": null
}'

Обновление кешей канального приложения

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

Обновление кешей канального приложения

kubectl -n ppch get pods \
  -l app.kubernetes.io/instance=ppch-tenant-management-service \ 
  -o name | xargs -I{} kubectl \
  -n ppch exec {} -- curl -s http://localhost:7079/actuator/refresh -X POST

kubectl -n ppch get pods \
  -l app.kubernetes.io/instance=ppch-gateway-mf-service \
  -o name | xargs -I{} kubectl \
  -n ppch exec {} -- curl -s http://localhost:7079/actuator/refresh -X POST

kubectl -n ppch get pods \
  -l app.kubernetes.io/instance=ppch-gateway-service \
  -o name | xargs -I{} kubectl \
  -n ppch exec {} -- curl -s http://localhost:7079/actuator/refresh -X POST

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

Проверка работоспособности сервисов на контуре DEV

Проверка	Описание	Ожидаемый ответ
Проверка работоспособности	Браузером открыть страницу: http://sfera.apps.ocp.t1.demo.ru/app/ppdb/ (URL может быть другим, в зависимости от сделанных настроек при установке)	Откроется стартовая страница приложения

Планово-предупредительные мероприятия

Процедуры проверки работоспособности системы и локализации неработающих компонентов представлены в таблице ниже

№	Содержание мероприятия	Периодичность	Ответственный
1	Мониторинг работоспособности различных компонентов системы	Различная	Прикладной администратор
2	Локализации неработающих компонентов системы	Различная	Прикладной администратор
3	Проверить наличие сертификатов	Перед запуском пилотного/целевого решения, перед релизом	Прикладной администратор
4	Проверить в консоли администратора k8s, что все поды запущены в требуемом количестве	После запуска пилотного/целевого решения, после вывода релиза	Прикладной администратор
5	Проверить логи запуска микросервисов, сообщения с типом ERROR должны отсутствовать	После запуска пилотного/целевого решения,после вывода релиза	Прикладной администратор
6	Выполнить в роутах микросервисов healthcheck `http://hostname:8080/orders/ping`	После запуска пилотного/целевого решения,после вывода релиза	Прикладной администратор
7	Проверка работоспособности компонента Grafana	Раз в месяц	Прикладной администратор
8	Проверка работоспособности микросервисов	Ежедневно	Прикладной администратор
9	Проверка статуса системы. Статус запуска серверов	Ежедневно	Прикладной администратор
10	Проверка статуса системы. Мониторинг использования серверов	Раз в месяц	Прикладной администратор
11	Мониторинг использования серверов. Анализ статистики по логам	Раз в месяц	Прикладной администратор
12	Проверка статуса системы. Мониторинг выполнения задач планировщика	Ежедневно	Прикладной администратор

Для просмотра записанных логов в k8s необходимо залогиниться в консоли k8s с ролью администратора. Для просмотра логов нужно перейти на вкладку «Pods» в разделе «Workloads», выбрать «Project», зайти в нужный под и перейти на вкладку «Logs».

Будет открыто окно с выводом текущих логов микросервиса в режиме реального времени. В окне отображается последняя тысяча строк лога микросервиса. Это окно можно развернуть на весь экран, нажав на кнопку «Expand». Также можно скачать эти логи, нажав кнопку «Download».

Аварийное восстановление

Критерии аварийного события

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

Массовые обращения пользователей ИС в службу поддержки.
Обращение Бизнес Администратора, Технолога или Аналитика ИС в службу поддержки.
Выявление События в результате Планово-предупредительных мероприятий со стороны службы поддержки.
Обращение со стороны сотрудников Мониторинга, администраторов СУБД и серверов приложений.
Отрицательный результат проверки работоспособности сервисов при вводе системы в эксплуатацию

Перечень возможных аварийных событий:

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

Порядок действий при выявлении аварийного события

Общий порядок действий при возникновении аварийного события:

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

Потребители информации: Бизнес-заказчик, Технолог и Аналитик ИС.
Канал направления информации: e-mail и sms/звонок (дополнительно: канал информирования на усмотрении службы поддержки).
Содержание информации: данные о зарегистрированном инциденте (описание События, периметр События, возможные причины, плановые сроки устранения, возможные последствия).

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

Прикладные Администраторы.
Администраторы серверов Приложений (в части сопровождения и эксплуатации систем поддержки бизнеса).

Ролевая модель доступа

Внутренняя система привилегий

Типы привилегий

Тип	Сегмент	Допустимые действия	Описание
Приложение	nexus:{name}:{actions}	create,read,update,delete	Привилегии данного типа управляют доступом к специфичным функциям продукта в интерфейсе администратора, например nexus:blobstores:create,read разрешает доступ на создание и просмотр блоб-хранилищ
Администратор репозитория	nexus:repository-admin:{format}:{repository}:{actions}	browse,read,edit,add,delete	Привилегии данного типа дают право на управление конфигурацией приложения.например nexus:repository-admin:nuget:nuget.org-proxy:browse,read означает разрешить доступ на просмотр к nuget репозиторию с наименованием nuget.org-proxy
Селекторы	nexus:repository-content-selector:{selector}:{format}:{repository}:{actions}	browse,read,edit,add,delete	Привилегии данного типа реализуют детальный контроль над доступом к контенту в репозитории с помощью селектора контента.например nexus:repository-content-selector::maven2::read означает разрешить доступ к любому контенту соответствующему селектору с именем maven2
Просмотр репозитория	nexus:repository-view:{format}:{repository}:{actions}	browse,read,edit,add,delete	Привилегии данного типа дают дотсуп на контент репозитоия, без права настройки самого репозитория.например nexus:repository-view:maven2:central:browse,read разрешает доступ на просмотр содержимого репозитория фонмата maven2 с наименованием central
Скрипты	nexus:script:{script name}:{actions}	browse,read,edit,add,delete,run	Привилегии для работы с groovy скриптами

Действия

Действия — это функции, допускающие явное поведение, которое привилегия может выполнять со связанной функцией.

Вы должны назначить одно или несколько действий при создании новых привилегий; при назначении нескольких действий разделяйте каждое действие запятой, но не используйте пробелы после запятых (например, "add,view,create"). Тип привилегии, к которому вы применяете любое из этих действий, будет выполнять подразумеваемое поведение действия. Рассмотрим, как ведет себя каждое действие при применении к типу привилегий:

Действие	Описание
`add`	Это действие дает права на добавление содержимого репозитория или скриптов.
`browse`	Это действие позволяет привилегии просматривать содержимое связанных репозиториев. В отличие от чтения, типы привилегий с просмотром могут только просматривать и администрировать содержимое репозитория из пользовательского интерфейса.
`create`	Это действие позволяет привилегиям создавать применимые конфигурации в менеджере репозитория. Поскольку для просмотра конфигурации требуется разрешение на чтение, это действие связано с большинством существующих прав на создание.
`delete`	Это действие дает права на удаление конфигураций менеджера репозитория, содержимого репозитория и скриптов. Действие чтения обычно связано с действиями удаления, поэтому субъект может просмотреть эти конфигурации, чтобы удалить их.
`edit`	Это действие дает права на изменение скриптов, содержимого репозитория и настроек.
`read`	Это действие дает права на просмотр различных списков конфигурации и сценариев. Без чтения любое связанное с ним действие даст право просматривать эти списки, но не их содержимое. Действие чтения также позволяет привилегиям использовать инструменты, которые могут просматривать содержимое из командной строки.
`update`	Это действие дает права на обновление конфигураций менеджера репозитория. Большинство существующих привилегий с обновлением включают действия чтения. Таким образом, при создании настраиваемых привилегий с обновлением субъекту следует подумать о добавлении чтения к привилегии, чтобы просматривать обновления конфигурации менеджера репозитория.
`*`	Это действие является обобщением, дающим возможность группировать все действия вместе. Использование * применяет все другие применимые действия к привилегии.

Система привилегий при интеграции с ДИР

Настройка ДиР

Для настройки ДиР нужно обратиться к руководству администратора этой системы.

Со стороны ДиЛ мы предоставляем конфигурацию для импорта привилегий (файл objectTypes.json), его нужно импортировать в ДиР в типы объектов, в подсистему созданную для ДиЛ.

Для удобства мы так же предоставляем дополнительную (опциональную) конфигурацию для импорта ролей (файл roles.json). Роли можно импортировать из данного файла, либо создать их самостоятельно с нуля.

Настройка ДиЛ

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

Включить capability "Sfera Authentication Configuration"
1. Указать Auth service URL - адрес сервиса аутентификации сферы в вашей инсталяции (пример https://sfera.org/api/auth )
2. Указать Profile service URL - адрес сервиса с информацией о профилях (пример https://sfera.org/api/profile )
3. Указать ремя жизни кэша в секундах
Включить capability "Sfera Authtorization Confuguration"
1. Указать Dir service URL - адрес сервиса Доступы и Роли (пример https://sfera.org/app/ppam )
2. Указать код системы Дистрибутивы и Лицензии используемый в Доступах и Ролях (пример PPBD)
3. Указать логин и пароль технической учетной записи через которую будут делаться запросы на получение данных из ДиР
4. Указать Repository template - шаблон для применения привилегий на множество репозиториев по маске. Шаблон представляет из себя регулярное выражение (regex), в который встроен шаблон с обязательной константой ${SPACE}. Пример
```
.*${SPACE}.*
```
Перейти в раздел "Realms", включить реалм "Sfera Authentication Realm" и отключить реалм "Rut Auth Realm"
Запустить синхронизацию справочных данных из ДиЛ вызвав endpoint
```
POST /service/rest/v1/dir/update
```
данным действием мы запустим механизм для копирования названий репозиториев и скриптов в справочники ДиР, для того чтобы эти значения можно было использовать при назначении соответствующих привилегий. Последующее дополнение значений в справочниках будет происходить автоматически по мере создания новых репозиториев в ДиЛ

Описание типов привилегий в ДиР

Тип привилегии	Список действий	Описание	Необходимые атрибуты (справочники)
Полный доступ (all_privileges)	all	Полный доступ системе ДиЛ включая права на администрирование
Приложение (application)	create - создание read - чтение update - обновление delete - удаление	Привилегии данного типа управляют доступом к специфичным функциям продукта в интерфейсе администратора	domain - домен в приложении
Работа с артефактами репозиториев (repository-view)	add - добавление read - чтение edit - редактирование delete - удаление browse - просмотр	Доступ к артефактам по названиям репозиториев. Дает доступ выборочно только к тем репозиториям которые явно перечислены при назначении пользователям системы.	repository_name - название репозитория
Работа с артефактами проектных областей (repository-view-template)	add - добавление read - чтение edit - редактирование delete - удаление browse - просмотр	Доступ к артефактам по названию проектных областей. Дает доступ ко всем репозиториям по шаблону в котором встречается название проектной области.	space - проектная область
Управление репозиториями (repository_admin)	add - добавление read - чтение edit - редактирование delete - удаление browse - просмотр	Доступ к администрированию репозиториев. Дает доступ выборочно только к тем репозиториям которые явно перечислены при назначении пользователям системы.	repository_name - название репозитория
Управление репозиториями проектных областей (repository_admin_template)	add - добавление read - чтение edit - редактирование delete - удаление browse - просмотр	Доступ к администрированию репозиториев по названию проектных областей. Дает доступ ко всем репозиториям по шаблону в котором встречается название проектной области.	space - проектная область
repository_content_selector	add - добавление read - чтение edit - редактирование delete - удаление browse - просмотр	Доступ к артефактам через селекторы контента	repository_name - название репозитория content_selector_name - название селектора
Управление скриптами (script)	add - добавление read - чтение edit - редактирование delete - удаление browse - просмотр run - запуск	Работа со скриптами	script_name - наименование скрипта

Описание типов объектов справочников

Тип объекта	Описание	Возможные значения
domain	Домен приложения	Заполняется из ДиЛ при первоначальном импорте
repository_name	Название репозитория	Заполняется из ДиЛ при первоначальном импорте и в процессе работы
space	Проектная область	Заполняет вручную при заведении новой проектной области
content_selector_name	Название селектора	Заполняется из ДиЛ при первоначальном импорте и в процессе работы
script_name	Название скрипта	Заполняется из ДиЛ при первоначальном импорте и в процессе работы

Файлы для импорта в ДиР

objectTypes.json
{
  "objectTypes": [
    {
      "code": "application",
      "title": "Приложение",
      "actions": [
        {
          "code": "create",
          "title": "Создание"
        },
        {
          "code": "read",
          "title": "Чтение"
        },
        {
          "code": "delete",
          "title": "Удаление"
        },
        {
          "code": "update",
          "title": "Обновление"
        }
      ],
      "attributes": [
        {
          "code": "domain"
        }
      ]
    },
    {
      "code": "content_selector_name",
      "title": "Название селектора",
      "actions": [],
      "attributes": []
    },
    {
      "code": "all_privileges",
      "title": "Полный доступ",
      "actions": [
        {
          "code": "all",
          "title": "Все"
        }
      ],
      "attributes": []
    },
    {
      "code": "repository_name",
      "title": "Название репозитория",
      "actions": [],
      "attributes": []
    },
    {
      "code": "repository_view",
      "title": "Работа с артефактами",
      "actions": [
        {
          "code": "add",
          "title": "Добавление"
        },
        {
          "code": "read",
          "title": "Чтение"
        },
        {
          "code": "edit",
          "title": "Редактирование"
        },
        {
          "code": "delete",
          "title": "Удаление"
        },
        {
          "code": "browse",
          "title": "Просмотр"
        }
      ],
      "attributes": [
        {
          "code": "repository_name"
        }
      ]
    },
    {
      "code": "space",
      "title": "Проектная область",
      "actions": [],
      "attributes": []
    },
    {
      "code": "repository_view_template",
      "title": "Работа с артефактами (Проектная область)",
      "actions": [
        {
          "code": "add",
          "title": "Добавление"
        },
        {
          "code": "read",
          "title": "Чтение"
        },
        {
          "code": "edit",
          "title": "Редактирование"
        },
        {
          "code": "delete",
          "title": "Удаление"
        },
        {
          "code": "browse",
          "title": "Просмотр"
        }
      ],
      "attributes": [
        {
          "code": "space"
        }
      ]
    },
    {
      "code": "repository_admin",
      "title": "Управление репозиториями",
      "actions": [
        {
          "code": "add",
          "title": "Добавление"
        },
        {
          "code": "read",
          "title": "Чтение"
        },
        {
          "code": "edit",
          "title": "Редактирование"
        },
        {
          "code": "delete",
          "title": "Удаление"
        },
        {
          "code": "browse",
          "title": "Просмотр"
        }
      ],
      "attributes": [
        {
          "code": "repository_name"
        }
      ]
    },
    {
      "code": "repository_admin_template",
      "title": "Управление репозиториями (Проектная область)",
      "actions": [
        {
          "code": "add",
          "title": "Добавление"
        },
        {
          "code": "read",
          "title": "Чтение"
        },
        {
          "code": "edit",
          "title": "Редактирование"
        },
        {
          "code": "delete",
          "title": "Удаление"
        },
        {
          "code": "browse",
          "title": "Просмотр"
        }
      ],
      "attributes": [
        {
          "code": "space"
        }
      ]
    },
    {
      "code": "repository_content_selector",
      "title": "Работа с артефактами через селекторы",
      "actions": [
        {
          "code": "add",
          "title": "Добавление"
        },
        {
          "code": "read",
          "title": "Чтение"
        },
        {
          "code": "edit",
          "title": "Редактирование"
        },
        {
          "code": "delete",
          "title": "Удаление"
        },
        {
          "code": "browse",
          "title": "Просмотр"
        }
      ],
      "attributes": [
        {
          "code": "repository_name"
        },
        {
          "code": "content_selector_name"
        }
      ]
    },
    {
      "code": "script_name",
      "title": "Название скрипта",
      "actions": [],
      "attributes": []
    },
    {
      "code": "script",
      "title": "Скрипты",
      "actions": [
        {
          "code": "add",
          "title": "Добавление"
        },
        {
          "code": "read",
          "title": "Чтение"
        },
        {
          "code": "edit",
          "title": "Редактирование"
        },
        {
          "code": "delete",
          "title": "Удаление"
        },
        {
          "code": "browse",
          "title": "Просмотр"
        },
        {
          "code": "run",
          "title": "Запуск"
        }
      ],
      "attributes": [
        {
          "code": "script_name"
        }
      ]
    },
    {
      "code": "domain",
      "title": "Домен",
      "actions": [],
      "attributes": []
    }
  ]
}

roles.json
{
  "roles": [
    {
      "code": "PPBD_DEVELOPER",
      "title": "ДиЛ. Разрабочик",
      "objectTypeActions": [
        {
          "code": "read",
          "objectTypeCode": "repository_view"
        },
        {
          "code": "edit",
          "objectTypeCode": "repository_view"
        },
        {
          "code": "delete",
          "objectTypeCode": "repository_view"
        },
        {
          "code": "browse",
          "objectTypeCode": "repository_view"
        },
        {
          "code": "read",
          "objectTypeCode": "repository_view_template"
        },
        {
          "code": "edit",
          "objectTypeCode": "repository_view_template"
        },
        {
          "code": "delete",
          "objectTypeCode": "repository_view_template"
        },
        {
          "code": "browse",
          "objectTypeCode": "repository_view_template"
        },
        {
          "code": "read",
          "objectTypeCode": "repository_content_selector"
        },
        {
          "code": "edit",
          "objectTypeCode": "repository_content_selector"
        },
        {
          "code": "delete",
          "objectTypeCode": "repository_content_selector"
        },
        {
          "code": "browse",
          "objectTypeCode": "repository_content_selector"
        }
      ],
      "objectTypes": []
    },
    {
      "code": "PPBD_VIEWER",
      "title": "ДиЛ. Просмотр данных",
      "objectTypeActions": [
        {
          "code": "read",
          "objectTypeCode": "repository_view"
        },
        {
          "code": "browse",
          "objectTypeCode": "repository_view"
        },
        {
          "code": "read",
          "objectTypeCode": "repository_view_template"
        },
        {
          "code": "browse",
          "objectTypeCode": "repository_view_template"
        },
        {
          "code": "read",
          "objectTypeCode": "repository_content_selector"
        },
        {
          "code": "browse",
          "objectTypeCode": "repository_content_selector"
        },
        {
          "code": "read",
          "objectTypeCode": "script"
        },
        {
          "code": "browse",
          "objectTypeCode": "script"
        }
      ],
      "objectTypes": []
    },
    {
      "code": "PPBD_ADMIN",
      "title": "ДиЛ. Администратор",
      "objectTypeActions": [
        {
          "code": "all",
          "objectTypeCode": "all_privileges"
        }
      ],
      "objectTypes": []
    }
  ]
}

Журналирование

Реализуется стандартными средствами для java приложений на основе библиотеки logback

Сервис ppdl-back

Включение логирования в json формате осуществляется через переменные окружения

LOGGING_CONFIG=json

Формат json логов

{
  "product": "ppdl",   // название продукта
  "serviceName": "ppdl-backend", // название сервиса
  "serviceId": "83f1ee4a-dbbd-4e99-b0df-ae140890d10c", // идентификатор инстанса сервиса
  "serviceVersion": "v1.0.123", // версия сервиса
  "localTime": "1686047487000",  // таймштамп в милисекундах

  "level": "INFO",  // уровень лога
  "text": "Текст сообщения", // логируемое сообщение
  "loggerName": "ru.t1.example.LoggMe", // имя логгера
  "threadName": "thread-1",  // поток

  "stack": "" // опциональный стектрейс при ошибках  виде строки
} 

В случае если стандартный формат логов не устраивает, то можно добавить собственную конфигурацию:

Настройки формата логирования осуществляются через файл конфигурации logback расположенного в папке /nexus-data/etc/logback/logback.xml

Создать папку ${NEXUS_DATA}/etc/logback-${название конфигурации}, где название конфигурации - произвольная строка. например custom
Добавить в папку 2 файла logback.xml и logback-access.xml
Добавить в файлы требуемые настройки логирования. Особенности настройки можно найти в руководстве по настройке логирования logback.
Включить новый формат логирования через переменную окружения
```
 LOGGING_CONFIG=${название конфигурации} ## в нашем примере custom
```
Примеры файлов
- logback.xml
- logback-access.xml

Сервис ppbd-gateway

Включение логирования в json формате осуществляется через переменную окружения

LOGGING_CONFIG=classpath:logback-json.xml

Включение логирования в режиме простого текста осуществляется через переменную окружения

LOGGING_CONFIG=classpath:logback-plain.xml

Формат json логов

{
  "product": "ppbd",   // название продукта
  "serviceName": "ppbd-gateway", // название сервиса
  "serviceId": "83f1ee4a-dbbd-4e99-b0df-ae140890d10c", // идентификатор инстанса сервиса
  "serviceVersion": "2023.4.0.6", // версия сервиса
  "localTime": 1699886345193,  // таймштамп в милисекундах

  "level": "INFO",  // уровень лога
  "text": "Текст сообщения", // логируемое сообщение
  "loggerName": "ru.sfera.ppdl.gateway.Authenticator", // имя логгера
  "threadName": "thread-1",  // поток

  "stack": "" // опциональный стектрейс при ошибках  виде строки
}

Настройка отправки логов в socket

docker-compose.yaml
version: '3'

networks:
  ppdl:
    driver: bridge


services:
  fluent-bit:
    image: docker-infra.sfera.org/docker-group/fluent/fluent-bit
    container_name: fluent-bit
    hostname: fluent-bit
    ports:
      - "9999:9999"
    volumes:
      - ./fluent-bit.conf:/fluent-bit/etc/fluent-bit.conf
      - ./fluent-bit-parsers.conf:/fluent-bit/parsers/parsers.conf
  ppdl-gateway:
    image: docker-infra.sfera.org/docker-group/ppdl/ppbd-gateway:${GW_VERSION}
    container_name: ppdl-gateway
    networks:
      - ppdl
    environment:
      - APPLICATION_AUTHENTICATION_SERVICE_URL=/
      - APPLICATION_ROUTES_NEXUS_INNER_PREFIX=/api/
      - APPLICATION_ROUTES_NEXUS_OUTER_HOST=localhost
      - APPLICATION_ROUTES_NEXUS_OUTER_PORT=8080
      - APPLICATION_ROUTES_NEXUS_OUTER_PROTO=http
      - APPLICATION_ROUTES_NEXUS_URL=http://ppdl-back:8081
      - SPRING_CONFIG_LOCATION=/app/application.yml
      - SERVER_PORT=8080
      - LOGGING_LEVEL_ROOT=INFO
      - LOGGING_CONFIG=classpath:logback-json.xml
    restart: always
    volumes:
      - ./gateway-properties.yml:/app/application.yml
    logging:
      driver: fluentd
      options:
        fluentd-address: localhost:9999
    deploy:
      resources:
        limits:
          cpus: '2'
          memory: 1G
        reservations:
          cpus: '1'
          memory: 500M
    depends_on:
      - fluent-bit
  ppdl-back:
    image: docker-infra.sfera.org/docker-group/ppdl/ppdl-back:${BE_VERSION}
    container_name: ppdl-back
    networks:
      - ppdl
    environment:
      - NEXUS_CONTEXT=api
      - LOGGING_CONFIG=json
    volumes:
      - ./nexus-data:/nexus-data
    restart: always
    deploy:
      resources:
        limits:
          cpus: '4'
          memory: 4G
        reservations:
          cpus: '4'
          memory: 2G
    logging:
      driver: fluentd
      options:
        fluentd-address: localhost:9999
    depends_on:
      - fluent-bit
  ppdl-front:
    image: docker-infra.sfera.org/docker-group/ppdl/ppdl-fe:${FE_VERSION}
    container_name: ppdl-front
    environment:
      - ENABLE_LICENSE_MODULE=false
      - STANDALONE_MODE=true
      - GATEWAY_URL=http://ppdl-gateway:8080
    networks:
      - ppdl
    restart: always
    ports:
      - "8080:8000"
    deploy:
      resources:
        limits:
          cpus: '0.2'
          memory: 500M
        reservations:
          cpus: '0.1'
          memory: 200M
    logging:
      driver: fluentd
      options:
        fluentd-address: localhost:9999
    depends_on:
      - fluent-bit

fluent-bit.conf
[SERVICE]
    Parsers_File /fluent-bit/parsers/parsers.conf

[INPUT]
    name forward
    listen 0.0.0.0
    port 9999

[FILTER]
    name record_modifier
    Match  *
    Whitelist_key log

[FILTER]
    name parser
    Match  *
    Key_Name log
    Parser json

[FILTER]
    Name modify
    Match  *
    Add risCode 1

[OUTPUT]
    name stdout
    match *

fluent-bit-parser.conf
[PARSER]
    Name json
    Format json
    Time_Key time
    Time_Format %Y-%m-%dT%H:%M:%S.%L

Мониторинг

Сервис ppdl-back предоставляет метрики в prometheus формате. Для получения метрик нужно обратиться по урлу http://host:port/service/metrics/prometheus

Получение метрик требует наличия прав на сбор метрик nx-metrics-all.

Сервис ppbd-gateway предоставляет метрики в prometheus формате по урлу http://host:port/actuator/prometheus

Трейсинг

Трейсинг работает только на уровне ppbd-gateway сервиса.

Для работы трейсинга нужен любой сборщик трейсов поддерживающий open telemetry. Например jaeger c otel коллектором.

Включается трейсинг через переменную окружения сервиса ppbd-gateway

SPRING_SLEUTH_ENABLED=true
JAEGER_OTLP_ENDPOINT=<URL до коллектора> // например http://jaeger-collector.jaeger:4317/

Аудит

Общие положения

Аудит реализуется через библиотеку аудита интегрированную в сервисы.

Аудируются все вызовы rest api вызовы.

По требованиям безопасности аудит должен выполняться синхронно с гарантиями доставки событий. Это сильно влияет на производительность системы, так как на каждый rest api вызов делается еще 2 внешних вызова для отравки аудита, и система дожидается ответа об успешной обработке аудит событий.

Схема работы аудита

Есть реализация двух аудит адаптеров

Адаптер для PostgreSQL хранилища (можно использовать для тестовых контуров, где нет большой нагрузки)
Адаптер для Kafka хранилища

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

Адаптер принимает на вход конфигурацию событий аудита /config/audit-config.yml

metadata:
  - event-code: 'API_CALL'
    event-type: 'Вызов метода контроллера'
    business-object-expr: "object"
    business-object: 'Пользователь'
    business-operation: 'Вызов метода контроллера'
    audit-event-start:
      title: "'Вызов метода контроллера'"
      message-template: "'Вызов метода контроллера'"
    audit-event-success:
      title: "'Вызов метода контроллера'"
      message-template: "'Вызов метода контроллера выполнен успешно'"
    audit-event-failure:
      title: "'Вызов метода контроллера'"
      message-template: "'Вызов метода контроллера выполнен с ошибкой ' + error.message"

Переменные окружения

  SFERA_LOCAL_AUDIT_ADAPTER_METADATA="file:/config/audit-config.yml"
  SFERA_AUDIT_ADAPTER_INFO_SYSTEMS_0_KEY="ppdl-back"
  SFERA_AUDIT_ADAPTER_INFO_SYSTEMS_0_ID="2068"
  SFERA_AUDIT_ADAPTER_INFO_SYSTEMS_0_CODE="PPDL"

Настройка

Для работы аудита нужно включить в capabilities "Audit" плагина

Enable audit sfera = true
Audit service URL = \<URL до аудит адаптера>
Application ID = ppdl-back

План развертывания​

Список сервисов​

Настройки​

ppbd-gateway​

Настройка SSL​

ppdl-back​

Настройка SSL​

Описание структуры монтируемых данных​

ppdl-fe​

Настройка SSL​

ppdl-fe-aggregator​

Настройка SSL​

Прокси для docker репозиториев​

Добавление в канальное приложение​

Добавление ДиЛ в канальное приложение​

Скрытие лишних плиток ДиЛ в интерфейсе канального приложения (опциональный шаг)​

Добавление группировки фронтовых плиток в канальное приложение (опциональный шаг)​

Обновление кешей канального приложения​

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

Планово-предупредительные мероприятия​

Аварийное восстановление​

Критерии аварийного события​

Порядок действий при выявлении аварийного события​

Ролевая модель доступа​

Внутренняя система привилегий​

Система привилегий при интеграции с ДИР​

Настройка ДиР​

Настройка ДиЛ​

Описание типов привилегий в ДиР​

Описание типов объектов справочников​

Файлы для импорта в ДиР​

Журналирование​

Сервис ppdl-back​

Сервис ppbd-gateway​

Настройка отправки логов в socket​

Мониторинг​

Трейсинг​

Аудит​

Общие положения​

Настройка​

План развертывания

Список сервисов

Настройки

ppbd-gateway

Настройка SSL

ppdl-back

Настройка SSL

Описание структуры монтируемых данных

ppdl-fe

Настройка SSL

ppdl-fe-aggregator

Настройка SSL

Прокси для docker репозиториев

Добавление в канальное приложение

Добавление ДиЛ в канальное приложение

Скрытие лишних плиток ДиЛ в интерфейсе канального приложения (опциональный шаг)

Добавление группировки фронтовых плиток в канальное приложение (опциональный шаг)

Обновление кешей канального приложения

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

Планово-предупредительные мероприятия

Аварийное восстановление

Критерии аварийного события

Порядок действий при выявлении аварийного события

Ролевая модель доступа

Внутренняя система привилегий

Система привилегий при интеграции с ДИР

Настройка ДиР

Настройка ДиЛ

Описание типов привилегий в ДиР

Описание типов объектов справочников

Файлы для импорта в ДиР

Журналирование

Сервис ppdl-back

Сервис ppbd-gateway

Настройка отправки логов в socket

Мониторинг

Трейсинг

Аудит

Общие положения

Настройка