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

Andrew Laski andrew at lascii.com
Thu Aug 4 16:43:38 UTC 2016

On Thu, Aug 4, 2016, at 11:40 AM, John Garbutt wrote:
> On 4 August 2016 at 16:28, Edward Leafe <ed at leafe.com> wrote:
> > On Aug 4, 2016, at 8:18 AM, Andrew Laski <andrew at lascii.com> wrote:
> >
> >> This gets to the point I'm trying to make. We don't guarantee old
> >> behavior in all cases at which point users can no longer rely on
> >> microversions to signal non breaking changes. And where we do guarantee
> >> old behavior sometimes we do it artificially because the only signal we
> >> have is microversions and that's the contract we're trying to adhere to.
> >
> > I've always understood microversions to be a way to prevent breaking an automated tool when we change either the input or output of our API. Its benefit was less clear for the case of adding a new API, since there is no chance of breaking something that would never call it. We also accept that a bug fix doesn't require a microversion bump, as users should *never* be expecting a 5xx response, so not only does fixing that not need a bump, but such fixes can be backported to affect all microversions.
> >
> > The idea that by specifying a distinct microversion would somehow guarantee an immutable behavior, though, is simply not the case. We discussed this at length at the midcycle regarding the dropping of the nova-network code; once that's dropped, there won't be any way to get that behavior no matter what microversion you specify. It's gone. We signal this with deprecation notices, release notes, etc., and it's up to individuals to move away from using that behavior during this deprecation period. A new microversion will never help anyone who doesn't follow these signals.
> >
> > In the case that triggered this thread [0], the change was completely on the server side of things; no change to either the request or response of the API. It simply allowed a failed resize to be recovered more easily. That's a behavior change, not an API change, and frankly, I can't imagine anyone who would ever *want* the old behavior of leaving an instance in an error state. To me, that's not very different than fixing a 5xx response, as it is correcting an error on the server side.
> >
> The problem is was thinking about is, how do you know if a cloud
> supports that new behaviour? For me, a microversion does help to
> advertise that. Its probably a good example of where its not important
> enough to add a new capability to tell people thats possible.

I do see this as a capability though. I've been thinking of capabilities
as an answer to the question of "what can I do with this resource?" So a
capability query to an instance that errored during resize might
currently just return ['delete', 'call admin(joking)'] and assuming we
relax the restriction it would return ['delete', 'revert_resize'].

> That triggers the follow up question, of is that important in this
> case, could you just make the call and see if it works?

Sure. Until we have more discoverability in the API this is the reality
of what users need to do due to things like policy checks.

What I'm aiming for is discoverability that works well for users. The
current situation is a new microversion means go check the docs or
release notes and where I'd like to be is a new microversion means check
the provided API schemas, and a new/removed capability expresses a
change in behavior. And if there are other types of changes users should
be aware of that we think about the right mechanism for exposing it. All
I'm saying is all we have is a hammer, is everything we're using it on
really a nail? :)

> Thanks,
> johnthetubaguy
> __________________________________________________________________________
> 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

More information about the OpenStack-dev mailing list