4.4. Руководство по инсталляции адаптеров¶

4.4.1. Назначение и общий функционал работы с адаптерами¶

Адаптер: Представляет собой веб-сервис доступа к данным приложения или базы данных, связанных с Системой.

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

Адаптер БД.

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

Адаптер Remedy.
Адаптер LDAP.
Адаптер полнотекстового поиска Solr.
Адаптер CMDB.

Использование адаптеров в системе лицензируется. Установка лицензии описана в Раздел 4.3 Руководства по инсталляции.

4.4.2. Установка адаптера¶

Примечание

Можно установить и настроить несколько экземпляров одного адаптера. Подробнее см. Установка и настройка нескольких экземпляров одного адаптера.

Для установки адаптера необходимо сначала установить Docker и Vault.

Подробнее об установке и настройке Docker можно посмотреть здесь: https://docs.docker.com/get-started/.

Подробнее об установке и настройке Vault см. Руководство по инсталляции сервиса системных настроек Vault.

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

docker load -i /path/to/image.tar.gz

Здесь:

/path/to/image.tar.gz: Пример пути к архиву с образом соответствующего адаптера.

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

docker login registry.igtel.ru:6443

При входе необходимо ввести логин и пароль.

После этого нужно скачать образ соответствующего адаптера:

registry.igtel.ru:6443/sgate/integration: Образ адаптера Remedy.
registry.igtel.ru:6443/sgate/integration_ldap: Образ адаптера LDAP.
registry.igtel.ru:6443/sgate/integration_db: Образ адаптера БД.
registry.igtel.ru:6443/sgate/integration-solr: Образ адаптера полнотекстового поиска (Solr).
registry.igtel.ru:6443/sgate/integration_cmdb: Образ адаптера CMDB.

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

docker pull registry.igtel.ru:6443/sgate/integration

После того как образ скачан (из архивного файла или из реестра Docker), необходимо запустить контейнер, выполнив в командной строке команду в многострочном формате (после символа

должен быть перенос строки без пробелов и других символов):

docker run -d \
--env sgate.server.host=0.0.0.0 \
--env sgate.server.port=8082 \
--env sgate.vault.url=http://devops.igtel.ru:8200 \
--env sgate.vault.token=s.xRYEe6FCAHn1DAdOAqodkz4Z \
--env sgate.vault.engine=sgate \
--env sgate.vault.version=2 \
--env sgate.vault.sources="common remedy" \
-p 8082:8082 --name sgate_integration \
registry.igtel.ru:6443/sgate/integration

Здесь:

sgate.server.host: Хост сервиса в контейнере.
sgate.server.port: Порт сервиса в контейнере. Можно выбрать любой свободный порт в Системе.
sgate.vault.url: URL сервиса Vault с конфигурацией сервиса.
sgate.vault.token: Токен для логина в Vault.
sgate.vault.engine: Название Vault engine, где хранятся настройки.
sgate.vault.version: Версия хранилища Vault.
sgate.vault.sources: Список секретов (secrets), которые будут использоваться сервисом. В примере это секреты «common» и «remedy». Cекреты в списке разделяются пробелом. Секреты подгружаются в порядке, указанном в списке. Если секреты содержат одинаковые ключи, то значение для ключа берется из последнего секрета, в котором найден ключ. Таким образом, можно выделить общие настройки и переопределять их для нужных сервисов.
8082:8082: Указываются номер порта на сервере и номер порта в контейнере (порт на сервере маппится на порт в контейнере).
name: Указывается название контейнера, для использования этого названия при обращении (вместо идентификатора). В примере это «sgate_remedy».
registry.igtel.ru:6443/sgate/integration: Образ соответствующего адаптера. В примере это образ адаптера Remedy.

4.4.3. Общая настройка всех сервисов¶

Общая настройка всех сервисов заключается в добавлении общих для всех сервисов ключей и их значений в соответствующий секрет Vault.

Описание общих ключей см. Общая настройка всех сервисов.

4.4.4. Настройка адаптеров¶

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

4.4.4.1. Настройка адаптера Remedy¶

Для адаптера Remedy необходимо добавить следующие ключи в секрет/секреты Vault:

remedy.area.secret: Токен для аутентификации в Remedy.
remedy.area.with-salt: Использовать «соль» при формировании токена.
remedy.uri: URL для подключения к Remedy.
user-info.cache.initial-capacity: Начальный размер кеша UserInfo (шт)
user-info.cache.maximum-size: Максимальный размер кеша UserInfo (шт)
user-info.cache.reload-period: Период обновления кеша

Пример заполнения ключей для адаптера Remedy:

{
"remedy.area.secret": "passwd",
"remedy.area.with-salt": "true",
"remedy.uri": "remedy://appadmin:appadmin@example.ru:5555",
"user-info.cache.initial-capacity": "32",
"user-info.cache.maximum-size": "1024",
"user-info.cache.reload-period": "PT15M"
}

4.4.4.2. Настройка адаптера LDAP¶

Для адаптера LDAP необходимо добавить следующие ключи в секрет/секреты Vault:

ldap.connections: Количество параллельных подключений.
ldap.url: URL LDAP.
ldap.customers: настройка групп пользователей (из разных тенантов) с соответствующими им настройками
expirationDate (ldap.customers): срок действия соли (unixtime в секундах)
salt (ldap.customers): соль для проверки токена
tenant (ldap.customers): название тенанта
ldap.customers.cache: настройки кеширования пользователей
ldap.customers.cache.initial-capacity: Начальный размер кеша
ldap.customers.cache.maximum-size: Максимальный размер кеша
ldap.customers.cache.reload-period: Период обновления данных в кеше
roles: маппинг ролей пользователя портала на логин/пароль пользователя ldap.

Пример заполнения ключей для адаптера LDAP:

{
"ldap.connections": "10",
"ldap.url": "ldap.example.ru:389",
"ldap.customers": [
  {
    "expirationDate": 1693515600,
    "roles": [
      {
        "role": "any",
        "username": "%ldap_user_name%",
        "password": "%ldap_password%"
      }
    ],
    "salt": "...",
    "tenant": "default"
  }
],
"ldap.customers.cache.initial-capacity": "32",
"ldap.customers.cache.maximum-size": "256",
"ldap.customers.cache.reload-period": "PT15M"
}

4.4.4.3. Настройка адаптера БД¶

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

cache.concurrency-level: Настройка параллельного доступа к кэшу для операций обновления. Подробнее: https://guava.dev/releases/18.0/api/docs/com/google/common/cache/CacheBuilder.html#concurrencyLevel(int).
cache.expire-after-write: Время жизни кэша в формате ISO 8601.
cache.initial-capacity: Начальный размер кэша.
cache.maximum-size: Максимальный размер кэша.
datasource.access-handler: Класс обработчика доступа к БД.
datasource.default-generator: Определяет способ генерации ID записи.
datasource.dialect: Класс диалекта БД.
datasource.driver: Класс драйвера БД.
datasource.jdbc-url: JDBC URL БД.
datasource.username: Логин к БД.
datasource.password: Пароль к БД.
schema.prefix: Префикс названия таблиц для генерации схемы.
schema-api.datasource.driver: Драйвер БД метаданных для управляемых схем.
schema-api.datasource.jdbc-url: URL БД метаданных для управляемых схем.
schema-api.datasource.username: Имя пользователя БД метаданных для управляемых схем.
schema-api.datasource.password: Пароль пользователя БД метаданных для управляемых схем.
schema-api.enabled: Параметр позволяет включать (true) и отключать (false) поддержку создания схем по метаданным

Пример заполнения ключей для адаптера БД:

{
"cache.concurrency-level": "8",
"cache.expire-after-write": "PT30S",
"cache.initial-capacity": "32",
"cache.maximum-size": "1024",
"datasource.access-handler": "ru.igtel.sgate.adapter.db.accessHandlers.DBAccessHandler",
"datasource.dialect": "ru.igtel.ms.camel.sql.DBHelper",
"datasource.driver": "org.dbsql.Driver",
"datasource.jdbc-url": "jdbc:dbsql://db.example.ru:5432/sgate_db",
"datasource.password": "passwd",
"datasource.username": "login",
"schema.prefix": "custom",
"schema-api.datasource.driver": "org.postgresql.Driver",
"schema-api.datasource.jdbc-url": "jdbc:postgresql://ci.igtel.ru:5432/sgate_db",
"schema-api.datasource.username": "username",
"schema-api.datasource.password": "password",
"schema-api.enabled": "true"
}

4.4.4.4. Настройка адаптера полнотекстового поиска¶

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

security.adapter.username: Логин к адаптеру Remedy.
security.adapter.password: Пароль к адаптеру Remedy.
security.adapter.url: URL к адаптеру Remedy.
security.salt.period: Период кеширования «соли» к адаптеру Remedy в формате ISO 8601.
solr.username: Логин к Solr.
solr.password: Пароль к Solr.
solr.url: URL к серверу Solr.

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

{
"security.adapter.password": "passwd",
"security.adapter.url": "http://integration.example.ru:8082",
"security.adapter.username": "login",
"security.salt.period": "PT5H",
"solr.password": "SolrRocks",
"solr.uri": "http://solr.example.ru:8983/solr",
"solr.username": "solr"
}

4.4.4.5. Настройка адаптера CMDB¶

Для адаптера CMDB необходимо добавить следующие ключи в секрет/секреты Vault:

graph.ci.name: Поле CMDB, в котором хранится название Базы знаний.
graph.cluster-conf: Конфигурация кластера Gremlin-сервера. Подробнее см. http://tinkerpop.apache.org/docs/current/reference/#_configuration.
graph.database.conf: Конфигурация подключения к OrientDB с помощью Gremlin. Подробнее см. https://orientdb.com/docs/3.0.x/tinkerpop3/OrientDB-TinkerPop3.html.
graph.database.entry-prefix: Префикс названий вершин и граней в графе CMDB.
graph.identifier: Поле CMDB, в котором хранится идентификатор Базы знаний.
graph.traversal-label: Название переменной для обхода графа в скриптах.

Пример заполнения ключей для адаптера CMDB:

{
"graph.ci.name": "Instance Name",
"graph.cluster-conf": {
    "hosts": [
    "localhost"
    ],
    "password": "passwd",
    "port": "8182",
    "username": "login"
},
"graph.database.conf": {
    "gremlin.graph": "org.apache.tinkerpop.gremlin.orientdb.OrientFactory",
    "orient-pass": "passwd",
    "orient-transactional": "true",
    "orient-url": "remote:cmdb.example.ru/cmdb",
    "orient-user": "login"
},
"graph.database.entry-prefix": "",
"graph.identifier": "UUID",
"graph.traversal-label": "g"
}

4.4.5. Установка и настройка нескольких экземпляров одного адаптера¶

В некоторых случаях необходимо создать несколько экземпляров одного адаптера.

Создание нескольких экземпляров одного адаптера с одинаковым набором ключей в секретах Vault требуется, например, для балансировки нагрузки на сервер и формирования отказоустойчивой Системы.

Создание нескольких экземпляров одного адаптера с разным набором ключей в секретах Vault позволяет, например, работать сразу с несколькими источниками данных (использовать несколько разных БД).

Все экземпляры адаптера устанавливаются аналогично (см. Установка адаптера). Для каждого экземпляра адаптера будет создан свой контейнер. Для каждого экземпляра адаптера нужно выполнить настройку: в зависимости от целей создания дополнительного экземпляра адаптера для него необходимо создать новые секреты в Vault или использовать уже существующие.

4.4.5.1. Установка и настройка нескольких экземпляров адаптера с одинаковым набором настроек¶

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

Сначала необходимо выполнить общую настройку всех сервисов (в том числе и всех создаваемых экземпляров БД), то есть добавить общие для всех сервисов ключи и их значения в соответствующий секрет Vault.

В примере это секрет «common» с общими настройками:

{
"basic.password": "passwd",
"basic.username": "login",
"jwt.algorithm": "HS512",
"jwt.key": "4bAKMH0ob8d2v4m0yOLuI/18psZgEo45AXnOQ9d9rd5Yzux4CnL5f1POQmrjJLCfg7Pn+8Ohqb8mGjlA/15Ciw==",
"ssl.enabled": "true",
"ssl.store-path": "keystore.jks",
"ssl.store-pass": "storepasswd",
"ssl.key-pass": "keypasswd"
}

Описание общих ключей см. Общая настройка всех сервисов.

Затем необходимо создать секрет в Vault с настройками БД. В примере это секрет «db».

Секрет «db» с настройками БД:

{
"cache.concurrency-level": "8",
"cache.expire-after-write": "PT30S",
"cache.initial-capacity": "32",
"cache.maximum-size": "1024",
"datasource.access-handler": "ru.igtel.sgate.adapter.db.accessHandlers.DBAccessHandler",
"datasource.dialect": "ru.igtel.ms.camel.sql.DBHelper",
"datasource.driver": "org.dbsql.Driver",
"datasource.jdbc-url": "jdbc:dbsql://db.example.ru:5432/sgate_db",
"datasource.password": "passwd",
"datasource.username": "login",
"schema.prefix": "custom"
}

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

Затем необходимо загрузить образ адаптера БД (см. Установка адаптера).

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

Запуск контейнера с первым адаптером:

docker run -d \
--env sgate.server.host=0.0.0.0 \
--env sgate.server.port=8083 \
--env sgate.vault.url=http://vault.example.ru:8200 \
--env sgate.vault.token=s.xRYEe6FCAHn1DAdOAqodkz4Z \
--env sgate.vault.engine=sgate \
--env sgate.vault.version=2 \
--env sgate.vault.sources="common db" \
-p 8083:8083 --name sgate_db1 \
registry.igtel.ru:6443/sgate/integration_db

Запуск контейнера со вторым адаптером:

docker run -d \
--env sgate.server.host=0.0.0.0 \
--env sgate.server.port=8084 \
--env sgate.vault.url=http://vault.example.ru:8200 \
--env sgate.vault.token=s.xRYEe6FCAHn1DAdOAqodkz4Z \
--env sgate.vault.engine=sgate \
--env sgate.vault.version=2 \
--env sgate.vault.sources="common db" \
-p 8084:8084 --name sgate_db2 \
registry.igtel.ru:6443/sgate/integration_db

В результате будут установлены и настроены два экземпляра адаптера БД с одинаковым набором настроек, которые хранятся в секретах «common» и «db».

4.4.5.2. Установка и настройка нескольких экземпляров адаптера с разным набором настроек¶

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

Сначала необходимо выполнить общую настройку всех сервисов (в том числе и всех создаваемых экземпляров БД), то есть добавить общие для всех сервисов ключи и их значения в соответствующий секрет Vault.

В примере это секрет «common» с общими настройками:

{
"basic.password": "passwd",
"basic.username": "login",
"jwt.algorithm": "HS512",
"jwt.key": "4bAKMH0ob8d2v4m0yOLuI/18psZgEo45AXnOQ9d9rd5Yzux4CnL5f1POQmrjJLCfg7Pn+8Ohqb8mGjlA/15Ciw==",
"ssl.enabled": "true",
"ssl.store-path": "keystore.jks",
"ssl.store-pass": "storepasswd",
"ssl.key-pass": "keypasswd"
}

Описание общих ключей см. Общая настройка всех сервисов.

Затем необходимо создать два секрета в Vault с настройками БД для двух экземпляров БД. В примере это секреты «db1» и «db2».

Секрет «db1» с настройками БД:

{
"cache.concurrency-level": "8",
"cache.expire-after-write": "PT30S",
"cache.initial-capacity": "32",
"cache.maximum-size": "1024",
"datasource.access-handler": "ru.igtel.sgate.adapter.db.accessHandlers.DBAccessHandler",
"datasource.dialect": "ru.igtel.ms.camel.sql.DBHelper",
"datasource.driver": "org.dbsql.Driver",
"datasource.jdbc-url": "jdbc:dbsql://db1.example.ru:5432/sgate_db",
"datasource.password": "passwd1",
"datasource.username": "login1",
"schema.prefix": "custom"
}

Секрет «db2» с настройками БД:

{
"cache.concurrency-level": "8",
"cache.expire-after-write": "PT30S",
"cache.initial-capacity": "32",
"cache.maximum-size": "1024",
"datasource.access-handler": "ru.igtel.sgate.adapter.db.accessHandlers.DBAccessHandler",
"datasource.dialect": "ru.igtel.ms.camel.sql.DBHelper",
"datasource.driver": "org.dbsql.Driver",
"datasource.jdbc-url": "jdbc:dbsql://db2.example.ru:5432/sgate_db",
"datasource.password": "passwd2",
"datasource.username": "login2",
"schema.prefix": "custom"
}

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

Затем необходимо загрузить образ адаптера БД (см. Установка адаптера).

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

Запуск контейнера с первым адаптером:

docker run -d \
--env sgate.server.host=0.0.0.0 \
--env sgate.server.port=8083 \
--env sgate.vault.url=http://vault.example.ru:8200 \
--env sgate.vault.token=s.xRYEe6FCAHn1DAdOAqodkz4Z \
--env sgate.vault.engine=sgate \
--env sgate.vault.version=2 \
--env sgate.vault.sources="common db1" \
-p 8083:8083 --name sgate_db1 \
registry.igtel.ru:6443/sgate/integration_db

Запуск контейнера со вторым адаптером:

docker run -d \
--env sgate.server.host=0.0.0.0 \
--env sgate.server.port=8084 \
--env sgate.vault.url=http://vault.example.ru:8200 \
--env sgate.vault.token=s.xRYEe6FCAHn1DAdOAqodkz4Z \
--env sgate.vault.engine=sgate \
--env sgate.vault.version=2 \
--env sgate.vault.sources="common db2" \
-p 8084:8084 --name sgate_db2 \
registry.igtel.ru:6443/sgate/integration_db

В результате будут установлены и настроены два экземпляра адаптера БД с разным набором настроек:

У первого экземпляра адаптера БД настройки хранятся в секретах «common» и «db1».
У второго экземпляра адаптера БД настройки хранятся в секретах «common» и «db2».

4.4.6. Настройка трансформаций в адаптерах¶

Трансформация позволяет корректно преобразовывать запросы к адаптеру в запросы к источнику данных и обратно - ответ источника данных в ответ адаптера. С помощью трансформаций можно преобразовать:

Название схемы.
Названия полей.
Типы данных.

Трансформации описываются в формате JSON. Для каждой схемы, требующей трансформации, создается JSON-файл с описанием правил трансформации. Название файла должно быть следующего формата:

%schema_alias%.json

где «%schema_alias%» - это название схемы в Системе (например, incidents.json).

Для добавления JSON-трансформаций нужно подключить папку с JSON-файлами трансформаций на сервере к папке /app/resources/transform в контейнере. Для этого при запуске контейнера из консоли нужно использовать параметр -v:

-v /path/to/transform:/app/resources/transform

После того как адаптер получает запрос, он ищет трансформацию для соответствующей схемы (т.е. в папке /app/resources/transform адаптер ищет JSON-файл, содержащий в своем названии соответствующее название схемы).

Если трансформация не найдена, то названия полей и схемы используются как есть, а преобразование типов данных выполняется драйвером источника данных. Если трансформация найдена, то запрос и ответ преобразуются в соответствии с правилами трансформации. Названия полей, не описанные в правилах, используются как есть, а типы данных в этих полях преобразуются драйвером источника данных.

4.4.6.1. Пример JSON-файла трансформации¶

JSON-файл трансформации можно рассмотреть на следующем примере:

{
  "properties": {
   "schema": "incidents",
   "key": "incident_number",
   "generator": "DB_MANAGED"
  },
 "fields": {
   "id": {
    "alias": "incident_number",
   "type": "varchar",
    "type_out": "varchar"
  },
 "created": {
   "alias": "create_date",
   "type": "timestamp"
 },
 "priority": {
   "type": "integer"
 },
 "status": "integer"
}
}

Здесь:

properties

Указываются различные параметры трансформации. На текущий момент доступен только обязательный параметр «schema» - название схемы источника данных.

generator

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

DB_MANAGED - значение генерируется БД (автоинкремент и др.)
UUIDv4 - значение генерируется адаптером в формате UUIDv4
DISABLE - генерация запрещена, ID должен быть задан в явном виде клиентом или иным способом

Для индивидуальной настройки генератора в отдельно взятой схеме в свойствах трансформации можно указать используемый тип генератора. Параметр необязателен. По умолчанию в адаптере генерация ID запрещена (DISABLE).

schema

Указывается схема данных маппинга

key

Указывается одно поле источника данных в качестве идентификатора.

Если параметр key не задан, в качестве ключа будет использовано поле с названием id.

fields

В объекте описывается маппинг полей и их типы. Ключами объекта fields являются названия полей источника данных (адаптера), а значениями - объект с описанием поля, где:

alias - (необязательное) название поля в Системе. Если не указано, то название поля в системе совпадает с названием в источнике данных.
type - тип поля в источнике данных
type_out - (необязательное) тип поля в Системе. Если не указан, то тип поля в системе совпадает с типом в источнике данных.

Также возможна упрощенная запись маппинга, когда вместо объекта с описанием поля указывается только тип поля. Например, определение поля:

"status": "integer"

эквивалентно записи в полной форме

"status": {
"alias": "status",
"type": "integer",
"type_out": "integer"
}

4.4.6.2. Поддерживаемые типы данных для БД¶

Поддерживаются следующие типы данных для БД:

Текстовые типы данных:
- char,
- varchar,
- longvarchar.
Числовые типы данных:
- bit,
- tinyint,
- smallint,
- integer,
- bigint,
- real,
- float,
- double,
- numeric
- decimal.
Дата/время:
- date,
- time,
- timestamp.
Другие типы данных:
- clob,
- blob,
- uuid.

4.4.6.3. Стратегии обработки ошибок при трансформации данных¶

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

Стратегии для правил (если правило не найдено):
- THROW_ERROR - выдавать ошибку (по умолчанию)
- PASS_THROUGH - пропускать данные без трансформации
Стратегии для полей (если поле не определено в конфигурации):
- KEEP_ORIGINAL - пропускать данное поле без трансформации
- IGNORE - игнорировать поле и его значение (по умолчанию)
- THROW_ERROR - выдавать ошибку
Стратегии для данных (если трансформация данных завершилась ошибкой):
- KEEP_ORIGINAL - пропустить значение без трансформации
- SET_NULL - установить в NULL
- THROW_ERROR - выдавать ошибку (по умолчанию)
- STRINGIFY - преобразовать в строку

Применение правил не по умолчанию требует адаптации/доработки адаптера. Осуществляется разработчиком ПО.