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 :login, while 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)))>

Where /loginname/keys/my-key corresponds to /:login/keys/:key-name and 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 interact with the cloudapi, Joyent provides the node.js package smartdc which doubles as a CLI as well for the use in your own programs. There is also a version for Python by Telefónica.

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.

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 list_*, get_* and 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 start(), stop(), destroy() and complementary blocking operations such as poll_until(...) and 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.