About Exoscale Organizations

Exoscale ressources are attached to organizations which have one or more users.

Users can have one of the following roles:

  • Owner which own the organizatin and can do anything
  • Tech : only has access to technical ressources
  • Admin : only has access to administrative informations

An organization can purchase a single instance of a given product matching a given plan.

For managed services that requires an account, there must be a single account on the vendor side per Exoscale organizations.

Vendor are free to allow accounts to provide additional users and segmenting management but billing must be reported for the initial organizations that created the account.

Vendor can allow users to fully managed their users list on the vendor platform or can implement a synchronization mechanisms that can manage user access based on Exoscale user access.

On provisioning, a uuid identifier will be provided for that organization which can be used when reporting custom metering.

This exoscale uuid will be passed as both organization_uuid and space_uuid fields to maintain compatibility with broker supporting CloudFoundry.

OpenServiceBroker API

Vendor providing managed services on the Exoscale marketplace should provide an OpenServiceBroker compliant endpoint to receive provision / deprovision query.

The Open Service Broker API project allows independent software vendors, SaaS providers and developers to easily provide backing services to workloads running on cloud native platforms such as Cloud Foundry and Kubernetes. The specification, which has been adopted by many platforms and thousands of service providers, describes a simple set of API endpoints which can be used to provision, gain access to and managing service offerings.

The official specification is available here: https://github.com/openservicebrokerapi/servicebroker/blob/master/spec.md

The following features are currently implemented:

  • Service instance provisioning
  • Service instance update (plan changes, suspensions, users sync)
  • Service instance deprovisiong
  • Synchronous requests support
  • CloudFoundry platform compatibility mode

The following features are under developpement:

  • Asynchronous requests support
  • Automatic catalog management
  • Dashboard URL and SSO support

The following features will be introduced at a later stage and are not yet available:

  • Full service binding support

Endpoint Access

Your production OSBAPI compatible endpoint should be hosted over TLS and accept basic auth authentication.

Plan Setup

A OSBAPI service matches one marketplace product on the Exoscale marketplace.

A OSBAPI plan should be setup for each published plan for that product.

A additinal technical plan must be available for managing suspensions of end-user organizations.

Provisioning

Workflow

  • An organization owner purchase your managed service through the Exoscale marketplace
  • Exoscale makes a provisioning call to the vendor OSBAPI endpoint for a service instance provision with a random uuid
  • The vendor allocate the required ressources and accounts
  • The vendor send a welcome email to the user providing the onboarding instructions
  • The vendor returns a success status if the request was carried out successfully

Provisioning call

PUT http://your-endpoint/v2/service_instances/here-instance-id

PAYLOAD

{
"service_id": "service-test-guid",
"plan_id": "plan1-test-guid",
"organization_guid": "org-guid-here",
"space_guid": "space-guid-here",
"parameters": {"users": [{"email":"email", "full_name": "full name", "role":"owner|tech"}]},
"context": {
    "organization_guid": "org-guid-here",
    "space_guid": "space-guid-here",
}}

Vendor return status code:

  • 201 on successful provisioning.
  • 200 if the instance already existed

See all reponse at https://github.com/openservicebrokerapi/servicebroker/blob/master/spec.md#response-3.

Deprovisioning

Deprovisioning can happened on 3 events:

  • An organization decide to unsubscribe to your product
  • An organization suspensions is not resolved before the 7 (trial) or 30 days delay which trigger a purge of their ressources
  • An organization decide to close their Exoscale account or is terminated.

Deprovision call

DELETE http://your-endpoint/v2/service_instances/here-instance-id?service_id=service-test-guid&plan_id=plan1-test-guid

Vendor should return status code 200 if the deprovision is complete.

See https://github.com/openservicebrokerapi/servicebroker/blob/master/spec.md#response-9.

Deprovisioning and custom metering

When using custom metering, all usage must be reported before the subscription is removed for Exoscale.

It is therefore necessary to post any outstanding usage immediately when receiving a deprovisioning call before returning the result.

Deprovision

Service Instance Update

Service instance update are triggered on 3 events:

  • A customer decides to change his current plan
  • A customer is suspended
  • User list changed on Exoscale side and user sync is turned on

Update request

PATCH http://your-endpoint/v2/service_instances/here-instance-id

PAYLOAD

{
  "service_id": "service-test-guid",
  "plan_id": "plan1-test-guid",
  "parameters": {"users": [{"email":"email", "full_name": "full name", "role":"owner|tech"}]},
}

Vendor should return status code 200 if the update was carried out.

Sell all possible reponse here: https://github.com/openservicebrokerapi/servicebroker/blob/master/spec.md#response-5

User Sync

When user sync is enabled, Exoscale will post the complete list of users of the subscribing organizations as well as post update to the vendor when the list changes.

The vendor OSBAPI endpoint is expected to accept a service instance parameter “users” with the following format:

"users": [
    {
      "email" :"user@email.com",
      "full_name" : "John Doe",
      "role": "owner"
    },
    ...
]

When user sync is disabled, only the informations of the user that made the product purchase will be provided and will never be updated.