As mentioned in the first post about SmartDataCenter, it features various APIs. In this post we will have a look at them. Further I would like to present sdcadmin & sdc-heat, two small Python projects I have been working on. The former is a Python client library for SDCs admin APIs. The latter is an OpenStack Heat plugin that allows provisioning of SmartMachines and KVM VMs on SDC.
For the customers, there is a public facing REST API called the cloudapi. It is the only API that a customer reaches and is also used for the Joyent public cloud. The full documentation can be found here. It allows management of various resources, ranging from VMs to sub-users of your account. A small example for SSH keys associated with a login:
GET /:login/keys will return a list of all SSH keys for the specified
POST /:login/keys with the correct data sent will register a new one.
For authorization, the cloudapi uses something rather special: every HTTP request must be signed with a registered SSH private key. The
Authorization field should look like this:
Authorization: Signature keyId="/loginname/keys/my-key",algorithm="rsa-sha256" <Base64(rsa(sha256($Date)))>
/loginname/keys/my-key corresponds to
Base64(rsa(sha256($Date)))> to the Base64-encoded RSA digital signature of the date of the header, created with the mentioned key. Details are found here and here.
To accomplish the actual tasks, the cloudapi talks to the internal APIs on the admin network. In the following pictures a simplified version of SDCs services and their connectivity to the admin and external network is shown. A full overview is found here.
Following a service oriented architecture, SDC divides the responsibilities for various resources in compact, easy-to-understand API-components. Most of the APIs have a somewhat speaking name. In the table below you find an overview of the core APIs, what they cover and the equivalent project in OpenStack.
|Service Name||Description||OpenStack equivalent|
|amon||alarming and monitoring||Monasca|
|cnapi||compute node api||Nova|
|papi||package api||Flavors in Nova|
|sapi||service api||Services in Keystone|
|vmapi||virtual machine api||Servers in Nova|
|workflow||job runner, orchestrator||Heat|
|ufds||users, accounts, roles (ldap)||Keystone|
As these APIs are only available on the protected internal admin network. To interact with the various APIs, Joyent provides again a node.js package.
sdcadmin – a Python client library for admin network APIs
I have been working on a client library for the SDC admin APIs called sdcadmin. It aims to let the Python user interact with SDC in an easy way. To create a VM, all you need to do is:
from sdcadmin.datacenter import DataCenter dc = DataCenter(sapi=sapi_ip) all_smart_machines = dc.list_smart_machines() my_machine = dc.create_smart_machine(owner=user_uuid, networks=[network_uuid], package=package_small, image=smartmachine_image, alias='my_first_smart_machine')
The DataCenter object manages the discovery of the required APIs using the service API (sapi), handles the HTTP requests and provides
create_* functions. Returned machines (both SmartMachines and KVM) provide functions to control their lifecycle:
my_machine = dc.create_smart_machine(...) my_machine.poll_until(status=dc.STATE_RUNNING) my_machine.status() # => 'running' my_machine.stop() my_machine.poll_until(status=dc.STATE_STOPPED) my_machine.is_stopped() # => True my_machine.delete()
State changes such as
destroy() and complementary blocking operations such as
poll_while(...) are available. The documentation is still incomplete, but will be improved as the project grows.
It’s open source, the source is available on Github. The package is also available on the Python Package Index for easy installation via pip (
pip install sdcadmin). Pull requests are more than welcome! Having issues? Post them directly on Github.
Turning up the Heat
Using sdcadmin I created a plugin for OpenStacks Orchestrator Heat. In its current version, it allows to provision SmartMachines and KVM VMs(
SDC::Compute::SmartMachine & SDC::Compute::KVM).
Initially I intended to use the cloudapi for the plugin. Quickly I realised that not all required resources (networks) are available and the above mentioned authorization required put me off. The use of the admin network API on the other hand requires Heat to be on the admin network itself.
Installation instructions for a minimal KVM VM only running Heat and Keystone are found in the README on Github. Some templates for SmartMachines and KVM VMs are also included. As with sdcadmin, pull requests are welcome! Any issues? Post them directly on Github.