openstack team mailing list archive

[Jay Pipes <jaypipes@xxxxxxxxx>]

Hey all,

So, I wanted to follow up on the work that Andy Smith (termie)
contributed recently and that has now made it into Nova's trunk
branch. The follow up is to ensure everyone is on the same page about
what exactly Andy's patch added to Nova and, perhaps more importantly,
what it did NOT add to Nova. There's been some confusion about this,
so let's clear up the confusion :)

Andy proposed a branch (originally called "easyapi") that added some
functionality to Nova. Specifically, the branch added the following:

* Code cleanup and refactoring around the wsgi.Middleware class to
make that class more flexible (and match other WSGI middleware class
definitions like in Django)
* Reflection service that described the other controllers functioning
in Nova's API
* A server that published a REST-like API where the API call structure
was the name of the Python controller and the controller's method
* A simple client tool that spoke this REST-like API

I'll elaborate a bit more below on what the above enhancements
actually look like as a user of Nova, but before I do that, I want to
point out what Andy's patch did NOT do:

* Change the EC2 API
* Change the OpenStack API
* Make either the EC2 API or OpenStack API preferred
* Remove the ability to enhance the OpenStack API in the future
* Remove the ability to adapt the EC2 API in the future if and when
Amazon enhances the EC2 API
* Make the main Nova API node (bin/nova-api) speak a different API

OK, now that's stated, let me elaborate a bit more on how to use and
understand the new "Direct API" :)

In order to interact with Nova -- i.e. Create a user, a project, a
network, start an instance, etc -- one must issue a call to a Nova API
server. This API server is the program /bin/nova-api and listens for
HTTP calls coming from various clients.  A client could be a web
browser, one of the eucatools programs, the /bin/nova-manage program,
or any other tool that "speaks" to the API server via HTTP(S).

Now, because there are two underlying cloud-controlling APIs that Nova
understands -- the Amazon EC2 API and the Rackspace Cloud Servers v1.0
API (now called simply the "OpenStack API") -- the Nova API server
needs to *route* requests coming in to one or the other cloud
controllers.

As an example, let's take the action of listing the instances in a cloud.

In the Amazon EC2 API, this request would be a GET request to the path
http://ec2.example.com/?Action=DescribeInstances
In the OpenStack API, this request would be a GET request to the path
http://os.example.com/servers/detail

Behind the scenes, these requests are handled by two different
controller classes:

nova.api.ec2.cloud.CloudController.describe_instances() handles the
EC2 API call, and
nova.api.openstack.servers.Controller.detail() handles the OpenStack API call

OK, so what does the Direct API add to the mix?

Well, if one chooses to run the Direct API server -- the
/bin/nova-direct-api program -- another server gets spun up that
allows a user to interact with the *other* API controllers in a more,
well, direct fashion.

If we start up /bin/nova-direct-api, we can use the /bin/stack client
program to show the commands that the *other* API controllers provide.
An example of always easier to understand, so here is what the output
of /bin/stack shows when /bin/nova-direct-api has been started up[1]:

(.nova-venv)jpipes@serialcoder:~/repos/nova/trunk$ ./bin/stack help
usage: stack [options] <controller> <method> [arg1=value arg2=value]

  `stack help` should output the list of available controllers
  `stack <controller>` should output the available methods for that controller
  `stack help <controller>` should do the same
  `stack help <controller> <method>` should output info for a method

<snip>
Available controllers:
   reflect   Reflection methods to list available methods.
   compute   API for interacting with the compute manager.

We can get further help from each controller.  Internally, all this is
doing is using the Reflection service Andy added to ask the controller
to describe its own Python methods. The output looks like this
(abbreviated):

(.nova-venv)jpipes@serialcoder:~/repos/nova/trunk$ ./bin/stack help compute
Available methods for compute:
   suspend                                  suspend the instance with
                                            instance_id
   get_all                                  Get all instances,
                                            possibly filtered by one
                                            of the
   lock                                     lock the instance with
                                            instance_id
   unlock                                   unlock the instance with
                                            instance_id
<snip lots of methods...>

You can also perform SOME actions against the direct API that you
could otherwise use nova-manage or eucatools commands to do. However,
it should be emphasized that this way of working with the "Direct API"
DOES NOT CHANGE the existing EC2 and OpenStack APIs. It is simply a
flexible and hacker-friendly way of working with the system, and at
this point, should be considered just a developer's playground tool
that will help our development teams identify areas of improvement for
the other command-line tools.

Hope this clears up a few things. Andy, feel free to correct me if
I've made any incorrect statements above. I've tried my best to
explain the Direct API concepts.

Cheers!
jay

[1] There were a few outstanding bugs I had to fix before I got
bin/stack and bin/nova-direct-api working, so if you want to see the
above, wait a bit before those fixes are merged into trunk ;)