[libvirt] [PATCH v2] docs: add a page describing support guarantees for libvirt features

Fri Nov 17 13:17:47 UTC 2017

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 at suse.com>
> > Signed-off-by: Daniel P. Berrange <berrange at 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 :|