Переносимые сервисы позволяют интегрировать микросервисы в пользовательские модули, расширяя их функциональные возможности.
Подключить переносимый сервис в модуле можно несколькими способами. Нужный вариант выбирается в зависимости от среды размещения самого микросервиса, а также используемой поставки ELMA365. При создании сервиса вы можете передать в модуль:
- адрес образа микросервиса, размещённого в публичном или приватном репозитории Docker Hub, его внутренние настройки и конфигурации для работы в кластере. Такой способ используется в поставках, поддерживающих развёртывание сервиса в среде исполнения Kubernetes: ELMA365 On‑Premises и SaaS Enterprise;
- альтернативный адрес сервиса, установленного на внешнем хостинге с публичным доступом. Способ доступен для всех поставок, но зачастую применяется в облачной поставке ELMA365 SaaS Standard, где нельзя обеспечить работу образа сервиса.
В этой статье рассмотрим процесс создания сервиса в пользовательском модуле.
Подробнее об использовании микросервисов в разработке пользовательских решений читайте в статьях:
- особенности переносимых сервисов и пример использования — «Переносимые сервисы в модулях»;
- реализация проверки стабильного подключения сервиса — «Пример использования Readiness проверки в переносимых сервисах»;
- включение переносимых сервисов в ELMA365 Enterprise — «Включение переносимых сервисов»;
- разработка собственного микросервиса — «Рекомендации по разработке микросервисов для переносимых сервисов».
Добавить и настроить переносимый сервис
- Откройте страницу пользовательского модуля, в котором необходимо подключить переносимый сервис, и перейдите в Управление.
- На вкладке Сервисы нажмите кнопку + Сервис и заполните основные настройки в открывшемся окне:
- Имя* — название сервиса, отображаемое в списке на странице модуля;
- Уникальное имя сервиса* — имя, которое будет использоваться в коде или скриптах для обращения к сервису. Заданное при создании имя невозможно изменить в дальнейшем;
- Docker контейнер — в блоке настраивается размещение образа микросервиса в отдельном пространстве в среде исполнения Kubernetes. Настройка доступна в поставках ELMA365 On‑Premises и SaaS Enterprise:
- Адрес образа* — URL-адрес docker‑образа сервиса. Для образа, расположенного в Docker Hub, допускается короткое относительное наименование. Когда для образа требуется аутентификация, нужно указать логин и токен учётных данных. Для этого в поле нажмите значок ключа, заполните форму и сохраните данные. Обратите внимание, что логин и токен при экспорте модуля передаются в открытом виде;
- Порт HTTP* — порт, через который будет происходить взаимодействие с микросервисом. По умолчанию указан порт 3000. При настройке ознакомьтесь с документацией микросервиса и определите, какой из портов следует выбрать;
- Альтернативный адрес сервиса — блок заполняется, если микросервис, размещён и функционирует на стороннем сервере с публичным адресом доступа. Вы можете указать URL-адрес сервиса одним из следующих способов:
- внести адрес в строковом представлении, например https://example.mathcalculation.com;
- использовать предварительно созданные параметры из настроек модуля и задать шаблон адреса. В этом случае, если компоненты адреса изменяются, вы сможете отредактировать значения параметров в модуле, а не настраивать подключение повторно.
Обратите внимание, если в поставках ELMA365 On‑Premises и SaaS Enterprise указать оба адреса, то будет использоваться адрес образа.
- Нажмите Сохранить.
- Откроется окно Редактирование сервиса, в котором можно:
- указать дополнительные настройки Docker контейнера, если вы заполнили адрес образа на предыдущем шаге. Для этого нажмите значок шестерёнки справа от опции и в открывшемся окне выберите нужную вкладку: Основные настройки, Переменные окружения, Liveness, Readiness;
- отредактировать альтернативный адрес сервиса, если он был указан на предыдущем шаге. Для этого нажмите значок шестерёнки справа от соответствующей опции.
Настройки Docker контейнера
Настройки Docker контейнера выполняются на следующих вкладках: Основные настройки, Переменные окружения, Liveness, Readiness.
Вкладка «Основные настройки»
В поле Количество экземпляров укажите число экземпляров микросервисов, которое будет поднято. При изменении количества следует учитывать, что в ELMA365 не поддерживается репликация сервисов. Если это не заложено в микросервис, то каждый из запущенных экземпляров не будет связан с остальными.
Вкладка «Переменные окружения»
На этой вкладке создаются переменные окружения образа микросервиса. Они используются, если в микросервисе допускается конфигурирование через переменные среды. Определить доступность конфигурирования можно в документации микросервиса. Для создания переменной на вкладке нажмите + Переменная окружения и заполните шаблон параметра сервиса в открывшемся окне.
Обратите внимание, при добавлении или изменении переменных окружения микросервис перезапускается.
Вы можете не только задавать переменные окружения при разработке, но и предоставлять возможность их изменения конечным пользователям. Для этого при создании переменной в шаблоне можно использовать параметры настройки модуля.
Например, в настройках модуля есть свойство ServiceTimeout. Можно создать переменную окружения RequestTimeout и указать в её шаблоне {$ServiceTimeout}. Тогда пользователи будут изменять значение свойства на главной странице настроек модуля и при этом устанавливать значение для переменной окружения в микросервисе.
Если в шаблоне переменных окружения используются параметры настройки модуля, вы можете включить опцию Перезапускать при изменении настроек модуля. В этом случае, когда значения параметров на главной странице настроек модуля изменятся, сервис будет перезапускаться, т. е. полностью удаляться из Kubernetes-кластера и разворачиваться повторно.
Вкладка «Liveness»
Здесь вы можете включить возможность Kubernetes автоматически перезапускать микросервис в случае его неработоспособности. В выпадающем списке доступны следующие опции: Command, HTTP, TCP. Прежде чем включать Liveness-пробы и выбирать их тип, ознакомьтесь с документацией подключаемого микросервиса.
Вкладка «Readiness»
На этой вкладке включается возможность Kubernetes не позволять подключаться к микросервису до его полной инициализации. В выпадающем списке доступны следующие опции: Command, HTTP, TCP. Прежде чем включать Readiness-пробы и выбирать их тип, ознакомьтесь с документацией подключаемого микросервиса.
Конфигурирование параметров на вкладках Liveness и Readiness следует выполнять с особой осторожностью. В случае некорректной настройки и получении невалидного ответа Kubernetes будет считать микросервис неработоспособным и перезагружать его вне зависимости от его реального статуса. Включать параметры Liveness-проб и Readiness-проб рекомендуется, только если вы чётко понимаете специфику и последствия их использования.
Чтобы закончить настройку добавленного сервиса, в окне редактирования нажмите кнопку Сохранить.
Все созданные сервисы будут отображаться в управлении модулем, на вкладке Сервисы. Чтобы повторно открыть окно редактирования сервиса, нажмите на его название в списке. Для удаления сервиса отметьте его флажком и нажмите на появившуюся в правом углу страницы кнопку Удалить.
Шаблон альтернативного адреса сервиса
Альтернативный адрес сервиса можно указать с помощью параметров модуля. Такой способ позволяет более гибко управлять переносимым сервисом. Например, вы можете изменять компоненты адреса на странице подключения модуля.
Чтобы настроить шаблон адреса сервиса, выполните следующие шаги:
- Откройте страницу управления пользовательского модуля, в который будет добавляться переносимый сервис.
- Перейдите на вкладку Настройки и создайте свойства типа Строка (строка), из которых будет состоять адрес сервиса. Например, это могут быть два параметра: для записи протокола передачи данных и для указания базового адреса сервиса.
- В настройках при создании сервиса в модуле укажите шаблон в поле Адрес сервиса. Для этого нажмите значок {+}, выберите созданные ранее параметры и сохраните настройки.
- Чтобы отредактировать указанный адрес, в настройках сервиса нажмите значок шестерёнки справа от опции Альтернативный адрес сервиса. Отредактируйте шаблон или задайте новый адрес и сохраните изменения.
- Сохраните настройки сервиса.
Теперь адрес сервиса можно указать, изменить или удалить в настройках включённого модуля. Если поля не заполнены, связь с сервисом недоступна.
Запуск и выключение микросервисов
При включении модуля будут запущены все добавленные в него микросервисы. При выключении модуля микросервисы будут остановлены и удалены.
Один и тот же образ микросервиса, развёрнутый из разных модулей в одной компании, будет иметь разные экземпляры микросервиса.
Один и тот же образ микросервиса, развёрнутый из одного модуля в разных компаниях, будет иметь разные экземпляры микросервиса.
Монитор микросервисов
При включенном модуле статус добавленных в него микросервисов можно отслеживать на его странице. Для этого рядом с названием модуля отображается Монитор сервисов.
Нажав на кнопку, вы увидите список всех микросервисов, заданных переносимыми сервисами. По каждому сервису отображаются данные об образе, из которого поднимается контейнер, о количестве набора реплик и их текущем статусе. При наличии возможностей кластера Kubernetes предоставлять метрики указываются также данные о потреблении ресурсов.
Взаимодействие с микросервисом
Скрипты
Взаимодействовать с микросервисами можно через API, предоставляемый скриптами. Он доступен в серверных скриптах и только в модуле, к которому принадлежит микросервис, например, в виджетах или бизнес-процессах модуля. В клиентских скриптах доступа к микросервисам нет.
Доступ к сервисам осуществляется через пространство имён Namespace.services. Если модуль не содержит переносимых сервисов, то это пространство имён будет отсутствовать в автозаполнении скриптов.
Для взаимодействия с микросервисом следует использовать метод fetch.
Простой GET-запрос без дополнительных параметров отправляется, если указать в качестве параметра относительный путь до API микросервиса.
const res = await Namespace.services.vap.fetch("/SayHello");
if (res.ok) {
const resText = await res.text();
}
Чтобы отправить другой тип запроса, указать параметры, задать заголовки и тело запроса, можно воспользоваться методом fetch, в качестве второго параметра которого передаётся FetchRequest.
const res = await Namespace.services.vap.fetch("/RememberMe", {
method: 'POST',
headers: {
Authorization: 'myToken',
},
body: JSON.stringify({
name: 'Ivan',
age: 27,
})
} );
Для проверки состояния микросервиса используется метод status. Результатом будет перечисление ServiceStatus, несущее информацию о текущем статусе.
const info = await Namespace.services.vap.status();
Обмен данными между двумя переносимыми сервисами
Если разработчик микросервиса предусмотрел возможность взаимодействия между двумя микросервисами внутри Модуля, то настроить путь доступа из Переносимого сервиса-1 к Переносимому сервису-2 можно через переменные окружения.
Для этого добавьте в настройку Переносимого сервиса-1 переменную окружения с названием, указанным в документации микросервиса, задайте в ней шаблон имени Переносимого сервиса-2. Например, {$_srv_serv2}.
Экспорт и импорт модуля с сервисом
Экспорт и импорт модуля, имеющего переносимые сервисы, возможен только в случае, если Переносимые сервисы разблокированы.