Provide a simplified API that implements reasonable default policies for creating highly optimized KVM guests.
The API is targeted toward third party tool makers who need to integrate with virtualization but are not trying to build advanced virtualization management tools.
1. Virtual hardware should be transparent to the API consumer. Library users shouldn't have to worry about the use of virtio vs. e1000.
2. An minimal barrier to entry for creating a new guest. It should be possible to create a guest without filling in a lot of boiler plate information.
3. High level functionality should be exposed in a simple fashion--the interface to pause a VM should be just as simple as the interface to copy a file into a guest.
4. Configuration file should be extensible with user specified data.
These are not meant to be exhaustive but rather to provide examples of interesting API entry points.
virSimplePtr virSimpleCreate(virConnectionPtr ptr, const char *filename);
Where file contains:
<?xml verison="1.0"?> <guest xmlns:virtman="http://virt-manager.org/ns"> <name>Foo</name> <memory>128</memory> <vcpus>2</vcpus> <os>Windows</os> <virtman:icon>virtman-stock-winxp</virtman:icon> <disk id="vda">/home/anthony/foo.img</disk> <nic id="eth0" mac="52:10:00:02:32:43"/> <nic id="eth1" mac="52:10:00:02:32:44"/> </guest>
name="Foo" memory=128 vcpus=2 os="Windows" virtman:icon=virtman-stock-winxp disk.vda=/home/anthony/foo.img nic.eth0.mac=52:10:00:02:32:43 nic.eth1.mac=52:10:00:02:32:44
Both formats are shown but the suggestion isn't to support both. The point is that it should be easy to author a good guest's configuration file. One important point is that there isn't any explicit host network configuration.
The default should be to use bridging to the public network. Other network configuration modes could be exposed via a 'type' modifier. For example type="guest-vlan" would attach the nic to a private vlan to connect the guests.
// Returns true if guest is using guest addons, false otherwise bool virSimpleIsGuestAddonsPresent(virSimplePtr guest); // Either fail or return when virSimpleIsGuestAddonsPresent() would return true void virSimpleInstallGuestAddons(virSimplePtr guest);
Managing guest tools is one of the more complicated parts of KVM management today. We ought to provide a standard guest tool package and provide standard APIs to install said package.
A common problem in the field is figuring out whether a VM is "optimal" or not when a performance problem is reported. The idea is that virSimpleIsGuestAddonsPresent() becomes a short hand for checking whether the VM is optimally configured.
// Return true when disk is present and usable in guest--not when hotplug // succeeds. void virSimpleAddDisk(virSimplePtr guest, const char *id, const char *filename);
This isn't all that different from current APIs. The main difference is the lack of XML descriptions. To make this API work very well actually requires a guest agent that can verify that acpiphp is loaded and that the hot plug was successful.
Interacting with the Guest
// File transfer to and from guest void virSimpleCopyFileToGuest(virSimplePtr guest, const char *src, const char *dst); void virSimpleCopyFileFromGuest(virSimplePtr guest, const char *src, const char *dst);
This API demonstrates very high level functionality. It requires the guest addons.
// Simple resource allocation APIs void virSimpleSetCpuGuarantee(virSimplePtr guest, int cpu, double percentage); void virSimpleSetCpuEntitlement(virSimplePtr guest, int cpu, double percentage); void virSimpleSetNetworkGuarantee(virSimplePtr guest, const char *id, double percentage); void virSimpleSetNetworkEntitlement(virSimplePtr guest, const char *id, double percentage);
This is not a critical base API but the purpose is to illustrate that we ought to treat guest resources in terms that users will expect. Network rate limiting can be done in a ton of different ways with tremendous flexibility. The scope of this API though is to provide a simple interface that covers the most common case.
Ability to sample CPU time, memory usage, disk I/O, and network I/O for a VM and for the host globally. This can be used both by graphical tools as well as performance monitoring and capacity planning.
Shutdown / Restart / Suspend
// Simple shutdown-related APIs void virSimpleShutdown(virSimplePtr guest, int mode); // Possible values for MODE // SHUTDOWN_OS - OS initiated shutdown (eg. shutdown -h now) // SHUTDOWN_ACPI - ACPI power button press // SHUTDOWN_FORCE - virsh destroy void virSimpleReboot(virSimplePtr guest, int mode); // Possible values for MODE // REBOOT_OS - OS initiated reboot (eg. shutdown -r now) void virSimpleSuspend(virSimplePtr guest, int mode); // Possible values for MODE // SUSPEND_TO_RAM - Cause guest to enter ACPI S3 sleep state // SUSPEND_TO_DISK - Cause guest to suspend to disk and power off void virSimpleWakeFromSuspend(virSimplePtr guest);
Lifecycle and error events can be retrieved for auditing and diagnostic purposes. The includes:
- VM start, stop, pause, resume.
- Hardware hotplug and memory ballooning.
- VNC and console access.
- Fatal errors.