[openstack-dev] [Nova] Some thoughts on API microversions

Matt Riedemann mriedem at linux.vnet.ibm.com
Sat Aug 6 17:52:20 UTC 2016

On 8/3/2016 7:54 PM, Andrew Laski wrote:
> I've brought some of these thoughts up a few times in conversations
> where the Nova team is trying to decide if a particular change
> warrants a microversion. I'm sure I've annoyed some people by this
> point because it wasn't germane to those discussions. So I'll lay
> this out in it's own thread.
> I am a fan of microversions. I think they work wonderfully to
> express when a resource representation changes, or when different
> data is required in a request. This allows clients to make the same
> request across multiple clouds and expect the exact same response
> format, assuming those clouds support that particular microversion. I
> also think they work well to express that a new resource is
> available. However I do think think they have some shortcomings in
> expressing that a resource has been removed. But in short I think
> microversions work great for expressing that there have been changes
> to the structure and format of the API.
> I think microversions are being overused as a signal for other types
> of changes in the API because they are the only tool we have
> available. The most recent example is a proposal to allow the
> revert_resize API call to work when a resizing instance ends up in an
> error state. I consider microversions to be problematic for changes
> like that because we end up in one of two situations:
> 1. The microversion is a signal that the API now supports this
> action, but users can perform the action at any microversion. What
> this really indicates is that the deployment being queried has
> upgraded to a certain point and has a new capability. The structure
> and format of the API have not changed so an API microversion is the
> wrong tool here. And the expected use of a microversion, in my
> opinion, is to demarcate that the API is now different at this
> particular point.
> 2. The microversion is a signal that the API now supports this
> action, and users are restricted to using it only on or after that
> microversion. In many cases this is an artificial constraint placed
> just to satisfy the expectation that the API does not change before
> the microversion. But the reality is that if the API change was
> exposed to every microversion it does not affect the ability I lauded
> above of a client being able to send the same request and receive the
> same response from disparate clouds. In other words exposing the new
> action for all microversions does not affect the interoperability
> story of Nova which is the real use case for microversions. I do
> recognize that the situation may be more nuanced and constraining the
> action to specific microversions may be necessary, but that's not
> always true.
> In case 1 above I think we could find a better way to do this. And I
> don't think we should do case 2, though there may be special cases
> that warrant it.
> As possible alternate signalling methods I would like to propose the
> following for consideration:
> Exposing capabilities that a user is allowed to use. This has been
> discussed before and there is general agreement that this is
> something we would like in Nova. Capabilities will programatically
> inform users that a new action has been added or an existing action
> can be performed in more cases, like revert_resize. With that in
> place we can avoid the ambiguous use of microversions to do that. In
> the meantime I would like the team to consider not using
> microversions for this case. We have enough of them being added that
> I think for now we could just wait for the next microversion after a
> capability is added and document the new capability there.
> Secondly we could consider some indicator that exposes how new the
> code in a deployment is. Rather than using microversions as a proxy
> to indicate that a deployment has hit a certain point perhaps there
> could be a header that indicates the date of the last commit in that
> code. That's not an ideal way to implement it but hopefully it makes
> it clear what I'm suggesting. Some marker that a user can use to
> determine that a new behavior is to be expected, but not one that's
> more intended to signal structural API changes.
> Thoughts?
> -Andrew
> __________________________________________________________________________
OpenStack Development Mailing List (not for usage questions)
> Unsubscribe:
> OpenStack-dev-request at lists.openstack.org?subject:unsubscribe
> http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev

I probably can't add much to what's already been said elsewhere in this
thread. I agree microversions aren't a great fit for all things, and
they are especially tricky around behavior changes, like allowing rescue
of a volume-backed instance, or revert_resize of an instance in error state.

We have done a couple in Newton (2.32, 2.37) that are based on (1) 
request schema changes and (2) minimum nova-compute service version in 
the deployment. The (2) part of that is really fudging capabilities. For 
example, 2.32 will work if the minimum nova-compute is new enough AND 
the compute you hit is libvirt or hyper-v. If you're using ironic, 
vmware or xen then virtual device tags don't work. So from a client POV 
I don't have 100% assurance that requesting device tags with >=2.32 will 
actually work even if the computes are all running the latest code, but 
as mentioned elsewhere, it's at least some kind of signal which is 
better than nothing.

We're all in agreement on getting to discoverable policy and 
capabilities in the API, which we talked about at the Newton midcycle 
and we said there would be some work on that in Ocata.

There are other services in OpenStack that do provide a capabilities 
API, like Cinder:


That's just an RPC call from cinder-api to cinder-volume to ask the 
volume driver for a set of standard and vendor-specific capabilities. It 
provides a driver version (I'm not totally sure what that is, i.e. is it 
the version of NFS running on that host? Or the version of Cinder on 
that host?). It's also admin-only by default since you have to provide a 
hostname. I do wonder how much that is used by admins though. I'd think 
we could do something similar and make the host part optional (but 
admin-only if specified). But the user could request the capabilities of 
the cloud which would be aggregated from the host (resource provider) 

Anyway, thanks for kicking off a separate thread on this. I think we're 
going to need a session at Barcelona to dig into this a bit more in 
detail so we can flesh out an initial design.



Matt Riedemann

More information about the OpenStack-dev mailing list