Signed-off-by: Peter Krempa <pkrempa@xxxxxxxxxx> --- docs/goals.html.in | 64 ---------------------------------------------- docs/goals.rst | 56 ++++++++++++++++++++++++++++++++++++++++ docs/meson.build | 2 +- 3 files changed, 57 insertions(+), 65 deletions(-) delete mode 100644 docs/goals.html.in create mode 100644 docs/goals.rst diff --git a/docs/goals.html.in b/docs/goals.html.in deleted file mode 100644 index f1639338ad..0000000000 --- a/docs/goals.html.in +++ /dev/null @@ -1,64 +0,0 @@ -<?xml version="1.0" encoding="UTF-8"?> -<!DOCTYPE html> -<html xmlns="http://www.w3.org/1999/xhtml";> - <body> - <h1>Terminology and goals</h1> - <p>To avoid ambiguity about the terms used, here are the definitions - for some of the specific concepts used in libvirt documentation:</p> - <ul> - <li>a <strong>node</strong> is a single physical machine</li> - <li>an <strong>hypervisor</strong> is a layer of software allowing to - virtualize a node in a set of virtual machines with possibly different - configurations than the node itself</li> - <li>a <strong>domain</strong> is an instance of an operating system - (or subsystem in the case of container virtualization) running on a - virtualized machine provided by the hypervisor</li> - </ul> - <p>Now we can define the goal of libvirt: <b> to provide a common and - stable layer sufficient to securely manage domains on a node, possibly - remote</b>.</p> - <p> As a result, libvirt should provide all APIs needed to do the - management, such as: provision, create, modify, monitor, control, migrate - and stop the domains - within the limits of the support of the hypervisor - for those operations. - Not all hypervisors provide the same operations; but if an operation is - useful for domain management of even one specific hypervisor it is worth - providing in libvirt. - Multiple nodes - may be accessed with libvirt simultaneously, but the APIs are limited to - single node operations. Node resource operations which are needed - for the management and provisioning of domains are also in the scope of - the libvirt API, such as interface setup, firewall rules, storage management - and general provisioning APIs. Libvirt will also provide the state - monitoring APIs needed to implement management policies, obviously - checking domain state but also exposing local node resource consumption. - </p> - <p>This implies the following sub-goals:</p> - <ul> - <li>All API can be carried remotely though secure APIs</li> - <li>While most API will be generic in term of hypervisor or Host OS, - some API may be targeted to a single virtualization environment - as long as the semantic for the operations from a domain management - perspective is clear</li> - <li>the API should allow to do efficiently and cleanly all the operations - needed to manage domains on a node, including resource provisioning and - setup</li> - <li>the API will not try to provide high level virtualization policies or - multi-nodes management features like load balancing, but the API should be - sufficient so they can be implemented on top of libvirt</li> - <li>stability of the API is a big concern, libvirt should isolate - applications from the frequent changes expected at the lower level of the - virtualization framework</li> - <li>the node being managed may be on a different physical machine than - the management program using libvirt, to this effect libvirt supports - remote access, but should only do so by using secure protocols.</li> - <li>libvirt will provide APIs to enumerate, monitor and use the resources - available on the managed node, including CPUs, memory, storage, networking, - and NUMA partitions.</li> - </ul> - <p>So libvirt is intended to be a building block for higher level - management tools and for applications focusing on virtualization of a - single node (the only exception being domain migration between node - capabilities which involves more than one node).</p> - </body> -</html> diff --git a/docs/goals.rst b/docs/goals.rst new file mode 100644 index 0000000000..7385f27b61 --- /dev/null +++ b/docs/goals.rst @@ -0,0 +1,56 @@ +===================== +Terminology and goals +===================== + +To avoid ambiguity about the terms used, here are the definitions for some of +the specific concepts used in libvirt documentation: + +- a **node** is a single physical machine +- an **hypervisor** is a layer of software allowing to virtualize a node in a + set of virtual machines with possibly different configurations than the node + itself +- a **domain** is an instance of an operating system (or subsystem in the case + of container virtualization) running on a virtualized machine provided by the + hypervisor + +Now we can define the goal of libvirt: **to provide a common and stable layer +sufficient to securely manage domains on a node, possibly remote**. + +As a result, libvirt should provide all APIs needed to do the management, such +as: provision, create, modify, monitor, control, migrate and stop the domains - +within the limits of the support of the hypervisor for those operations. Not all +hypervisors provide the same operations; but if an operation is useful for +domain management of even one specific hypervisor it is worth providing in +libvirt. Multiple nodes may be accessed with libvirt simultaneously, but the +APIs are limited to single node operations. Node resource operations which are +needed for the management and provisioning of domains are also in the scope of +the libvirt API, such as interface setup, firewall rules, storage management and +general provisioning APIs. Libvirt will also provide the state monitoring APIs +needed to implement management policies, obviously checking domain state but +also exposing local node resource consumption. + +This implies the following sub-goals: + +- All API can be carried remotely though secure APIs +- While most API will be generic in term of hypervisor or Host OS, some API may + be targeted to a single virtualization environment as long as the semantic + for the operations from a domain management perspective is clear +- the API should allow to do efficiently and cleanly all the operations needed + to manage domains on a node, including resource provisioning and setup +- the API will not try to provide high level virtualization policies or + multi-nodes management features like load balancing, but the API should be + sufficient so they can be implemented on top of libvirt +- stability of the API is a big concern, libvirt should isolate applications + from the frequent changes expected at the lower level of the virtualization + framework +- the node being managed may be on a different physical machine than the + management program using libvirt, to this effect libvirt supports remote + access, but should only do so by using secure protocols. +- libvirt will provide APIs to enumerate, monitor and use the resources + available on the managed node, including CPUs, memory, storage, networking, + and NUMA partitions. + +So libvirt is intended to be a building block for higher level management tools +and for applications focusing on virtualization of a single node (the only +exception being domain migration between node capabilities which involves more +than one node). diff --git a/docs/meson.build b/docs/meson.build index adb7ac091e..afed104014 100644 --- a/docs/meson.build +++ b/docs/meson.build @@ -53,7 +53,6 @@ docs_html_in_files = [ 'formatsecret', 'formatstoragecaps', 'formatstorageencryption', - 'goals', 'governance', 'hooks', 'index', @@ -101,6 +100,7 @@ docs_rst_files = [ 'formatsnapshot', 'formatstorage', 'glib-adoption', + 'goals', 'hacking', 'libvirt-go', 'libvirt-go-xml', -- 2.35.1
