[libvirt] [PATCH] docs: add a page describing support guarantees for libvirt features
Jim Fehlig
jfehlig at suse.com
Thu Nov 16 22:32:21 UTC 2017
On 11/16/2017 10:19 AM, Daniel P. Berrange wrote:
> While we have collective knowledge about the support status of various
> parts of libvirt, this has never been formally documented, leaving our
> users to guess.
>
> Signed-off-by: Daniel P. Berrange <berrange at redhat.com>
> ---
> docs/docs.html.in | 3 +
> docs/support.html.in | 257 +++++++++++++++++++++++++++++++++++++++++++++++++++
> 2 files changed, 260 insertions(+)
> create mode 100644 docs/support.html.in
>
> diff --git a/docs/docs.html.in b/docs/docs.html.in
> index 931da85424..a8d544f83f 100644
> --- a/docs/docs.html.in
> +++ b/docs/docs.html.in
> @@ -110,6 +110,9 @@
> <dt><a href="drivers.html">Drivers</a></dt>
> <dd>Hypervisor specific driver information</dd>
>
> + <dt><a href="support.html">Support guarantees</a></dt>
> + <dd>Details of support status for various interfaces</dd>
> +
> <dt><a href="hvsupport.html">Driver support</a></dt>
> <dd>matrix of API support per hypervisor per release</dd>
>
> diff --git a/docs/support.html.in b/docs/support.html.in
> new file mode 100644
> index 0000000000..6f34a35eb7
> --- /dev/null
> +++ b/docs/support.html.in
> @@ -0,0 +1,257 @@
> +<?xml version="1.0" encoding="UTF-8"?>
> +<!DOCTYPE html>
> +<html xmlns="http://www.w3.org/1999/xhtml">
> + <body>
> + <h1>Support guarantees</h1>
> +
> + <ul id="toc"></ul>
> +
> + <p>
> + This document will outline the support status / guarantees around the
> + very interfaces that libvirt exposes to applications and/or system
> + adminstrators. The intent is to help users understand what features they
administrators
> + can rely upon in particular scenarios, and whether they are likely to
> + suffer disruption during upgrades
> + </p>
> +
> + <h2><a id="publicAPI">Primary public API</a></h2>
> +
> + <p>
> + The main public API provided by <code>libvirt.so</code> and described
> + in <code>libvirt/libvirt.h</code> exposes the primary hypervisor
> + agnostic management interface of libvirt. This API has the strongest
> + guarantee of any part of libvirt with a promise to keep backwards
> + compatibility forever. Specific details are as follows:
> + </p>
> +
> + <dl>
> + <dt>Functions</dt>
> + <dd>Functions will never be removed from the public API, and will
> + never have parameters added, removed or changed in their signature.
> + IOW they will be ABI compatible forever. The semantics implied by
> + a specific set of parameters passed to the function will remain
> + unchanged. Where a parameter accepts a bitset of feature flags, or
> + an enumerated value, further flags / enum values may be supported
> + in the future. Where a parameter accepts one of a set of related
> + constants, further constants may be supported in the future.
> + </dd>
> + <dt>Struct types</dt>
> + <dd>Once defined in a release, struct definitions will never have any
> + fields add, removed or changed in any way. Their size and layout is
> + fixed forever. If a struct name starts with an underscore, it is
> + considered acceptable to rename it. Applications should thus always
> + use the corresponding typedef in preference to the struct name.
> + </dd>
> + <dt>Union types</dt>
> + <dd>Once defined in a release, union definitions will never have any
> + existing fields removed or changed. New union choices may be added,
> + provided that they don't change the size of the existing union
> + definition. If a struct name starts with an underscore, it is
> + considered acceptable to rename it. Applications should thus always
> + use the corresponding typedef in preference to the struct name.
> + </dd>
> + <dt>Type definitions</dt>
> + <dd>Most custom data types used in the APIs have corresponding typedefs
> + provided for their stable names. The typedefs should always be used
> + in preference to the underlying data type name, as the latter are not
> + guaranteed to be stable.
> + </dd>
> + <dt>Enumerations</dt>
> + <dd>Once defined in a release, existing enumeration values will never
> + be removed or renamed. New enumeration values may be introduced at
> + any time. Every enumeration will have a '_LAST' value which indicates
> + the current highest enumeration value, which may increase with new
> + releases. If an enumeration name starts with an underscore, it is
> + considered acceptable to rename it. Applications should thus always
> + use the corresponding typedef in preference to the enum name.
> + </dd>
> + <dt>Constants</dt>
> + <dd>Once defined in a release, existing constants will never be removed
> + or have their value changed. Most constants are grouped into related
> + sets, and within each set, new constants may be introduced. APIs which
> + use the constants may thus accept or return new constant values over
> + time.
> + </dd>
> + <dt>Symbol versions</dt>
> + <dd>Where the platform library format permits, APIs defined in libvirt.so
> + library will have version information associated. Each API will be
> + tagged with the version in which it was introduced, and this won't
> + be changed thereafter.
> + </dd>
> + </dl>
> +
> + <h2><a id="hvAPI">Hypervisor specific APIs</a></h2>
> +
> + <p>
> + A number of hypervisor drivers provide additional libraries with hypervisor
> + specific APIs, extending the core libvirt API. These add-on libraries follow
> + the same general principles described above, however, they are <strong>not</strong>
> + not guranteed to be preserved forever. The project reserves the right to remove
extra 'not'
> + hypervisor specific APIs in any new release, or to change their semantics.
> + That said the project will endeavour to maintain API compatibility for as long
> + as is practical.
> + </p>
> +
> + <p>
> + Use of some hypervisor specific APIs may result in the running guest being
> + marked as "tainted" if the API is at risk of having unexpected interactions
> + with normal libvirt operations. An application which chooses to make use of
> + hypervisor specific APIs should validate their operation with each new release
> + of libvirt and each new release of the underlying hypervisor. The semantics
> + may change in unexpected ways, or have unforseen interactions with libvirt's
unforeseen
> + operation.
> + </p>
> +
> + <h2><a id="apierrors">Error reporting</a></h2>
> +
> + <p>
> + Almost API calls are subject to failure and so will report error codes and
s/Almost/Most/
> + messages. Libvirt defines error codes for a wide variety of scenarios, some
> + are very targetted to specific problems, while others are general purpose
targeted ? Or is this like tunnelled vs tunneled :-).
> + for broad classes of problem. Over time the error codes reported are liable
> + to, usually changing from a generic error to a more specific error. Thus
s/liable to,/liable to change,/
> + applications should be careful about checking for & taking action upon
> + specific error codes, as the behaviour is liable to change across releases.
> + </p>
> +
> + <h2><a id="xmlschema">XML schemas</a></h2>
> +
> + <p>
> + The main objects exposed via the primary libvirt public API are usually
> + configured via XML documents following specific schemas. The XML schemas
> + are considered to be stable formats, whose compatibility will be maintained
> + forever. Specific details are as follows:
> + </p>
> +
> + <dl>
> + <dt>Attributes</dt>
> + <dd>Attributes defined on an XML element will never be removed or
> + renamed. New attributes may be defined. If the set of valid values
> + for an attribute are determined by an enumeration, the permitted
> + values will never be removed or renamed, only new values defined.
> + None the less, specific hypervisors may reject usage of certain
> + values according to their feature set.</dd>
> + <dt>Elements</dt>
> + <dd>Elements defined will never be removed or renamed. New child
> + elements may be defined at any time. In places where only a
> + single instance of a named XML element is used, future versions
> + may be extended to permit multiple instances of the named XML
> + element to be used. An element which currently has no content
> + may later gain child elements.
> + </dd>
> + </dl>
> +
> + <p>
> + Some hypervisor drivers may choose to allow use of hypervisor specific
> + extensions to the XML documents. These extensions will always be
> + contained within a hypervisor specific XML namespace. There is generally
> + no guarantee of long term support for the hypervisor specific extensions
> + across releases, though the project will endeavour to preserve them as
> + long as is possible. Applications choosing to use hypervisor specific
> + extensions should validate their operation against new libvirt or
> + hypervisor releases.
> + </p>
> +
> + <h2><a id="configfiles">Configuration files</a></h2>
> +
> + <p>
> + A number of programs / daemons provided libvirt rely on host filesystem
> + configuration files. These configuration files are accompanied by augeas
> + lens for easy manipulation by applications. There is in general no
> + guarantee that parameters available in the configuration file will be
> + preserved across releases, though the project will endeavour to preserve
> + them as long as is possible. If a configuration option is dropped from
> + the file, the augeas lens will retain the ability to read that configuration
> + parameter, so that it is able to read & update historically modified
> + files.
> +
> + The default configuration files ship with all parameters commented out
> + such that a deployment relies on the built-in defaults of the application
> + in question. There is no guarantee that the defaults will remain the same
> + across releases. An deployments that expects a particular value for a
s/An deployments/A deployment/
> + configuration parameter should consider defining it explicitly, instead
> + of relying on the defaults.
> + </p>
> +
> + <h2><a id="hvdrivers">Hypervisor drivers</a></h2>
> +
> + <p>
> + The libvirt project provides support for a wide variety of hypervisor
> + drivers. These drivers target certain versions of the hypervisor's
> + underlying management APIs. In general libvirt aims to work with any
> + hypervisor version that is still broadly supported by its vendor.
> + When a vendor discontinues support for a particular hypervisor
> + version it will be dropped by libvirt. Libvirt may choose to drop
> + support for a particular hypervisor version prior to the vendor
> + ending support, if it deems that the likely usage is too small to
> + justify the ongoing maintenance cost.
> + </p>
> + <p>
> + Each hypervisor release will implement a distinct subset of features
> + that can be expressed in the libvirt APIs and XML formats. While the
> + XML schema syntax will be stable across releases, libvirt is unable
> + to promise that it will always be able to support usage of the same
> + features across hypervisor releases. Where a hypervisor changes the
> + way a feature is implemented, the project will endeavour to adapt
> + to the new implementation to provide the same semantics. In cases
> + where the feature is discontinued by the hypervisor, libvirt will
> + return an error indicating it is no supported. Likewise libvirt will
s/no/not/
> + make reasonable efforts to keep API calls working across hypervisor
> + releases even if the underlying implementation changes. In cases where
> + this is impossible, an suitable error will be reported. The list of
> + APIs which have implementations <a href="hvsupport.html">is detailed separately</a>.
> + </p>
> +
> + <h2><a id="rpcproto">RPC protocol</a></h2>
> +
> + <p>
> + For some hypervisor drivers, the libvirt.so library communicates with
> + separate libvirt daemons to perform work. This communication takes
> + place over a binary RPC protocol defined by libvirt. The protocol uses
> + the XDR format for data encoding, and the message packet format is
> + defined in libvirt source code.
> + </p>
> + <p>
> + Applications are encouraged to use the primary libvirt.so library which
> + transparently talks to the daemons, so that they are not exposed to the
> + hypervisor driver specific details. None the less, the RPC protocol
> + associated with the libvirtd is considered to be a long term stable ABI.
> + It will only ever have new messages added to it, existing messages will
> + not be removed, nor have their contents changed. Thus if an application
> + does wish to provide its own client side implementation of the RPC
> + protocol this is supported, with the caveat that the application will
> + loose the ability to work with certain hypervisors libvirt supports.
> + The project reserves the right to define new authentication and encryption
> + options for the protocol, and the defaults used in this area may change
> + over time. This is particularly true of the TLS ciphers permitted. Thus
> + applications choosing to implement the RPC protocol must be prepared to
> + track support for new security options. If defaults are changed, however,
> + it will generally be possible to reconfigure the daemon to use the old
> + defaults, albeit with possible implications for system security.
> + </p>
> +
> + <p>
> + Other daemons besides, libvirtd, also use the same RPC protocol, but
> + with different message types defined. These RPC protocols are all
> + considered to be private implementation that are liable to change
s/implementation/implementations/ ?
> + at any time. Applications must not attempt to talk to these other
> + daemons directly.
> + </p>
> +
> + <h2><a id="virsh">virsh client</a></h2>
> +
> + <p>
> + The virsh program provides a simple client to interact with an arbitrary libvirt
> + hypevisor connection. Since it uses the primary public API of libvirt, it should
> + generally inherit the guarantees associated with that API, and with the hypervisor
> + driver. The commands that virsh exposes, and the arguments they accept are all
> + considered to be long term stable. Existing commands and arguments will not be
> + removed or renamed. New commands and arguments may be added in new releases.
> + The text output format produced by virsh commands is not generally guaranteed to
> + be stable if it contains compound data (eg formatted tables or lists). Commands
> + which output single data items (ie an object name, or an XML document), can be
> + treated as having stable format.
> + </p>
> +
> + </body>
> +</html>
Reviewed-by: Jim Fehlig <jfehlig at suse.com>
Regards,
Jim
More information about the libvir-list
mailing list