VK Cloud logo
Помощь

Добавление SaaS-приложенияBeta

Сервис Marketplace и SaaS-приложение взаимодействуют между собой через SaaS-брокер по протоколу VK OSB. Протокол предоставляется платформой VK Cloud.

Требования к SaaS-брокеру:

  • Брокер должен реализовывать методы, которые описывают жизненный цикл инстансов сервиса. Методы представлены на схеме.

  • В брокере должна быть настроена аутентификация по безопасному протоколу HTTPS c сертификатом, выданным доверенным центром сертификации.

Поставщик SaaS-приложения разрабатывает SaaS-брокер полностью самостоятельно либо на основе шаблона, который предоставляется платформой VK Cloud. В шаблоне уже реализовано взаимодействие между магазином и брокером. Его необходимо дополнить описанием взаимодействия брокера с конкретным SaaS-приложением. Шаблон разработан на языке Python на основе фреймворка FastAPI.

Эта инструкция предназначена для случая разработки SaaS-брокера на основе шаблона от VK Cloud.

Подготовительные шаги

  1. Отправьте письмо на marketplace@cloud.vk.com. В письме запросите:

    • протокол VK OSB;
    • шаблон для разработки SaaS-брокера;
    • имена тестовых и открытых пространств имен Marketplace и доступ к ним.

  2. Отправьте на marketplace@cloud.vk.com письмо с вложенной в него иконкой в формате SVG размером не менее 62 × 62 пикселей. Размер файла с иконкой не должен превышать 1 МБ.

    Иконка сервиса отображается в карточке сервиса:

    • В каталоге магазина.
    • На вкладке Описание сервиса на странице сервиса.

    В ответном письме будет выслан URL иконки, который указывается в JSON-файле конфигурации сервиса.

  3. Зарегистрируйтесь на VK Cloud. Учетная запись VK Cloud необходима для тестирования приложения в магазине.

1. Опишите конфигурацию сервиса (тарифные планы, опции)

  1. Создайте файл catalog_<ИМЯ_СЕРВИСА>.json.

  2. В JSON-файле опишите конфигурацию сервиса, используя следующую структуру:

    {    "services": [    {    <ПАРАМЕТРЫ_СЕРВИСА>,    "preview": {        "parameters": [            {            "name": "<ИМЯ_ОПЦИИ_1>" // Имя первой тарифной опции            },            {            "name": "<ИМЯ_ОПЦИИ_2>" // Имя второй тарифной опции            },            ...        ]        },    "plans": [        { // Описание первого тарифного плана            <ПАРАМЕТРЫ_ПЛАНА>,            "display": {            },            "billing": {            },            "schemas": {            }        },        { // Описание второго тарифного плана            <ПАРАМЕТРЫ_ПЛАНА>,            "display": {            },            "billing": {            },            "schemas": {            }        },        ...        ]    }    ]}

    Здесь:

    • <ПАРАМЕТРЫ_СЕРВИСА> — параметры сервиса.

    • Секции preview и plans вместе определяют вид матрицы тарифных планов. В матрице будут отображаться все тарифные планы, указанные в секции plans, и тарифные опции, указанные в секции preview.

    • Массив parameters секции preview содержит имена тарифных опций, может быть пустым. Эти имена используются только в конфигурационном JSON-файле. В интерфейсе магазина тарифные опции будут отображаться с именами, заданными в секции schemas параметром description этих опций.

    • Секция plans описывает тарифные планы и их опции и для каждого плана содержит следующие блоки:

2. Разработайте SaaS-брокер

  1. Разработайте клиент для взаимодействия с API вашего сервиса.

  2. Разработайте сервисный менеджер, описывающий взаимодействие брокера и сервиса. Для этого реализуйте следующие методы:

    Метод

    Входные данные

    Создание тенанта или аккаунта

    • OSB ID инстанса сервиса, который формируется магазином при подключении сервиса. OSB ID передается в SaaS-приложение, чтобы SaaS-приложение сформировало ID инстанса сервиса. ID инстанса сервиса используется в методах, описанных ниже в таблице.
    • ID тарифного плана.
    • Тарифные опции плана, описанные в JSON-файле конфигурации сервиса в секции plans.schemas.service_instance.create.
    • (Опционально) Контекст, содержащий информацию о пользователе: электронная почта, уникальный идентификатор проекта (PID)

    Обновление тенанта или аккаунта

    Получение и удаление тенанта или аккаунта

    ID инстанса сервиса

    Создание сервисных привязок (bindings)

    Получение и удаление сервисных привязок

    • ID инстанса сервиса.
    • ID сервисной привязки

  3. Интегрируйте клиент в сервисный менеджер.

  4. Настройте аутентификацию в брокере.

  5. Если в SaaS-приложении есть постоплатные тарифные опции и метрики по ним собираются по pull-модели, выполните дополнительные действия:

    1. В сервисном менеджере реализуйте метод для получения отчета по фактически использованным ресурсам SaaS-приложения. В ответе на запрос брокер должен передать магазину отчет.

    2. В сервисном менеджере реализуйте метод для сообщения брокеру о том, что отчет обработан (списание денежных средств по отчету произошло или запланировано).

3. Загрузите конфигурацию сервиса в брокер

  1. Перейдите в директорию с брокером.

  2. Поместите файл с конфигурацией сервиса catalog_<ИМЯ_СЕРВИСА>.json в поддиректорию resources.

  3. В файле resources/plan_mapping.json укажите:

    • <ИМЯ_СЕРВИСА> — имя сервиса.

    • <ID_ПЛАНА> — ID тарифных планов, указанных в файле catalog_<ИМЯ_СЕРВИСА>.json.

    • <SAAS_ID_ПЛАНА> (формат string) — ID тарифных планов на стороне сервиса, соответствующих ID тарифных планов <ID_ПЛАНА>.

      {  "<ИМЯ_СЕРВИСА>": {    "<ID_ПЛАНА>": <SAAS_ID_ПЛАНА>,    "<ID_ПЛАНА>": <SAAS_ID_ПЛАНА>  }}

    Пример содержимого файла plan_mapping.json:

    {  "VKT": {    "0dc54b75-XXXX-89d5a47eef71": 1,    "312b628e-XXXX-080ab4ca3acb": 2,    "e2ae1588-XXXX-3f5081a799a9": 3,    "b54e7247-XXXX-7a9dccc22e7b": 4  }}

  4. В директории с брокером переименуйте файл .env.example в .env.

  5. В файле .env укажите имя сервиса в BROKER_MODE:

    BROKER_MODE=<ИМЯ_СЕРВИСА>

4. (Опционально) Протестируйте брокер локально

  1. В файле .env в директории брокера опишите переменные окружения:

    • BROKER_PROVIDER_CLIENT_ID — имя брокера для доступа к SaaS-приложению.
    • BROKER_PROVIDER_SECRET — пароль для доступа брокера к SaaS-приложению.
    • BROKER_PROVIDER_URL — URL SaaS-приложения.
    • BROKER_USERNAME — имя магазина для межсервисного взаимодействия c брокером.
    • BROKER_PASSWORD — пароль магазина для межсервисного взаимодействия с брокером.

  2. В файле .env в директории брокера укажите значения переменных для доступа к БД брокера.

  3. Установите Python-библиотеки, выполнив команду:

    pip install -r requirements/prod.txt

  4. Запустите брокер, выполнив команду:

    gunicorn app.main:app --log-file - --workers ${UVICORN_WORKERS:-1} --worker-class uvicorn.workers.UvicornWorker --bind 0.0.0.0:${BROKER_PORT:-8000} --timeout ${WORKER_TIMEOUT:-90}

    Пример ответа на команду запуска брокера:

    INFO:     Started server process [34934]INFO:     Waiting for application startup.INFO:     Application startup complete.INFO:     Uvicorn running on http://0.0.0.0:8000 (Press CTRL+C to quit)

  5. После установки брокера откройте в браузере страницу http://0.0.0.0:8000/docs.

    Страница содержит описание API брокера в редакторе Swagger.

  6. Выполните запросы API, используя следующие параметры:

    • Значение версии протокола VK OSB x-broker-api-version (например, "0.1").
    • Значение BROKER_USERNAME из файла .env.
    • Значение BROKER_PASSWORD из файла .env.

5. Разверните образ с брокером в окружении

Чтобы собрать образ, воспользуйтесь файлом Dockerfile в директории шаблона брокера.

6. Зарегистрируйте брокер

Отправьте письмо на marketplace@cloud.vk.com. В письме укажите:

  • Информацию о компании:

    • имя компании,
    • контактное лицо,
    • телефон.

  • Электронную почту пользователя, которому будут приходить уведомления об ошибках при создании инстансов сервиса.

  • Параметры брокера, приведенные в таблице.

Имя

Описание

Формат

Обязательный

name

Имя брокера

string

Добавление SaaS-приложения

url

URL, на который будут отправляться запросы от магазина

string

Добавление SaaS-приложения

description

Описание брокера

string

Добавление SaaS-приложения

osb_version

Версия протокола VK OSB

string

Добавление SaaS-приложения

username

Имя магазина для межсервисного взаимодействия c брокером.

string

Добавление SaaS-приложения

password

Пароль магазина для межсервисного взаимодействия с брокером.

string

Добавление SaaS-приложения

После регистрации брокера SaaS-приложение будет доступно в тестовом пространстве имен магазина. В открытом пространстве имен магазина сервис будет доступен только после публикации.

7. Протестируйте сервис в магазине

Чтобы проверить, как сервис будет функционировать в VK Cloud, протестируйте его в тестовом пространстве имен магазина:

  1. Отправьте письмо на marketplace@cloud.vk.com, чтобы получить грант на тестирование сервиса. Средства будут зачислены на бонусный счет вашего проекта в VK Cloud.

  2. Если у вас нет доступа к тестовым пространствам имен, указанным в конфигурации сервиса, отправьте письмо на marketplace@cloud.vk.com. В письме укажите:

    • Имена тестовых пространств имен Marketplace, заданных в параметре metadata в JSON-файле конфигурации сервиса.
    • Электронную почту пользователя, которому необходим доступ в тестовые пространства имен Marketplace.

  3. Перейдите в раздел Магазин приложений личного кабинета VK Cloud.

  4. Нажмите кнопку Все решения.

  5. Нажмите на карточку вашего сервиса и перейдите на вкладку Тарифные планы.

  6. Убедитесь, что мастер конфигурации каждого тарифного плана отображается корректно.

  7. Подключите сервис.

  8. Обновите инстанс сервиса:

    1. Поменяйте значения тарифных опций текущего тарифного плана.
    2. Перейдите на новый тарифный план.

  9. Проверьте основные пользовательские сценарии сервиса.

  10. Удалите инстанс сервиса.

  11. При необходимости внесите изменения в конфигурацию сервиса:

    1. Перейдите в поддиректорию resources директории с брокером.
    2. Отредактируйте файлы catalog_<ИМЯ_СЕРВИСА>.json и plan_mapping.json.
    3. Повторите тестирование еще раз.

  12. Если вы указали тестовые значения стоимости в конфигурации сервиса на время тестирования и отладки, отредактируйте файл catalog_<ИМЯ_СЕРВИСА>.json, указав в нем реальные значения.

8. Опубликуйте сервис

Отправьте письмо на marketplace@cloud.vk.com. В письме укажите ID сервиса и его ревизию.

Будет проведено модерирование конфигурации сервиса. После этого сервис будет опубликован в магазине.

Публикуемая ревизия сервиса переместится из тестового пространства имен магазина в открытое, указанное в параметре metadata JSON-файле конфигурации сервиса. Сервис будет доступен всем пользователям, имеющим доступ в это открытое пространство имен.

Была ли статья полезна?

Нашли ошибку в тексте? Выделите её и нажмите
Ctrl+Enter
Политика конфиденциальности