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
Harry Butterworth
2006-Jul-04 11:55 UTC
Re: [Xen-devel] Xen Management API Draft, version 0.4
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_______________________________________________ Xen-devel mailing list Xen-devel@lists.xensource.com http://lists.xensource.com/xen-devel
Harry Butterworth
2006-Jul-07 12:18 UTC
Re: [Xen-devel] Xen Management API Draft, version 0.4
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. _______________________________________________ Xen-devel mailing list Xen-devel@lists.xensource.com http://lists.xensource.com/xen-devel
Harry Butterworth
2006-Jul-07 13:16 UTC
Re: [Xen-devel] Xen Management API Draft, version 0.4
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. _______________________________________________ Xen-devel mailing list Xen-devel@lists.xensource.com http://lists.xensource.com/xen-devel
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. _______________________________________________ Xen-devel mailing list Xen-devel@lists.xensource.com http://lists.xensource.com/xen-devel
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. _______________________________________________ Xen-devel mailing list Xen-devel@lists.xensource.com http://lists.xensource.com/xen-devel
Harry Butterworth
2006-Jul-07 13:49 UTC
Re: [Xen-devel] Xen Management API Draft, version 0.4
> > 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. _______________________________________________ Xen-devel mailing list Xen-devel@lists.xensource.com http://lists.xensource.com/xen-devel
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. _______________________________________________ Xen-devel mailing list Xen-devel@lists.xensource.com http://lists.xensource.com/xen-devel
Harry Butterworth
2006-Jul-07 14:32 UTC
Re: [Xen-devel] Xen Management API Draft, version 0.4
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. _______________________________________________ Xen-devel mailing list Xen-devel@lists.xensource.com http://lists.xensource.com/xen-devel
Harry Butterworth
2006-Jul-07 14:57 UTC
Re: [Xen-devel] Xen Management API Draft, version 0.4
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. _______________________________________________ Xen-devel mailing list Xen-devel@lists.xensource.com http://lists.xensource.com/xen-devel
Harry Butterworth
2006-Jul-07 15:10 UTC
Re: [Xen-devel] Xen Management API Draft, version 0.4
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. _______________________________________________ Xen-devel mailing list Xen-devel@lists.xensource.com http://lists.xensource.com/xen-devel