docs/docs.html.in | 3 + docs/support.html.in | 257 +++++++++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 260 insertions(+) create mode 100644 docs/support.html.in
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.
Note, this document makes one change to our previous policy. It explicitly
declares the RPC protocol of libvirtd as being a supported interface. THis
accepts the reality that we can a) never change it without breaking compat
with old libvirt.so, b) there are both rust + go impls that are written
against the RPC protocol alrady.
Reviewed-by: Jim Fehlig <jfehlig@suse.com>
Signed-off-by: Daniel P. Berrange <berrange@redhat.com>
---
Changed in v2:
- Spelling fixes (Jim)
- Call out new RPC policy in commit msg
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..7a377e6152
--- /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
+ administrators. The intent is to help users understand what features they
+ 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>
+ guaranteed to be preserved forever. The project reserves the right to remove
+ 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 unforeseen interactions with libvirt's
+ operation.
+ </p>
+
+ <h2><a id="apierrors">Error reporting</a></h2>
+
+ <p>
+ Most API calls are subject to failure and so will report error codes and
+ messages. Libvirt defines error codes for a wide variety of scenarios, some
+ represent very specific problems, while others are general purpose for
+ broad classes of problem. Over time the error codes reported are liable
+ to change, usually changing from a generic error to a more specific error.
+ Thus applications should be careful about checking for & taking action
+ upon specific error codes, as their behaviour may 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. A deployment that expects a particular value for a
+ 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 not supported. Likewise libvirt will
+ 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 implementations that are liable to change
+ 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>
--
2.14.3
--
libvir-list mailing list
libvir-list@redhat.com
https://www.redhat.com/mailman/listinfo/libvir-list
On 11/17/2017 06:36 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. > > Note, this document makes one change to our previous policy. It explicitly > declares the RPC protocol of libvirtd as being a supported interface. THis > accepts the reality that we can a) never change it without breaking compat > with old libvirt.so, b) there are both rust + go impls that are written > against the RPC protocol alrady. > > Reviewed-by: Jim Fehlig <jfehlig@suse.com> > Signed-off-by: Daniel P. Berrange <berrange@redhat.com> > --- > > Changed in v2: > > - Spelling fixes (Jim) > - Call out new RPC policy in commit msg > > docs/docs.html.in | 3 + > docs/support.html.in | 257 +++++++++++++++++++++++++++++++++++++++++++++++++++ > 2 files changed, 260 insertions(+) > create mode 100644 docs/support.html.in > I know/understand it goes against the proposed premise, but I do think it's worth thinking about... Not having a chance to perhaps deprecate certain API's ever even when there's an API that is better certainly makes some engineering decisions much harder to make. It also forces one to "keep around" code that becomes harder and harder to support. There's quite a few examples with the way we collect "driver" data via the API's without @flags. Furthermore, if the lower layer (such as QEMU) deprecates an API - how do we back ourselves out of that corner? I certainly understand from the application layer why it's much easier if you can "guarantee" that the code you rely upon doesn't ever remove something that you rely upon. This is another one of those "hard areas" about adapt or die - carrying around cruft that we believe no one uses, but we cannot prove it, but we've committed to supporting ad infinatum. So understandably we cannot "remove" the API as that would really screw things up, but should we reserve the right to cause the API to return failure after a period of notice? For example, virConnectListDomains and virConnectListDefinedDomains were effectively replaced many years ago by virConnectListAllDomains. While the former API's still work, it is far better to use the latter. So while we cannot remove the former API's, being able to reserve the right to "indicate" in some release that in some release + some required period of time that the API will always return a specific error code and error message indicating the guts of the API has been deprecated and that the caller should use some other specific API. The period of time shall always be (for example) 6 months or longer. Something else that just popped into my consciousness, but I haven't fully thought about... Support of "older" hypervisor verions... We went through an exercise a while back "upping" the lowest version of QEMU we support from the really dark ages, to somewhere closer to the middle ages. Perhaps we could put a "stake" in the ground that "periodically" (and not a x.0.0 release), it will be a goal that for active hypervisors libvirt will support only releases Y years old or X versions of their releases. I know hard to do with different release cycles and certain downstream concerns, but it does help ensure we periodically go through and clean up/out older and harder to maintain algorithms. Of course it means we must follow through, but for those actively developed against hypervisors I would think it would be a net gain. > 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..7a377e6152 > --- /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 > + administrators. The intent is to help users understand what features they > + can rely upon in particular scenarios, and whether they are likely to > + suffer disruption during upgrades 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> > + guaranteed to be preserved forever. The project reserves the right to remove > + 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 unforeseen interactions with libvirt's > + operation. > + </p> > + > + <h2><a id="apierrors">Error reporting</a></h2> > + > + <p> > + Most API calls are subject to failure and so will report error codes and > + messages. Libvirt defines error codes for a wide variety of scenarios, some > + represent very specific problems, while others are general purpose for > + broad classes of problem. Over time the error codes reported are liable > + to change, usually changing from a generic error to a more specific error. > + Thus applications should be careful about checking for & taking action > + upon specific error codes, as their behaviour may 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> Consistency... put </dd> on it's own line. > + <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. A deployment that expects a particular value for a > + 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 not supported. Likewise libvirt will > + 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 implementations that are liable to change > + 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 hypervisor Reviewed-by: John Ferlan <jferlan@redhat.com> John > + 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> > -- libvir-list mailing list libvir-list@redhat.com https://www.redhat.com/mailman/listinfo/libvir-list
On Fri, Nov 17, 2017 at 07:57:23AM -0500, John Ferlan wrote: > > > On 11/17/2017 06:36 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. > > > > Note, this document makes one change to our previous policy. It explicitly > > declares the RPC protocol of libvirtd as being a supported interface. THis > > accepts the reality that we can a) never change it without breaking compat > > with old libvirt.so, b) there are both rust + go impls that are written > > against the RPC protocol alrady. > > > > Reviewed-by: Jim Fehlig <jfehlig@suse.com> > > Signed-off-by: Daniel P. Berrange <berrange@redhat.com> > > --- > > > > Changed in v2: > > > > - Spelling fixes (Jim) > > - Call out new RPC policy in commit msg > > > > docs/docs.html.in | 3 + > > docs/support.html.in | 257 +++++++++++++++++++++++++++++++++++++++++++++++++++ > > 2 files changed, 260 insertions(+) > > create mode 100644 docs/support.html.in > > > > I know/understand it goes against the proposed premise, but I do think > it's worth thinking about... > > Not having a chance to perhaps deprecate certain API's ever even when > there's an API that is better certainly makes some engineering decisions > much harder to make. It also forces one to "keep around" code that > becomes harder and harder to support. There's quite a few examples with > the way we collect "driver" data via the API's without @flags. At least in the case of APIs without flags, the burden is pretty minimal, as from the hypervisor driver impls, the old API simply calls the new API with flags==0. So we just have the wire protocol & public API entries to keep around, which don't have a cost as that part is essentially write-once, touch never. > Furthermore, if the lower layer (such as QEMU) deprecates an API - how > do we back ourselves out of that corner? We have never promised that every API works with every hypervisor, or every hypervisor version. If QEMU changes something that libvirt relies on we would try to adapt libvirt to an alternative impl with the same semantics. If that's no possible, we are already within our rights to just return an error from the API in question, as we can't magic a feature up out of thin air if it doesn't exist anymore :-) Fortunately hypervisors rarely delete features entirely. I think we have hit this problem in a few places before, but can't remember details offhand. It wasn't the end of the world though. > I certainly understand from the application layer why it's much easier > if you can "guarantee" that the code you rely upon doesn't ever remove > something that you rely upon. It is a matter of pain for one project (libvirt) in maintaining the feature, vs pain for 10's or 100's of projects (the downstream apps) if we change a feature. The core premise of libvirt is that for the open source virt ecosystem as a whole, it is a net win if the libvirt team accepts the maint burden of providing back compat. This has also been key to the ability of entrprise distros like RHEL to pull in newer libvirt on a regular basis. Other projects have taken different views (GTK, and Python) are two significant ones that come to mind. The fallout seen from Gtk2 -> Gtk3 and Python2 to Python3 has been really massively painful for applications. > This is another one of those "hard areas" about adapt or die - carrying > around cruft that we believe no one uses, but we cannot prove it, but > we've committed to supporting ad infinatum. > > So understandably we cannot "remove" the API as that would really screw > things up, but should we reserve the right to cause the API to return > failure after a period of notice? > > For example, virConnectListDomains and virConnectListDefinedDomains were > effectively replaced many years ago by virConnectListAllDomains. While > the former API's still work, it is far better to use the latter. So > while we cannot remove the former API's, being able to reserve the right > to "indicate" in some release that in some release + some required > period of time that the API will always return a specific error code and > error message indicating the guts of the API has been deprecated and > that the caller should use some other specific API. The period of time > shall always be (for example) 6 months or longer. The ListDomains/ListDefinedDomains/ListAllDomains APIs are probably the main case where we do have a burden in hypervisor drivers from old APIs, because we kept the original impls around without change. It would be possible to change ListDomains/DefinedDomains to actually call the ListAllDomains methods todo their work, which would take the burden out of the individual drivers. There would be some cost in performance of the old APIs though. I think that arbitrarily changing an API to return an error, is actually worse than deleting it entirely, because you've turned what would be a compile time incompatibility into a runtime incompatibility. I would only do that in the example you illustrate earlier, where a hypervisor removes a feature and there's no way for libvirt to continue to provide the equivalent functionality. > Something else that just popped into my consciousness, but I haven't > fully thought about... Support of "older" hypervisor verions... We went > through an exercise a while back "upping" the lowest version of QEMU we > support from the really dark ages, to somewhere closer to the middle > ages. Perhaps we could put a "stake" in the ground that "periodically" > (and not a x.0.0 release), it will be a goal that for active hypervisors > libvirt will support only releases Y years old or X versions of their > releases. I know hard to do with different release cycles and certain > downstream concerns, but it does help ensure we periodically go through > and clean up/out older and harder to maintain algorithms. Of course it > means we must follow through, but for those actively developed against > hypervisors I would think it would be a net gain. There is a section inthe doc below that describes our policy wrt hypervisor version support. There are so many different release cycles / timeframes, and with Linux length of support varies per distros, that it is hard to define a fixed rule. So I used the fuzzy definition of saying we'll not support a hypervisor if the vendor has end of life'd it, and we reserve the right to end support sooner than end-of-life, if we decide that there are insufficient real world users to justify it. IOW, while technically RHEL-5 is supporting KVM still, the number of users of that who will also be interested in new libvirt is essentially zero, so we choose to drop it as a target. As a rough rule of thumb for KVM, I would go with a max of 2 RHEL major versions, so we could drop RHEL-6 when RHEL-8 comes out. I didn't want to write the doc in terms of RHEL though, as that's a bit biased towards one vendor. > > + <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 not supported. Likewise libvirt will > > + 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> Regards, Daniel -- |: https://berrange.com -o- https://www.flickr.com/photos/dberrange :| |: https://libvirt.org -o- https://fstop138.berrange.com :| |: https://entangle-photo.org -o- https://www.instagram.com/dberrange :| -- libvir-list mailing list libvir-list@redhat.com https://www.redhat.com/mailman/listinfo/libvir-list
© 2016 - 2024 Red Hat, Inc.