About Exoscale Organizations

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

Users can have one of the following roles:

  • OWNER: owns the organization and has full rights
  • TECH: has access to technical resources only
  • ADMIN: has access to administrative information only

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

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

Vendors can allow accounts to provide additional users and segment management, but billing must be reported for the initial organizations that created the account.

Vendors can also allow users to fully manage their user list on the vendor platform, or vendors can implement a synchronization mechanism that manages user access based on Exoscale user access.

On provisioning, a UUID identifier will be provided for the 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 brokers that support CloudFoundry.

Open Service Broker API (OSBAPI)

Vendors providing managed services on the Exoscale Marketplace need to provide an endpoint that is compliant with Open Service Broker to receive provision and deprovision queries.

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.

You can learn more on the Open Service Broker specification.

Exoscale uses Open Service Broker API for provisioning and deprovisioning integration with external vendors.

The API currently has the following features:

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

The following features are under development:

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

We are also working on full-service binding support.

Endpoint access

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

Plan setup

There are a few plan requirements:

  • A OSBAPI service must match one product on the Exoscale marketplace.

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

  • An additional technical plan must be available for managing suspensions of end user organizations.

Provisioning

Workflow

  • An organization owner purchases 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 allocates the required resources and accounts.
  • The vendor sends a welcome email to the user with onboarding instructions.
  • The vendor returns a success status if the request was successful.

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",
}}

The vendor returns either of the following status codes:

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

See all responses at the OSBAPI specifications.

Deprovisioning

Deprovisioning can when:

  • An organization decides to unsubscribe to your product.
  • An organization suspension is not resolved before 7 days in trial mode, or 30 days outside of trial mode, which triggers a purge of their resources.
  • An organization decides to close their Exoscale account, or their account is terminated.

Deprovision call

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

The vendor return status code 200 if the deprovision is complete. See the OSBAPI specifications.

Deprovisioning and custom metering

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

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

Deprovision

Service Instance Update

Service instance updates are triggered by 3 events:

  • A customer decides to change their current plan.
  • A customer is suspended.
  • A user list changes 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"}]},
}

The vendor should return status code 200 if the update was successful. See all possible responses in the OSBAPI specifications.

User Sync

When user sync is enabled, Exoscale will post the complete list of users for the subscribing organization as well as post an 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 information of the user that made the product purchase will be provided. The information will never be updated.