# Настроить переносимый сервис в модуле > [HTML Version](portable-services.html) Переносимые сервисы позволяют интегрировать микросервисы в пользовательские модули, расширяя их функциональные возможности. Подключить переносимый сервис в модуле можно несколькими способами. Нужный вариант выбирается в зависимости от среды размещения самого микросервиса, а также используемой поставки ELMA365. При создании сервиса вы можете передать в модуль: - адрес образа микросервиса, размещённого в публичном или приватном репозитории Docker Hub, его внутренние настройки и конфигурации для работы в кластере. Такой способ используется в поставках, поддерживающих развёртывание сервиса в среде исполнения Kubernetes: ELMA365 On‑Premises и SaaS Enterprise; - альтернативный адрес сервиса, установленного на внешнем хостинге с публичным доступом. Способ доступен для всех поставок, но зачастую применяется в облачной поставке ELMA365 SaaS Standard, где нельзя обеспечить работу образа сервиса. В этой статье рассмотрим процесс создания сервиса в пользовательском модуле. Подробнее об использовании микросервисов в разработке пользовательских решений читайте в статьях: - особенности переносимых сервисов и пример использования — [«Переносимые сервисы в модулях»](portable-microservices.md); - реализация проверки стабильного подключения сервиса — [«Пример использования Readiness проверки в переносимых сервисах»](readiness.md); - включение переносимых сервисов в ELMA365 Enterprise — [«Включение переносимых сервисов»](enable-portable-services.md); - разработка собственного микросервиса — [«Рекомендации по разработке микросервисов для переносимых сервисов»](development-key-points.md).  ## Добавить и настроить переносимый сервис 1. Откройте страницу пользовательского модуля, в котором подключается переносимый сервис, и перейдите в **Управление**. 2. На вкладке **Сервисы** нажмите кнопку **+ Сервис** и заполните основные настройки в открывшемся окне: **(portable-services-1.png)** - **Имя\*** — название сервиса, отображаемое в списке на странице модуля; - **Уникальное имя сервиса\*** — имя, которое будет использоваться в коде или скриптах для обращения к сервису. Заданное при создании имя невозможно изменить в дальнейшем; - **Docker контейнер** — в блоке указывается адрес реестра, из которого можно загрузить образ микросервиса для его размещения в отдельном пространстве среды исполнения Kubernetes. Настройка доступна в поставках ELMA365 On‑Premises и SaaS Enterprise: - **Адрес образа\*** — URL-адрес Docker‑образа сервиса. Задаётся в одном из форматов: для Docker Hub используйте [краткий относительный путь](#image-address-formats), для других реестров — [полный путь](#image-address-full-path). Когда для образа требуется аутентификация, нужно указать логин и токен учётных данных. Для этого напротив поля нажмите значок ключа и заполните форму одним из следующих способов: - укажите логин и токен в строковом представлении. При экспорте модуля указанные значения сохраняются и передаются в открытом виде; - чтобы предотвратить случайную утечку данных авторизации при экспорте модуля, используйте шаблонизированные переменные типа [Строка (строка)](360009707032.md#string), созданные в виде [параметров настроек модуля](extention-settings.md). Для этого нажмите значок **\{+\}** и выберите добавленное свойство. В этом случае значения логина и токена указываются на [странице подключения модуля](extention-settings.md#parameters-page), а не вводятся напрямую в окне **Данные авторизации**. При экспорте и последующем импорте модуля конфиденциальная информация не будет случайно передана, поскольку значения параметров настроек удалятся. При этом сами переменные для логина и токена сохранятся. **(portable-services-8.png)** - **Порт HTTP\*** — порт, через который будет происходить взаимодействие с микросервисом. По умолчанию указан порт **3000**. При настройке ознакомьтесь с документацией микросервиса и определите, какой из портов следует выбрать. ```` начало примера ```` **Примечание** При использовании модуля в закрытом контуре без доступа в интернет укажите в ConfigMap переносимых сервисов адрес локального реестра образов и секреты Kubernetes для доступа к нему. Подробнее читайте в статье [«Настройка параметров переносимых сервисов через ConfigMap»](configmap.md#local-address). ```` конец примера - ```` **Альтернативный адрес сервиса** — блок заполняется, если микросервис размещён и функционирует на стороннем сервере с публичным адресом доступа. Вы можете указать URL‑адрес сервиса одним из следующих способов: - внести адрес в строковом представлении, например **https://example.mathcalculation.com**; - использовать предварительно созданные параметры из настроек модуля и [задать шаблон адреса](#alternative-address). В этом случае, если компоненты адреса изменяются, вы сможете отредактировать значения параметров в модуле, а не настраивать подключение повторно. Обратите внимание, если в поставках ELMA365 On‑Premises и SaaS Enterprise указать оба адреса, то будет использоваться адрес образа. 3. Нажмите **Сохранить**. 4. Откроется окно **Редактирование сервиса**, в котором можно: (portable-services-5.png) - отредактировать или добавить [адрес образа](#image-address-formats) и порт, а также указать [дополнительные настройки Docker‑контейнера](#docker-settings). Например, можно задать количество экземпляров микросервиса, добавить переменные окружения, настроить Liveness- и Readiness‑пробы; - отредактировать или указать публичный адрес сервиса, нажав значок шестерёнки справа от поля **Альтернативный адрес сервиса**. Чтобы адрес формировался на основе параметров модуля, для него можно [задать шаблон](#alternative-address). ## Форматы для адреса образа В зависимости от размещения Docker‑образа укажите в настройках сервиса: - **краткий относительный путь** — применяется, если образ расположен в реестре по умолчанию — Docker Hub. Формат: **:**, где: - **** — путь к образу в реестре. Обязателен; - **** — тег образа. Необязателен. ```` начало примера ```` **Примеры** Адреса контейнеров в репозитории Docker Hub: - **nginx**; - **nginx:latest**; - **chialab/math-api**; - **chialab/math-api:latest**; - **company/service**; - **company/service:v1.0.0**. ```` конец примера - ```` **полный путь** — для публичного или приватного репозитория, расположенного на отдельном сервере. Формат: **:/:**, где: - **** — доменный адрес реестра образов. Обязателен; - **** — порт, по которому можно получить доступ к реестру образов. Необязателен; - **** — путь к образу в реестре. Обязателен; - **** — тег образа. Необязателен. ```` начало примера ```` **Примеры** Адреса контейнеров в сторонних реестрах: - **company.goharbor.io/math-api**; - **company.goharbor.io:5005/math-api:v1.0.0**; - **registry.company.com/service/app**; - **registry.company.com:5005/service/app:latest**. ```` конец примера ```` Подробнее об адресах образов читайте в [официальной документации Kubernetes](https://kubernetes.io/docs/concepts/containers/images/#image-names). ### Проверка корректности адреса Для проверки загрузите образ микросервиса с помощью команды: ```` docker pull ```` Где \[OBJECT\]** **— адрес образа. Если загрузка проходит успешно, адрес можно использовать для сервиса в модуле ELMA365. ## Шаблон альтернативного адреса сервиса Альтернативный адрес сервиса можно указать с помощью параметров модуля. Такой способ позволяет более гибко управлять переносимым сервисом. Например, вы можете изменять компоненты адреса на [странице подключения модуля](extention-settings.md#parameters-page). Чтобы настроить шаблон адреса сервиса, выполните следующие шаги: 1. Откройте страницу управления пользовательского модуля, в который будет добавляться переносимый сервис. 2. Перейдите на вкладку **Настройки** и создайте свойства типа **Строка (строка)**, из которых будет состоять адрес сервиса. Например, это могут быть два параметра: для записи протокола передачи данных и для указания базового адреса сервиса. 3. В настройках при создании сервиса в модуле укажите шаблон в поле **Адрес сервиса**. Для этого нажмите значок **\{+\}**, выберите созданные ранее параметры и сохраните настройки. **(portable-services-6.png)** 4. Чтобы отредактировать указанный адрес, в настройках сервиса нажмите значок шестерёнки справа от опции **Альтернативный адрес сервиса**. Отредактируйте шаблон или задайте новый адрес и сохраните изменения. 5. Сохраните настройки сервиса. Теперь адрес сервиса можно указать, изменить или удалить в настройках включённого модуля. Если поля не заполнены, связь с сервисом недоступна. **(portable-services-7.png)** ## Настройки Docker-контейнера В поставках ELMA365 On‑Premises и SaaS Enterprise образ микросервиса можно разместить в среде исполнения Kubernetes. Чтобы задать настройки развёртывания микросервиса, нажмите значок шестерёнки справа от названия блока **Docker контейнер**. В открывшемся окне настройка выполняется на нескольких вкладках: [Основные настройки](#main-tab), [Переменные окружения](#variables-tab), [Liveness](#liveness-tab), [Readiness](#readiness-tab). ### Вкладка «Основные настройки» **(portable-services-2.png)** - **Адрес образа\***, **Порт HTTP\*** — вы можете отредактировать адрес образа, логин и токен для доступа к репозиторию и порт подключения, указанные при [создании переносимого сервиса](#add-portable-microservices); - **Дополнительные порты **— вы можете указать для микросервиса дополнительные порты, с помощью которых другие микросервисы модуля смогут к нему обращаться. Для одного микросервиса доступно не более 10 дополнительных портов. ```` начало внимание ```` Чтобы указание дополнительных портов в настройках переносимых сервисов стало доступно, включите фича-флаг \[OBJECT\]. Подробнее читайте в статьях [«Изменение параметров ELMA365 Enterprise»](change-settings-enterprise.md#enable-feature-flag-enterpeise) и [«Изменение параметров ELMA365 Standard»](change-elma365standard-parameters.md#enable-feature-flag-standard). ```` конец внимание - ```` **Количество экземпляров** — укажите, сколько экземпляров микросервисов развернуть и запустить. При изменении количества следует учитывать, что в ELMA365 не поддерживается репликация сервисов. Если это не заложено в микросервис, то каждый из запущенных экземпляров не будет связан с остальными. Вы можете настроить дополнительные параметры переносимого сервиса с помощью ConfigMap. Например, задать лимиты использования ресурсов, включить автомасштабирование микросервиса и настроить размещение подов на узлах кластера. Подробнее читайте в статье [«Настройка параметров переносимых сервисов через ConfigMap»](configmap.md). ### Вкладка «Переменные окружения» Если разработчик предусмотрел конфигурирование микросервиса с помощью переменных окружения, на этой вкладке можно управлять их значениями. Для этого добавьте: - имя переменной окружения — задаётся и указывается разработчиком в документации микросервиса; - значение для созданной переменной окружения — заполняется сразу при добавлении переменной или указывается конечным пользователем модуля на странице его подключения. **Важно**: конфиденциальную информацию, например, логины и токены, рекомендуем [сохранять в секреты Kubernetes и передавать в переносимый сервис с помощью ConfigMap](configmap-secrets.md), а не указывать в открытом виде на вкладке **Переменные окружения**. Такой способ повышает безопасность и минимизирует риски случайной утечки данных. Рассмотрим, как создать переменную окружения и настроить её заполнение через свойство модуля: 1. Нажмите **+ Переменная окружения**. **(portable-services-3.png)** 2. В открывшемся окне: - в поле **Название\*** добавьте имя переменной окружения. Она указывается в документации микросервиса; - поле **Значение\*** заполните одним из способов: - сразу укажите данные; - добавьте заранее созданное свойство из настроек модуля. Таким образом значение переменной окружения смогут изменять конечные пользователи с помощью [поля на странице подключения модуля](extention-settings.md#parameters-page). Например, в программном коде микросервиса предусмотрена возможность ограничить максимальное время ожидания ответа на запрос. Этот лимит указывается в переменной окружения с названием **RequestTimeout**. Чтобы конечные пользователи могли самостоятельно определить значение этой переменной, в [настройках модуля](extention-settings.md) создайте свойство `ServiceTimeout`. Затем перейдите к добавлению переменной **RequestTimeout**, в поле **Значение\*** нажмите значок **\{+\}** и выберите созданное свойство `\{\$ServiceTimeout\}`. Если в шаблоне переменных окружения используются параметры настройки модуля, вы можете включить опцию **Перезапускать при изменении настроек модуля**. В этом случае, когда значения параметров на главной странице настроек модуля изменятся, сервис будет перезапускаться, т. е. полностью удаляться из Kubernetes‑кластера и разворачиваться повторно. Обратите внимание, при добавлении или изменении переменных окружения микросервис также перезапускается. ### Вкладка «Liveness» Здесь вы можете включить возможность Kubernetes автоматически перезапускать микросервис в случае его неработоспособности. В выпадающем списке доступны следующие опции: **Command**, **HTTP**, **TCP**. Прежде чем включать Liveness-пробы и выбирать их тип, ознакомьтесь с документацией подключаемого микросервиса. ### Вкладка «Readiness» На этой вкладке включается возможность Kubernetes не позволять подключаться к микросервису до его полной инициализации. В выпадающем списке доступны следующие опции: **Command**, **HTTP**, **TCP**. Прежде чем включать Readiness-пробы и выбирать их тип, ознакомьтесь с документацией подключаемого микросервиса. Конфигурирование параметров на вкладках **Liveness **и **Readiness** следует выполнять с особой осторожностью. В случае некорректной настройки и получении невалидного ответа Kubernetes будет считать микросервис неработоспособным и перезагружать его вне зависимости от его реального статуса. Включать параметры Liveness-проб и Readiness-проб рекомендуется, только если вы чётко понимаете специфику и последствия их использования. Чтобы закончить настройку добавленного сервиса, в окне редактирования нажмите кнопку **Сохранить**. Все созданные сервисы будут отображаться в управлении модулем, на вкладке **Сервисы**. Чтобы повторно открыть окно редактирования сервиса, нажмите на его название в списке. Для удаления сервиса отметьте его флажком и нажмите на появившуюся в правом углу страницы кнопку **Удалить**. ## Запуск и выключение микросервисов При включении модуля будут запущены все добавленные в него микросервисы. При выключении модуля микросервисы будут остановлены и удалены. Один и тот же образ микросервиса, развёрнутый из разных модулей в одной компании, будет иметь разные экземпляры микросервиса. ## Монитор сервисов модуля При включённом модуле статус добавленных в него микросервисов можно отслеживать на его странице. Для этого рядом с названием модуля** **отображается **Монитор сервисов**. **(portable-services-4.png)** Нажав на кнопку, вы** **увидите список всех микросервисов, заданных переносимыми сервисами. По каждому сервису отображаются данные об образе, из которого поднимается контейнер, о количестве набора реплик и их текущем статусе. При наличии возможностей кластера Kubernetes предоставлять метрики указываются также данные о потреблении ресурсов. Также вы можете просматривать информацию по сервисам в рамках всех модулей компании на странице [Монитор сервисов](service-monitor.md). ## Взаимодействие с микросервисом ### Скрипты Взаимодействовать с микросервисами можно через API, предоставляемый скриптами. Он доступен только на уровне модуля, к которому принадлежит микросервис, например, в виджетах или бизнес-процессах модуля. Обратиться к микросервису можно: - в клиентских и серверных скриптах модуля в формате \[OBJECT\]. Для этого способа взаимодействия [настройте делегированный метод API](extention-api.md#delegated); - в серверных скриптах модуля в формате \[OBJECT\]. Для взаимодействия с микросервисом используйте: 1. Метод \[OBJECT\]: - чтобы отправить простой GET-запрос без дополнительных параметров, укажите в методе \[OBJECT\] относительный путь к API микросервиса. Пример: ```` const res = await Namespace.services.vap.fetch("/SayHello"); if (res.ok) \{ const resText = await res.text(); \} - ```` чтобы отправить другой тип запроса, указать параметры, задать заголовки и тело запроса, в методе \[OBJECT\] передайте \[OBJECT\]. Пример: ```` const res = await Namespace.services.vap.fetch("/RememberMe", \{ method: 'POST', headers: \{ Authorization: 'myToken', \}, body: JSON.stringify(\{ name: 'Ivan', age: 27, \}) \} ); 2. ```` Метод \[OBJECT\]. Позволяет проверить состояние микросервиса. В результате возвращает перечисление \[OBJECT\], которое содержит информацию о текущем статусе микросервиса. Пример: ```` const info = await Namespace.services.vap.status(); ### ```` Обмен данными между двумя переносимыми сервисами В поставках ELMA365 On‑Premises и SaaS Enterprise можно организовать взаимодействие между микросервисами внутри одного модуля. Путь доступа настраивается с помощью переменных окружения. Подробнее читайте в статье [«Рекомендации по разработке микросервисов для переносимых сервисов»](development-key-points.md#communication-between-services). ## Экспорт и импорт модуля с сервисом Экспорт и импорт модуля, имеющего переносимые сервисы, возможен только в случае, если **Переносимые сервисы **разблокированы.