1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
|
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
<HTML>
<HEAD>
<META HTTP-EQUIV="CONTENT-TYPE" CONTENT="text/html; charset=utf-8">
<TITLE>ConVirt v1.1 : Plugin Development Guide</TITLE>
<META NAME="GENERATOR" CONTENT="OpenOffice.org 2.2 (Linux)">
<META NAME="CREATED" CONTENT="20070104;16493900">
<META NAME="CHANGEDBY" CONTENT="jd">
<META NAME="CHANGED" CONTENT="20080619;22581800">
<STYLE TYPE="text/css">
<!--
@page { size: 8.5in 11in }
TD P { color: #000000 }
H1 { color: #000000 }
P { color: #000000 }
H2 { color: #000000 }
H3 { color: #000000 }
TH P { color: #000000 }
-->
</STYLE>
</HEAD>
<BODY LANG="en-US" TEXT="#000000" DIR="LTR">
<H1 ALIGN=CENTER>Plugin Development Guide</H1>
<P ALIGN=CENTER>Copyright 2009, Convirture Corp</P>
<P ALIGN=CENTER>v1.1</P>
<H2><BR><BR>
</H2>
<P STYLE="margin-bottom: 0in; page-break-before: always"><FONT SIZE=4>Table
of Contents</FONT></P>
<P STYLE="margin-bottom: 0in"><BR>
</P>
<P STYLE="margin-bottom: 0in"> Introduction</P>
<P STYLE="margin-bottom: 0in"><BR>
</P>
<P STYLE="margin-left: 0.2in; margin-bottom: 0in">Philosophy</P>
<P STYLE="margin-left: 0.2in; margin-bottom: 0in"><BR>
</P>
<P STYLE="margin-left: 0.2in; margin-bottom: 0in">ConVirt Overview
</P>
<P STYLE="margin-left: 0.39in; margin-bottom: 0in">Packages</P>
<P STYLE="margin-left: 0.39in; margin-bottom: 0in">Model
</P>
<P STYLE="margin-left: 0.39in; margin-bottom: 0in">Overall Flow and
UI
</P>
<P STYLE="margin-left: 0.39in; margin-bottom: 0in"><BR>
</P>
<P STYLE="margin-left: 0.2in; margin-bottom: 0in">Plugin Development</P>
<P STYLE="margin-left: 0.39in; margin-bottom: 0in">Platform Specific
Core Model</P>
<P STYLE="margin-left: 0.39in; margin-bottom: 0in">Platform specific
UI Helpers
</P>
<P STYLE="margin-left: 0.39in; margin-bottom: 0in">Integration
</P>
<P STYLE="margin-left: 0.39in; margin-bottom: 0in">Platform specific
Images
</P>
<P STYLE="margin-left: 0.39in; margin-bottom: 0in">Packaging
</P>
<P STYLE="margin-left: 0.39in; margin-bottom: 0in">Feedback
</P>
<P STYLE="margin-left: 0.39in; margin-bottom: 0in"><BR>
</P>
<P STYLE="margin-left: 0.2in; margin-bottom: 0in">FAQ</P>
<P><BR><BR>
</P>
<P><A NAME="mozTocId96936"></A>Introduction</P>
<P>ConVirt team is pleased to announce the availability of Platform
Plugin Development guide with this release. This allows developers to
add a plugin for a specific virtualization platform. Once the plugin
is deployed, ConVirt users can use the same user interface and
features for the new platform. This document describes architecture
of ConVirt followed by details on developing such a plugin. The Xen and KVM
plugin implementation provides as a good reference.</P>
<H2>Philosophy</H2>
<P>The over all philosophy for the project is to allow for platform
specific configuration while maintaining reasonable standardization
to provide a unified view of VM life cycle management.</P>
<H2>ConVirt Overview
</H2>
<P>For developing a plugin, it is necessary to have a good
understanding of ConVirt model and some inner-workings. This section
provides necessary details to achieve it.</P>
<H3>Packages</H3>
<P>The following table outlines some of the packages in ConVirt.</P>
<DL>
<DD>
<TABLE WIDTH=663 BORDER=1 CELLPADDING=4 CELLSPACING=3>
<COL WIDTH=138>
<COL WIDTH=498>
<TR VALIGN=TOP>
<TH WIDTH=138>
<P>Package</P>
</TH>
<TH WIDTH=498>
<P>Description</P>
</TH>
</TR>
<TR VALIGN=TOP>
<TD WIDTH=138>
<P>core/model</P>
</TD>
<TD WIDTH=498>
<P>All core classes representing model. For example, VM
representing a Virtual Machine, ManagedNode and VNode
representing managed server and managed virtualized server
respectively etc. This package also contains GridManager,
ImageStore, ApplianceStore etc.</P>
</TD>
</TR>
<TR VALIGN=TOP>
<TD WIDTH=138>
<P>core/appliances</P>
</TD>
<TD WIDTH=498>
<P>Contains model for representing appliance catalog, and classes
needed for transforming an appliance in to a ConVirt image. It
also contains sub packages for appliance vendor integration.</P>
</TD>
</TR>
<TR VALIGN=TOP>
<TD WIDTH=138>
<P>core/utils</P>
</TD>
<TD WIDTH=498>
<P>Contains utility classes and constants. Notably NodeProxy and
Paramiko helper for doing remote operations via ssh.</P>
</TD>
</TR>
<TR VALIGN=TOP>
<TD WIDTH=138>
<P>core/repos</P>
</TD>
<TD WIDTH=498>
<P>Reserved for having ConVirt repository related details</P>
</TD>
</TR>
<TR VALIGN=TOP>
<TD WIDTH=138>
<P>core/platforms</P>
</TD>
<TD WIDTH=498>
<P>Platform specific model implementation.</P>
</TD>
</TR>
<TR VALIGN=TOP>
<TD WIDTH=138>
<P>client/</P>
</TD>
<TD WIDTH=498>
<P>The client package contains the code for GTK base ConVirt
client, utilities, glade files, as well as platform specific
classes for UI.</P>
</TD>
</TR>
<TR VALIGN=TOP>
<TD WIDTH=138>
<P>server/</P>
</TD>
<TD WIDTH=498>
<P>Reserved for ConVirt server</P>
</TD>
</TR>
<TR VALIGN=TOP>
<TD WIDTH=138>
<P>web/</P>
</TD>
<TD WIDTH=498>
<P>Reserved for ConVirt web application</P>
</TD>
</TR>
<TR VALIGN=TOP>
<TD WIDTH=138>
<P>cli/</P>
</TD>
<TD WIDTH=498>
<P>Reserved for CLI</P>
</TD>
</TR>
</TABLE>
</DL>
<P><BR><BR>
</P>
<H3>Model
</H3>
<P STYLE="font-weight: medium">This section describes important
entities and their relationships. Here is a UML diagram for the core
components.</P>
<P><IMG SRC="ConVirtUML.png" NAME="graphics1" ALIGN=LEFT WIDTH=686 HEIGHT=439 BORDER=0><BR CLEAR=LEFT><BR><BR>
</P>
<P STYLE="font-weight: medium">GridManager : Manages Groups (Server
groups) and Managed Nodes (Servers).</P>
<P STYLE="font-weight: medium">Managed Node : A server being managed.
</P>
<P STYLE="font-weight: medium">VNode : Virtualized Node, a node with
Virtualized Platform / VMM running on it.</P>
<P STYLE="font-weight: medium">VMM : The Virtual Machine manager. It
implements all interactions with the VMM for a specific platform.</P>
<P STYLE="font-weight: medium">VM : A Virtual Machine. A VM contains
runtime information (VMInfo) and the configuration information
(VMConfig).
</P>
<P STYLE="font-weight: medium">ImageStore : Manages image groups and
images.</P>
<P STYLE="font-weight: medium">ApplianceStore : Catalog of appliances
provided by Appliance Vendors like rPath and JumpBox.</P>
<P STYLE="font-weight: medium">PlatformRegistry : Configuration
information about available virtualization platforms.</P>
<P STYLE="font-weight: medium">Platform : Main Integration point for
a platform plugin. Provides platform specific factories and related
information about a plugin implementation.</P>
<P STYLE="font-weight: medium">PlatformUIHelper : Interface to be
implemented by a platform plugin to customize the UI specific to the
platform.</P>
<P STYLE="font-weight: medium">VMSettings : UI for editing images,
VMConfigs as well as provisioning UI. Plugin developers can customize
this for their platforms.
</P>
<P STYLE="font-weight: medium">VMInfoHelper : A helper class that
implements display of VM information in ConVirt UI.</P>
<H3>Overall Flow and UI
</H3>
<P>This section describes program flow for initialization and few
other important user work flows.</P>
<P><B>Initialization :</B> On startup ConVirt initializes UI
artifacts and important model items. The GridManager initialization
loads the list of Server Pools and Servers while the Image Store
initialization reads the image groups and images within them. The
GridManager uses the Platform specific NodeFactory to create VNodes.
The left navigation tree in ConVirt UI gets populated with the
information from the GridManager and the Image Store. The Summary tab
of the Notebook also gets initialized depending on the selection.
ConVirt refreshes the Summary information with current CPU and memory
information periodically.</P>
<P><B>Provisioning : </B>The provisioning operation opens up the
Settings Dialog (VMSettings or derived class) and allows the user to
customize the image information. It then sets up the environment and
kicks of the provisioning script.</P>
<P><B>Edit VM Settings : </B>It reads in the VM configuration and
allows the user to change it. If the VM is running, the user can also
make changes to it. For example, memory allocated to a running VM can
be changed.</P>
<P><B>Edit Image : </B>It reads in the image configuration as well as
VM configuration template and allows the user to customize it.
</P>
<P><B>Appliance Import : </B>The Appliance import begins with
presenting appliance catalog using ApplianceList. On selection, The
Appliance Import dialog shown and then the import is kicked off. The
import operation typically opens the appliance package, create
necessary VM template and image config files. The selection of
templates (meta-template) is done in a platform specific fashion.
</P>
<P><B>VM Lifecycle Ops : </B>The VM operations are initiated using
menu or button bar and the implementation in the VM/VMM gets invoked.
The VNode acts as a factory to create VMs of specific platform type.
While the VM acts as a Factory to create VMConfig and VMInfo in a
similar fashion.</P>
<P STYLE="page-break-before: always"><BR><BR>
</P>
<H2>Plugin Development</H2>
<P>Armed with this background, lets see what is involved in
developing the actual plugin. ConVirt has a registry mechanism to get
required integration points from the plugin. The Platform and
PlatformUIHelper are the two interfaces which needs to be implemented
by the plugin developer. The Platform interface helps tie in the
platform specific core model, while the PlatformUIHelper helps with
UI integration points.</P>
<P>Overall the following steps needs to be taken. In the following
sections each one of these are addressed in detail.</P>
<UL>
<LI><P>Develop Platform specific model classes</P>
<LI><P>Develop Platform specific UI classes</P>
<LI><P>Specify Integration files</P>
<LI><P>Platform specific images</P>
<LI><P>Packaging</P>
</UL>
<H3>Platform Specific Core Model</H3>
<UL>
<LI><P>Implement platform specific VMM derived class. This is
responsible for communicating with the actual VMM for the platform.
In case of Xen the XenVMM class communicates with the Xen VMM using
the xml-rpc API.</P>
<LI><P>Implement the VMInfo that encapsulates the required runtime
VM information using dynamic_map. VMM would return instances of
these when the runtime information is requested by the client.
XenInfo is implemented in XenVMM.py which takes care of giving map
like interface to the information received in sxp format.
</P>
<LI><P>Implement platform specific VMConfig class. This would
represent the configuration for the VM. It is recommended to use the
VMConfig derived class for ease of use. If the platform requires
specific config format, override the read and write methods for
custom read/write. It is required that the VMConfig allows the
configuration parameters to be accessed similar to a map. In case of
Xen the XenConfig implementation takes care of this.</P>
<LI><P>Implement the platform specific VM class. Typically contains
references to the platform config and platform's runtime VM
information and keeps track of the state.</P>
<LI><P>Implement the VNode : Implement a platform specific VNode
class. This typically handles creating platform specific VMM. Apart
from this is also responsible for implementing platform specific
migration checks, and returning a snapshot of all VMs. The XenNode
class implements all these for the Xen platform.</P>
<LI><P>Implement the VNodeFactory that implements creating instance
of platform specific VNode and other methods to read and write node
information to the repository. This allows ConVirt to create correct
type of platform node.</P>
<LI><P>Implement the Platform class. This class would be used by
ConVirt to interact with model specific classes mentioned in the
previous steps. In addition, the platform detection code and
prerequisites checks needs to be implemented. Check the XenPlatform
class for the Xen platform.</P>
</UL>
<H3>Platform specific UI Helpers
</H3>
<P>This section specifies steps to implement various UI artifacts
that are required to be implemented by a platform plugin.</P>
<UL>
<LI><P>Implement the UI helper class for the platform. This would
require some of the following classes to be implemented.</P>
<LI><P>Implement AddNode dialog for the platform. This should return
an instance of platform specific node. And allow an existing node to
be edited.</P>
</UL>
<UL>
<LI><P>Use the VMSettings dialog as the settings dialog for the
platform. As a second pass, you might want to customize the
VMSettings. <SPAN STYLE="font-weight: medium"><BR><BR>The VMSettings
dialog is used for different operations based on mode. <BR>- Editing
VM config (mode = EDIT_VM_CONFIG)<BR>- Editing runtime VMInfo (mode
= EDIT_VM_INFO)<BR>- Editing an Image (mode = EDIT_IMAGE)<BR>-
Provisioning an Image (mode = PROVISION_IMAGE)<BR><BR>The VMSettings
dialog follows a pattern of<BR><BR>* get context from the caller<BR>*
initialize widgets based on mode <BR>* scatter information from the
context to the UI element <BR>* let the user make changes <BR>*
validate information from UI elements <BR>* gather information from
UI elements <BR>* perform operation (saving/provisioning) on the
gathered information.<BR><BR>You can extend the dialog for
customizing the UI. XenSettings dialog is implemented, that adds the
bootloader, ramdisk and kernel parameters to the VMSettings dialog.</SPAN></P>
</UL>
<H3>Integration
</H3>
<P>This section specifies the steps to populate proper registry
entries for ConVirt to find the plugin information.</P>
<UL>
<LI><P>Specify the registry file for the platform at the following
location.<BR>ConVirt<FONT FACE="monospace">/core/platforms/<platform>/registry.</FONT></P>
<LI><P><FONT FACE="Liberation Serif, serif">Update the master
platform registry to include the platform. This is located at
ConVirt<FONT FACE="monospace">/core/platforms/registry</FONT></FONT></P>
</UL>
<H3>Platform specific Images
</H3>
<P>This section describes steps to add a new platform specific image
to the image store.</P>
<UL>
<LI><P>Under the image store create a directory containing image.
Typically consisting of</P>
<LI><P>a template for the VM configuration</P>
<LI><P>image.conf which takes care of providing additional context
for the provisioning script</P>
<LI><P>the provisioning script</P>
<LI><P>any additional data / disks that are required for the
provisioning operation.</P>
</UL>
<P STYLE="margin-left: 0.79in">You may customize or write your own
provisioning script. ConVirt would invoke the script by giving it the
vm_config and image_config context at the time of provisioning.</P>
<UL>
<LI><P>Use the add_image.py utility in the CLI area to add register
the image with the image store.<BR><FONT FACE="monospace">$
src/convirt/cli/add_image.py <image_name> <platform>
<image_group></FONT></P>
<LI><P><FONT FACE="Liberation Serif, serif">You may also want to
specify the platform specific meta-templates under the
<FONT FACE="monospaced">src/ConVirt/</FONT><FONT FACE="monospace">appliance/<</FONT><FONT FACE="monospaced">platform>/</FONT>.
These would be used when an appliance of for this platform is being
imported using catalog or location specified manually.</FONT></P>
</UL>
<H3>Packaging
</H3>
<P>For now simply provide the plugin as a tar ball which would
overlay existing ConVirt installation. Include a readme and other
documents too.</P>
<H3>Feedback
</H3>
<P STYLE="font-weight: medium">Drop us an email to our mailing list
or write post details on our forums at www.convirt.net.
</P>
<P><BR><BR>
</P>
<P STYLE="page-break-before: always"><BR><BR>
</P>
<H2>FAQ</H2>
<P>This section has few related FAQ entries.</P>
<P>-- <B>How does ConVirt and Platform plugin work together ?</B></P>
<P STYLE="font-weight: medium">All the context required by the
ConVirt is provided via the the platform registry. The platform
registry allows the plugin developer to specify implementations
required. In particular, implementations for Platform interface and
PlatformUIHelper interfaces are expected.
</P>
<P STYLE="font-weight: medium"><I>Refer to : registry, Platform,
PlatformUIHelper</I></P>
<P>-- <B>How does ConVirt create appropriate VNode instance
corresponding to the platform ?</B></P>
<P STYLE="font-weight: medium">The integration class implements the
get_factory method that returns the appropriate factory class for
creating VNode instances. The plugin developer also need to implement
a dialog to add/edit node for its particular platform. Each node when
persisted saves the platform along with it.</P>
<P STYLE="font-weight: medium"><I>Refer to : VNode, VNodeFactory,
XenNode, XenNodeFactory</I></P>
<P>-- <B>How to get list of VMs managed by VMM on a particular Server
(node). ?</B></P>
<P STYLE="font-weight: medium">The Platform Node is expected to
return a list of managed VMs on the node. The VNode class implements
most of these functionality with some assumptions. It assumes that VM
configuration files would be present in some specific directory and
the VMM class would return the list of running VMs. If a specific
platform has different way of managing list of VM configuration,
implement the get_dom_list method for the VNode. Note : The VNode
acts as a factory for the platform specific VM instance.</P>
<P STYLE="font-weight: medium"><I>Refer to : VNode, XenNode</I></P>
<P>-- <B>How to get stats for all VMs running on a Server ?</B></P>
<P STYLE="font-weight: medium">The platform specific VNode is also
responsible for getting a snapshot of state and stats (cpu, memory,
disk i/o, network i/o) for all VMs. This is done by implementing the
get_metric_snapshot method. The base class provides polling and
caching facilities.</P>
<P STYLE="font-weight: medium"><I>Refer to : XenNode</I></P>
<P>-- <B>How to do VM ops, i.e. Start/Stop/Pause/Save/Restore/Connect
to Console etc. ?</B></P>
<P STYLE="font-weight: medium">These VM operations are delegated to
the VMM class. See XenVMM for more information. For getting to the
console of a running VM, is_graphical, get_vnc_port and
get_console_cmd methods need to be implemented by the VM class. The
is_graphical method returns true, if the VM's console is graphical
and can be reached via vnc. The get_console_cmd is invoked to get the
command line. This command line is used to get to the console of the
VM shown in the Terminal.
</P>
<P STYLE="font-weight: medium"><I>Refer to : VM, VMM, XenDomain,
XenVMM</I></P>
<P><BR><BR>
</P>
<P>-- <B>How is configuration for a particular VM is stored. ?</B></P>
<P STYLE="font-weight: medium">The base VMConfig class represents the
configuration in the python config format. For complex configuration,
one can derive a specific class from VMConfig and overwrite the read
and write method. It is required to keep the map like access to the
various elements of the configuration.
</P>
<P STYLE="font-weight: medium"><I>Refer to : PyConfig, VMConfig,
DomListHelper, XenConfig</I></P>
<P>-- <B>How should the VMInfo information be presented in the UI ?</B></P>
<P STYLE="font-weight: medium">ConVirt gives flexibility for a plugin
to control how VM information is displayed. This is done via
customizing the VMInfoHelper class.</P>
<P STYLE="font-weight: medium"><I>Refer to : VMInfoHelper,
XenInfoHelper</I></P>
<P>-- <B>How should I display Platform specific information about a
Server/Node ?</B></P>
<P STYLE="font-weight: medium">The platform specific VNode can
implement the get_platform_info method to return the platform
specific information. This would be displayed in a separate category
with Server information.
</P>
<P STYLE="font-weight: medium"><I>Refer to : VMNode, XenNode</I></P>
<P><BR><BR>
</P>
</BODY>
</HTML>
|
