Repository files navigation

The Clever Cloudadd-on api expose a service as aClever Cloud add-on to organization's users or Clever Cloud's users.

Through all this document we will talk aboutexposing a service through an organization. To expose a service to all organization asClever Cloud's partner add-on's providers, the process is the same. The scope policy can be updated by the Clever Cloud teams. Contactpartnership@clever-cloud.com orsupport@clever-cloud.com.

For historical reasons, in Clever Cloud we are used to talk aboutadd-on. However, itwould be more understandable to talk aboutservices. In this document we will mainly use the terms ofadd-on. Consider it in the same way asmanaged services.

The official documentation is available onhttps://www.clever-cloud.com/doc/extend/add-ons-api/.

In the context of an add-on creation or to expose a service through an add-on, we will consider three point of view useful to understand theadd-on api.

• Theadd-on back-end which handle the user's request for an add-on

  • Can be hosted on any infrastructure

• Theadd-on interface with which the end-user will interact with

  • User interface on Clever Cloud. It is a way for the provider to display specifics informations in the Clever Cloud console

• Theadd-on api back-end which is the link betweenClever Cloud users andadd-on's providers

  • Managed and ran by Clever Cloud

To deploy your own service on Clever Cloud through theadd-on api, you need to provide anadd-on back-end and set-up anadd-on interfaceWe will assume youradd-on back-end is ready and up for this section. If not refer to theadd-on back-end section.

{"id":"addon_provider_demo","name":"addon_provider","api": {"config_vars": [],"regions": ["eu"],"password":"<LONG_RANDOM_PASS_PHRASE>","sso_salt":"<LONG_RANDOM_TOKEN>","production": {"base_url":"http://demo_addon_provider.cleverapps.io/addon_management","sso_url":"http://demo_addon_provider.cleverapps.io/"    },"test": {"base_url":"http://demo_addon_provider.cleverapps.io/addon_management","sso_url":"http://demo_addon_provider.cleverapps.io/"    }  }}

Theid must beunique through all Clever Cloud add-ons.

Use aspecific andexplicitid to make sure your as using a unique one

Make sure thatapi/production/base_url andapi/test/base_url arethe same

Make sure thatapi/production/sso_url andapi/test/sso_url arethe same.

test endpoints are used just after the add-on provider creation. Then the production endpoint is used

thebase_url is the endpoint of youradd-on back-end wich handlecreate,deletion andplan change refer tothe base url endpoint section

thesso_url return the custom add-on panel displayed in theClever Cloud Console refer tothe sso url endpoint section

more info about the manifest in the main documentation

Once your manifest has been sent. You can set-up some plan for youradd-on

You can also add some feature at your plans by theedit plans button

At least one plan must be done !

• It is the main endpoint for youradd-on back-end. Each request forprovisioning,deprovisioning orplan change would be done on this url.

• It must behttps connexion

• The call is secure by aBasic authentication

  • theusername is yourprovider id

    addon_provider_demo inthe example

  • thepassword is the value of thepassword field from the manifest

    <LONG_RANDOM_PASS_PHRASE> inthe example

• It is the endpoint called by theAdd-on dashboard panel from theprovided add-on in the client sideClever Cloud console

  

• The call is secured by atoken

  • TheClever Cloud api send aPOST https request with a fieldid,token andtimestamp in the form
  • thetoken is asha1 hash ofid:SALT:timestamp

  note the: between all the values

  • SALT had been provided in themanifest

    <LONG_RANDOM_TOKEN> inthe example

  • You have to check that your computed token match the provided one

In theexample-addon-provider-python folder we provide a minimal example in Python (Flask) to understand how the back-end and the add-on api can work together.

It demonstrates:

• API Backend: Handles provisioning and deprovisioning of resources using Basic Auth.
• Dashboard: Handles SSO authentication and displays a user interface using Token verification.

It is implemented in a single fileserver.py for simplicity.

See theREADME in that folder for more details.

In theexample-addon-provider-js folder we provide a minimal example in Node.js/Express to understand how the back-end and the add-on api can work together.

It demonstrates:

• API Backend: Handles provisioning and deprovisioning of resources using Basic Auth.
• Dashboard: Handles SSO authentication and displays a user interface using Token verification.

See theREADME in that folder for more details.`