Xen Management API Draft, version 0.4

Xen Management API Draft, version 0.4

[Ewan Mellor]

[-- Attachment #1: Type: text/plain, Size: 2502 bytes --]

Attached is version 0.4 of the Xen Management API Draft.  This document will
eventually define a fixed XML-RPC protocol for remote and local management of
Xen-based systems.  I would like to invite you to study, give feedback on, and
collaborate around this document, so that we will soon have for the first time
an open source toolstack that exports a supported management API for Xen.

This document presents our ideas in terms of a data model, with an implied
binding to XML-RPC calls. These XML-RPC calls can then be used (over one of a
number of transports) to manage a Xen-based system.

The intention is to standardise both the data model and XML-RPC calls (one
implying the other) and then the Xen project will guarantee that that wire
protocol would be supported for the long term.

Behind that interface, we would then be free to improve Xend, and at the same
time we give a solid foundation for third-party tools (in particular
libvirt-based applications), GUIs, and so on. The API becomes effectively part
of the "guarantees" of the Xen project.


The XML-RPC calls will be the fixed standard, but we're also going to need
bindings to that XML-RPC for Python (for xm), for C (for libvirt), and
possibly for other languages too. These will be a thin translation from the
host language's values and types onto the XML-RPC, so that they can be kept
stable so that third-party applications can rely upon them in the long
term. Cleverer facilities (such as libvirt) can then be built on top. These
bindings will be open-source, and committed as libraries to the Xen trees for
all to use.


The latest version of the API definition, version 0.4, is attached.  This is
an Open Preview Release, and we welcome any discussion about it and the issues
surrounding it. We would love to see use cases for this API, so that we can
check that it all makes sense, and welcome any feedback you might have.

Please join the xen-api mailing list if you are interested in this project.  I
will collate all the feedback from that list and push out new versions of the
document as and when.

In particular, please pay attention to Section 1.6, the to-do list.  All of
these changes will be rolled into the document in the next couple of days.

This document, and its source, are available at the Xen wiki page XenApi:

http://wiki.xensource.com/xenwiki/XenApi


This API is not yet fixed! The definition is still in flux, so please do not
expect it to be stable.  Please do comment though!


Many thanks,

Ewan.

[-- Attachment #2: xenapi.pdf --]
[-- Type: application/pdf, Size: 235853 bytes --]

[-- Attachment #3: Type: text/plain, Size: 138 bytes --]

_______________________________________________
Xen-devel mailing list
Xen-devel@lists.xensource.com
http://lists.xensource.com/xen-devel

Re: Xen Management API Draft, version 0.4

[Harry Butterworth]

On the first reading, the bit of the document that I was most interested
in was the introduction as I was trying to establish the scope of the
API.  But it's just a one liner.  I think there needs to be considerable
work up front to set the scene and describe the background, context and
scope for the API.

I'd like to see a survey of existing solutions to the problem and a
discussion of the pros and cons of each.

One of the questions to answer up front is whether the API is for
managing a xen instance on a single node or a cluster of xen instances
on multiple nodes.  A picture of the whole system under consideration
and where the API fits into that would help.

It's just as important to describe an example for the kind of
environment that's expected to surround the API as the API and the
implementation itself.

Some of the text you have written below to introduce the document could
go into the introduction of the document itself.

The other part of the document that I found useful was the picture of
the domain lifecycle because it's a high level description of one part
of the model for supporting the use-cases that I'm interested in.  And I
can evaluate it against the use-cases to see if the system is going to
be useful.

The rest of the document is a description of the implementation.  This
part of the document is essential but really ought to fall out trivially
once you understand the scope and the use cases and the model for
supporting the uses cases.

So I think it would be good if the document was structured with an
introduction.  A bit of background on existing stuff.  A set of use
cases that the API is going to address.  A set of use cases that are for
future consideration.  A set of use cases that are not going to be
addressed.  A description of the scope and context of the API and how it
is intended to fit into a system that can meet the use cases that are
going to be addressed.  A description of the system model that supports
the use cases which would include diagrams like the domain lifecycle
diagram and then a description of the API used to drive the system
model.

Agreeing on the set of use cases and the scope of the API first will
make the model and implementation much easier to define.

With use-cases I think it's best if as many people as possible pool all
their ideas and then the complete set is filtered.  Some will be
duplicates, out of scope or too far out.  Some of the use cases will be
high level but require some support from the low level API.  Here's as
many as I can think of right now:

User buys new box wants to install xen and a single service.
User has existing box already running a service and not xen.  Wants to
create a new service on same box using xen for isolation.
User has existing boxes already running services and wants to work out
the cost of consolidation onto (how many?) fewer boxes using xen.
User has existing boxes already running services wants to actually
perform consolidation onto fewer boxes using xen.
The user wants to know how many xen boxes will be required.
User has existing xen infrastructure and wants to deploy a new service.
User has existing xen infrastructure but load is skewed.  Wants to
rebalance load across boxes.
User has existing virtual infrastructure from another provider and wants
to incrementally replace it by deploying xen.
User has existing xen infrastructure but wants to remove xen and migrate
back to native operation.
User has existing xen infrastructure and wants to migrate to virtual
infrastructure from another provider.
User has existing xen infrastructure and wants to safely evaluate the
effect of a xen upgrade.
User has existing xen infrastructure and wants to safely evaluate the
effect of upgrades to a set of interrelated services.
User has existing xen infrastructure and the xen hypervisor crashes. The
user wants a) the system operational again ASAP b) to know the root
cause c) a fix and d) to test the fix safely before deploying it in
production.  The xen developers want first failure data capture
debugging information.
User has existing xen infrastructure and a VM crashes. The user wants a)
the system operational again ASAP b) to know the root cause c) a fix and
d) to test the fix safely before deploying it in production.  Someone
wants first failure data capture information to debug the VM.
User has existing xen infrastructure and the system is performing
poorly.  The user wants to debug the problem and fix it.
The user wants to check up on the xen infrastructure to satisfy
themselves that it is all running OK.
User has existing xen infrastructure and a box needs to be powered off
for servicing.  The user wants to service the machine without disrupting
the services running on it.
User has existing xen infrastructure and a physical machine fails
completely.  The user wants to reestablish system operation ASAP.
User has existing xen infrastructure and a data centre is taken out. The
user wants to reestablish system operation at a new site ASAP.
User has existing xen infrastructure in multiple sites and wants a
disaster recovery solution that will get them up again ASAP if any site
is lost.
There is confidential information in a virtual machine.  User wants to
do a secure delete.
User has a virtual machine and wants to package it for distribution to
other users.
User is provided with a virtual machine package and wants to deploy it.
User wants to deploy a very large number of generally idle virtual
machines and dynamically balance resources such that the machines that
are active have enough resources to make progress.
User wants to deploy a virtual machine for the duration of a job on any
physical machine from a pool.
Multiple users want to do some of these use cases using the same
physical hardware at the same time with some protection from each other.
VM service provider wants to track resource usage of a VM for accounting
purposes.
Client of VM service provider wants to dynamically adjust resource
allocation according to workload to minimise cost.
User wants to maintain an archive of VMs so as to be able to recreate
historical configurations.
User wants a backup of a consistent set of virtual machines.
User's security is breached and primary systems are compromised.
Perhaps compromise is replicated by disaster recovery solution to
secondary site.  User wants to roll back to before the attack and then
reapply transaction logs.  Perhaps there were some VM configuration
changes or migrations during the period of interest.
User wants to perform some of these use-cases directly at the physical
machine.
User wants to perform some of these uses cases from a remote machine.
User wants to write scripts to automate some of these uses cases.
User wants to integrate the xen infrastructure with existing
infrastructure.

Harry.

On Mon, 2006-07-03 at 16:53 +0100, Ewan Mellor wrote:
> Attached is version 0.4 of the Xen Management API Draft.  This document will
> eventually define a fixed XML-RPC protocol for remote and local management of
> Xen-based systems.  I would like to invite you to study, give feedback on, and
> collaborate around this document, so that we will soon have for the first time
> an open source toolstack that exports a supported management API for Xen.
> 
> This document presents our ideas in terms of a data model, with an implied
> binding to XML-RPC calls. These XML-RPC calls can then be used (over one of a
> number of transports) to manage a Xen-based system.
> 
> The intention is to standardise both the data model and XML-RPC calls (one
> implying the other) and then the Xen project will guarantee that that wire
> protocol would be supported for the long term.
> 
> Behind that interface, we would then be free to improve Xend, and at the same
> time we give a solid foundation for third-party tools (in particular
> libvirt-based applications), GUIs, and so on. The API becomes effectively part
> of the "guarantees" of the Xen project.
> 
> 
> The XML-RPC calls will be the fixed standard, but we're also going to need
> bindings to that XML-RPC for Python (for xm), for C (for libvirt), and
> possibly for other languages too. These will be a thin translation from the
> host language's values and types onto the XML-RPC, so that they can be kept
> stable so that third-party applications can rely upon them in the long
> term. Cleverer facilities (such as libvirt) can then be built on top. These
> bindings will be open-source, and committed as libraries to the Xen trees for
> all to use.
> 
> 
> The latest version of the API definition, version 0.4, is attached.  This is
> an Open Preview Release, and we welcome any discussion about it and the issues
> surrounding it. We would love to see use cases for this API, so that we can
> check that it all makes sense, and welcome any feedback you might have.
> 
> Please join the xen-api mailing list if you are interested in this project.  I
> will collate all the feedback from that list and push out new versions of the
> document as and when.
> 
> In particular, please pay attention to Section 1.6, the to-do list.  All of
> these changes will be rolled into the document in the next couple of days.
> 
> This document, and its source, are available at the Xen wiki page XenApi:
> 
> http://wiki.xensource.com/xenwiki/XenApi
> 
> 
> This API is not yet fixed! The definition is still in flux, so please do not
> expect it to be stable.  Please do comment though!
> 
> 
> Many thanks,
> 
> Ewan.
> _______________________________________________
> Xen-devel mailing list
> Xen-devel@lists.xensource.com
> http://lists.xensource.com/xen-devel

Re: Xen Management API Draft, version 0.4

[Harry Butterworth]

A site-wide emergency power outage happens during any of the use-cases.
The user wants the use-case to roll back to the start or proceed to
completion when power is restored.
User wants to run a text-only interactive application on a virtual
machine.
User wants to run a 2-D graphical interactive application on a virtual
machine.
User wants to run a 3-D graphical interactive application on a virtual
machine.
User wants to configure networking between virtual machines.
User wants to configure networking between virtual machines and the
outside world.
User wants to change storage provision allocated to a virtual machine.
User wants to connect a USB device to a virtual machine :-(
User wants to clone a virtual machine.
User wants to run synthesis on a cloned virtual machine (to make it
slightly different from the original) before connecting it to the
outside world.
User wants to replay virtual machine operation to analyse a security
breach or intermittent problem.
User wants to configure a fault-tolerant virtual machine for a high
availability application.
User wants to configure virtual machines to operate in lock-step to
evaluate whether a change to internal implementation has affected the
external interface (n-version programming).
User wants to single-step a consistent set of virtual machines in
virtual time to debug a cluster application.
User wants to restore a consistent set of virtual machines from a backup
(this one normally gets forgotten).
User wants to test an application designed for large SMP on cheaper
small SMP hardware.
User wants to repeatedly test an application against multiple versions
of a VM, resetting the VMs between each test run.

There must be lots of other use cases.  Yes, there's a bit of a gap
between the level of these use cases and the API proposal.  Which is why
it's important to have a sketch in the document about the software
that's going to be there to fill the gap, roughly how it's going to go
about doing it and how the low-level API operations are sequenced to
operate on the model to achieve these user-level use-cases.

People rarely comment on the notes I write.  I'm continually wondering
whether I'm managing to convey anything useful at all.

Harry.

Re: Xen Management API Draft, version 0.4

[Harry Butterworth]

I may be misreading the document but it seems to me like you've
constrained the class definition such that all of the construtor
parameters have accessor methods.

I think this may be a bit unnatural and I think any required accessor
methods for constructor parameters are just a special case of accessor
methods required in general and they in turn are just a special case of
general purpose methods like the ones required to drive the vm
lifecycle.

A bit of googling turned up this article on accessors which I tend to
agree with for the most part:

http://www.javaworld.com/javaworld/jw-09-2003/jw-0905-toolbox.html

Harry.

Re: Xen Management API Draft, version 0.4

[Ewan Mellor]

On Fri, Jul 07, 2006 at 02:16:45PM +0100, Harry Butterworth wrote:

> I may be misreading the document but it seems to me like you've
> constrained the class definition such that all of the construtor
> parameters have accessor methods.
> 
> I think this may be a bit unnatural and I think any required accessor
> methods for constructor parameters are just a special case of accessor
> methods required in general and they in turn are just a special case of
> general purpose methods like the ones required to drive the vm
> lifecycle.

You've lost me.  Could you give an example?

Ewan.

Re: Xen Management API Draft, version 0.4

[Ewan Mellor]

On Fri, Jul 07, 2006 at 01:18:37PM +0100, Harry Butterworth wrote:

> People rarely comment on the notes I write.  I'm continually wondering
> whether I'm managing to convey anything useful at all.

Not at all, Harry -- your comments are useful, and welcome.  The use cases in
particular are something that we need to get into the document, and I'm very
happy to see such a comprehensive list.

I agree totally that the introduction isn't rich enough to convey the whole
context of where this API fits in the grand scheme of things, and I agree that
it should.  It's just taking some time to get it down on paper, but don't
worry, your comments are certainly being taken on board.

Ewan.

Re: Xen Management API Draft, version 0.4

[Harry Butterworth]

> > I think this may be a bit unnatural and I think any required accessor
> > methods for constructor parameters are just a special case of accessor
> > methods required in general and they in turn are just a special case of
> > general purpose methods like the ones required to drive the vm
> > lifecycle.
> 
> You've lost me.  Could you give an example?

>From my understanding of your doc:

Class X has property Y implies constructor for class X takes parameter Y
and class X automatically gets at a get_Y method (and a set_Y method if
Y is RW).

But, what if the dynamic model for X has two states (say) where get_Y is
a valid operation in state A but not in state B.

An alternative way of saying this is that accessor methods are identity
state transitions on the dynamic model which happen to either pass or
return a single value and should be expressed in the same way that the
methods for the other state transitions are expressed.

i.e. little circular arrows that point back to the same state on the
dynamic model.  The key point is that they aren't necessarily valid in
all states of the dynamic model.

So, I think that the bit in the document about an object having a list
of fields is unnecessary and breaks encapsulation as explained in the
googled reference I gave.

You need to use the use cases to get the dynamic model for the objects
right and then work out whether any accessor methods are required at all
and if so, which states of the dynamic model they are required in.

Harry.

Re: Xen Management API Draft, version 0.4

[Ewan Mellor]

On Fri, Jul 07, 2006 at 02:49:10PM +0100, Harry Butterworth wrote:

> > > I think this may be a bit unnatural and I think any required accessor
> > > methods for constructor parameters are just a special case of accessor
> > > methods required in general and they in turn are just a special case of
> > > general purpose methods like the ones required to drive the vm
> > > lifecycle.
> > 
> > You've lost me.  Could you give an example?
> 
> >From my understanding of your doc:
> 
> Class X has property Y implies constructor for class X takes parameter Y
> and class X automatically gets at a get_Y method (and a set_Y method if
> Y is RW).
> 
> But, what if the dynamic model for X has two states (say) where get_Y is
> a valid operation in state A but not in state B.
> 
> An alternative way of saying this is that accessor methods are identity
> state transitions on the dynamic model which happen to either pass or
> return a single value and should be expressed in the same way that the
> methods for the other state transitions are expressed.
> 
> i.e. little circular arrows that point back to the same state on the
> dynamic model.  The key point is that they aren't necessarily valid in
> all states of the dynamic model.
> 
> So, I think that the bit in the document about an object having a list
> of fields is unnecessary and breaks encapsulation as explained in the
> googled reference I gave.
> 
> You need to use the use cases to get the dynamic model for the objects
> right and then work out whether any accessor methods are required at all
> and if so, which states of the dynamic model they are required in.

I happen to agree very much with the document that you have cited, and I have
been writing Java and C++ code without getters and setters for many years.

That said, I don't think that that approach is suitable here.  Every one of
these use cases that we are using to drive the dynamic model has the
additional caveat that the system must be permanently monitorable.  In other
words, this API isn't just for _doing_ things, it's for watching what's going
on, too.  This means that you need access to every field that we've exposed,
all the time.

Furthermore, this approach implies that it's possible to enumerate all your
use cases.  This is all very well within a program, when you can add a new
method to an object when it becomes necessary, but this API doesn't have that
luxury -- it must be possible to support arbitrary and unanticipated use cases
without coming back and forcing additional methods upon the API.  This means
that all the fields must be available directly and through the API.

Cheers,

Ewan.

Re: Xen Management API Draft, version 0.4

[Harry Butterworth]

On Fri, 2006-07-07 at 14:22 +0100, Ewan Mellor wrote:
> I'm very happy to see such a comprehensive list.
 
I doubt that that list was anywhere close to being comprehensive.  I
think you need a lot more input from people who are actually using or
who want to use Xen.  There's likely to be a whole load of stuff to do
with fitting into existing infrastructure which will have a collection
of small impacts on the API.

> 
> I agree totally that the introduction isn't rich enough to convey the whole
> context of where this API fits in the grand scheme of things, and I agree that
> it should.  It's just taking some time to get it down on paper, but don't
> worry, your comments are certainly being taken on board.

You shouldn't see this as a one-off effort.  You should look at it more
as a component of a process for maintaining the integrity of the
architecture over a period of time.

So, for example, the initial list of use-cases can be those supported
today, and the API can be today's API and the dynamic model can be
today's dynamic model.

Then additional use cases can be added incrementally and the dynamic
model adjusted and the API changed (with versioning) appropriately.

Harry.

Re: Xen Management API Draft, version 0.4

[Harry Butterworth]

On Fri, 2006-07-07 at 15:31 +0100, Ewan Mellor wrote:

> That said, I don't think that that approach is suitable here.  Every one of
> these use cases that we are using to drive the dynamic model has the
> additional caveat that the system must be permanently monitorable.  In other
> words, this API isn't just for _doing_ things, it's for watching what's going
> on, too.  This means that you need access to every field that we've exposed,
> all the time.

No.  I absolutely disagree.  Monitoring the system is just another
use-case and you need to consider what needs to be monitored and how it
is exposed and this should be a stable, versioned part of the API that
status reporting tools can depend on.

In general, it simply doesn't make sense to monitor some things in some
states and the API should reflect that.

Debugging the system is something else and should have a separate
interface that gives you arbitrary access (but isn't versioned or
guaranteed stable).

> 
> Furthermore, this approach implies that it's possible to enumerate all your
> use cases.  This is all very well within a program, when you can add a new
> method to an object when it becomes necessary, but this API doesn't have that
> luxury -- it must be possible to support arbitrary and unanticipated use cases
> without coming back and forcing additional methods upon the API.  This means
> that all the fields must be available directly and through the API.

Again, I disagree.

You aren't going to get it right first time whatever you do.  Exposing
everything R/O isn't going to help that, it's just going to make it
harder to maintain backwards compatibility when you want to change
something.

Exposing unnecessary stuff R/W is even more dangerous because it allows
your clients to break your dynamic model.  Which is going to make it
impossible to support the system.

If you want to be able to support Xen, the dynamic model should be such
that it is impossible for your clients to break you.  If that means that
it is impossible to support a use case with the API and it's necessary
to add a feature to the API and do another version.  That's fine because
you can do it in a controlled supportable way.

The alternative is that to support unforseen use-cases all the different
proprietary management tools start messing with your bits in ill defined
undocumented ways that you don't know about and when you want to add a
new feature to Xen you can't change anything for fear of breaking the
world.

Having said this, it might be that you've already thought quite
carefully about what you want to expose and monitor and your current API
may be quite well thought out anyway.  I'm just arguing the principle of
exposing everything by default.  I'm not arguing in the context of how
that has actually fallen out in the specific cases you have documented.

Harry.

Re: Xen Management API Draft, version 0.4

[Harry Butterworth]

Besides, if you get good coverage in the use-cases you consider to start
off with then you'll end up with a good dynamic model that implements a
set of primitive operations that are useful and flexible which it will
be possible to recombine to implement a substantial proportion of
unforseen use-cases without having to make any API changes.