VK Cloud logo

Adding a SaaS applicationBeta

The Marketplace service and the SaaS application interact with each other via a SaaS broker using the VK OSB protocol. The protocol is provided by the VK Cloud platform.

Requirements for the SaaS broker:

  • The broker must implement methods that describe the lifecycle of service instances. The methods are shown in the diagram.

  • The broker must have authentication configured over the secure HTTPS protocol with a certificate issued by a trusted certificate authority.

The SaaS application provider develops the SaaS broker entirely on their own or based on a template provided by the VK Cloud platform. The template already implements the interaction between the marketplace and the broker. It needs to be supplemented with a description of the broker's interaction with a specific SaaS application. The template is written in Python based on the FastAPI framework.

These instructions are intended for the case of developing a SaaS broker based on the template from VK Cloud.

Preparatory steps

  1. Send an email to marketplace@cloud.vk.com. In the email, request:

    • the VK OSB protocol;
    • the template for developing a SaaS broker;
    • the names of the test and public Marketplace namespaces and access to them.
  2. Send an email to marketplace@cloud.vk.com with an icon attached in SVG format at least 62 × 62 pixels in size. The size of the icon file must not exceed 1 MB.

    The service icon is displayed in the service card:

    • In the marketplace catalog.
    • On the Service description tab on the service page.

    A reply email will be sent containing the icon URL, which is specified in the service configuration JSON file.

  3. Register with VK Cloud. A VK Cloud account is required to test the application in the marketplace.

1. Describe the service configuration (tariff plans, options)

  1. Create a catalog_<SERVICE_NAME>.json file.

  2. In the JSON file, describe the service configuration using the following structure:

    {    "services": [    {    <SERVICE_PARAMETERS>,    "preview": {        "parameters": [            {            "name": "<OPTION_NAME_1>" // Name of the first pricing option            },            {            "name": "<OPTION_NAME_2>" // Name of the second pricing option            },            ...        ]        },    "plans": [        { // Description of the first pricing plan            <PLAN_PARAMETERS>,            "display": {            },            "billing": {            },            "schemas": {            }        },        { // Description of the second pricing plan            <PLAN_PARAMETERS>,            "display": {            },            "billing": {            },            "schemas": {            }        },        ...        ]    }    ]}

    Here:

    • <SERVICE_PARAMETERS> — service parameters.

    • The preview and plans sections together define the appearance of the pricing plan matrix. The matrix will display all pricing plans specified in the plans section and the pricing options specified in the preview section.

    • The parameters array of the preview section contains the names of pricing options and can be empty. These names are used only in the configuration JSON file. In the marketplace interface, pricing options will be displayed with the names specified in the schemas section by the description parameter of these options.

    • The plans section describes pricing plans and their options, and for each plan contains the following blocks:

2. Develop the SaaS broker

  1. Develop a client for interacting with the API of your service.

  2. Develop a service manager that describes the interaction between the broker and the service. To do this, implement the following methods:

    Method

    Input data

    Creating a tenant or account

    • The OSB ID of the service instance, which is generated by the marketplace when the service is connected. The OSB ID is passed to the SaaS application so that the SaaS application generates the service instance ID. The service instance ID is used in the methods described below in the table.
    • The tariff plan ID.
    • The tariff plan options described in the service configuration JSON file in the plans.schemas.service_instance.create section.
    • (Optional) Context containing user information: email, unique project identifier (PID)

    Updating a tenant or account

    Retrieving and deleting a tenant or account

    The service instance ID

    Creating service bindings

    Retrieving and deleting service bindings

    • The service instance ID.
    • The service binding ID
  3. Integrate the client into the service manager.

  4. Configure authentication in the broker.

  5. If the SaaS application has postpaid tariff options and metrics for them are collected using the pull model, perform additional steps:

    1. In the service manager, implement a method for obtaining a report on the actually consumed resources of the SaaS application. In response to the request, the broker must send the report to the marketplace.

    2. In the service manager, implement a method for notifying the broker that the report has been processed (funds have been charged according to the report or the charge has been scheduled).

3. Upload the service configuration to the broker

  1. Navigate to the broker directory.

  2. Place the service configuration file catalog_<SERVICE_NAME>.json in the resources subdirectory.

  3. In the resources/plan_mapping.json file, specify:

    • <SERVICE_NAME> — the service name.

    • <PLAN_ID> — the IDs of the tariff plans specified in the catalog_<SERVICE_NAME>.json file.

    • <SAAS_PLAN_ID> (format: string) — the tariff plan IDs on the service side corresponding to the <PLAN_ID> tariff plan IDs.

      {  "<SERVICE_NAME>": {    "<PLAN_ID>": <SAAS_PLAN_ID>,    "<PLAN_ID>": <SAAS_PLAN_ID>  }}

    Example of the plan_mapping.json file contents:

    {  "VKT": {    "0dc54b75-XXXX-89d5a47eef71": 1,    "312b628e-XXXX-080ab4ca3acb": 2,    "e2ae1588-XXXX-3f5081a799a9": 3,    "b54e7247-XXXX-7a9dccc22e7b": 4  }}
  4. In the broker directory, rename the .env.example file to .env.

  5. In the .env file, specify the service name in BROKER_MODE:

    BROKER_MODE=<SERVICE_NAME>

4. (Optional) Test the broker locally

  1. In the .env file in the broker directory, describe the environment variables:

    • BROKER_PROVIDER_CLIENT_ID — the broker name for accessing the SaaS application.
    • BROKER_PROVIDER_SECRET — the password for the broker to access the SaaS application.
    • BROKER_PROVIDER_URL — the URL of the SaaS application.
    • BROKER_USERNAME — the marketplace name for interservice interaction with the broker.
    • BROKER_PASSWORD — the marketplace password for interservice interaction with the broker.
  2. In the .env file in the broker directory, specify the variable values for accessing the broker database.

  3. Install the Python libraries by running the command:

    pip install -r requirements/prod.txt
  4. Start the broker by running the command:

    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}

    Example of the response to the broker start command:

    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. After installing the broker, open the http://0.0.0.0:8000/docs page in your browser.

    The page contains the broker API description in the Swagger editor.

  6. Make API requests using the following parameters:

    • The value of the VK OSB protocol version x-broker-api-version (for example, "0.1").
    • The BROKER_USERNAME value from the .env file.
    • The BROKER_PASSWORD value from the .env file.

5. Deploy the broker image to the environment

To build the image, use the Dockerfile file in the broker template directory.

6. Register the broker

Send an email to marketplace@cloud.vk.com. In the email, specify:

  • Company information:

    • the company name,
    • the contact person,
    • the phone number.
  • The email address of the user who will receive notifications about errors when creating service instances.

  • The broker parameters listed in the table.

Name

Description

Format

Required

name

The broker name

string

Adding a SaaS application

url

The URL to which requests from the marketplace will be sent

string

Adding a SaaS application

description

The broker description

string

Adding a SaaS application

osb_version

The VK OSB protocol version

string

Adding a SaaS application

username

The marketplace name for interservice interaction with the broker.

string

Adding a SaaS application

password

The marketplace password for interservice interaction with the broker.

string

Adding a SaaS application

After the broker is registered, the SaaS application will become available in the test namespace of the marketplace. The service will be available in the public namespace of the marketplace only after publication.

7. Test the service in the marketplace

To check how the service will function in VK Cloud, test it in the test namespace of the marketplace:

  1. Send an email to marketplace@cloud.vk.com to receive a grant for testing the service. The funds will be credited to the bonus account of your project in VK Cloud.

  2. If you do not have access to the test namespaces specified in the service configuration, send an email to marketplace@cloud.vk.com. In the email, specify:

    • The names of the test Marketplace namespaces specified in the metadata parameter of the service configuration JSON file.
    • The email address of the user who needs access to the test Marketplace namespaces.
  3. Go to the Marketplace section of the VK Cloud management console.

  4. Click the All solutions button.

  5. Click your service's card and go to the Pricing plans tab.

  6. Make sure the configuration wizard for each pricing plan is displayed correctly.

  7. Connect the service.

  8. Update the service instance:

    1. Change the values of the pricing options of the current pricing plan.
    2. Switch to a new pricing plan.
  9. Test the main user scenarios of the service.

  10. Delete the service instance.

  11. If necessary, make changes to the service configuration:

    1. Navigate to the resources subdirectory of the broker directory.
    2. Edit the catalog_<SERVICE_NAME>.json and plan_mapping.json files.
    3. Repeat the testing one more time.
  12. If you specified test cost values in the service configuration for the duration of testing and debugging, edit the catalog_<SERVICE_NAME>.json file specifying the real values in it.

8. Publish the service

Send an email to marketplace@cloud.vk.com. In the email, specify the service ID and its revision.

The service configuration will be moderated. After that, the service will be published in the marketplace.

The published revision of the service will move from the test namespace of the marketplace to the public namespace specified in the metadata parameter of the service configuration JSON file. The service will be available to all users who have access to this public namespace.

Was this article helpful?