Open Stack

On Wed, Aug 03, 2016 at 08:54:07PM -0400, 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.

+1. Microversions as a concept was created (and communicated) on the
basis that the API should always behave the same if the client always
sends the same microversion. Clients pinned to a particular version
likely won't notice the new microversion until they need to (probably
when behavior changes when they weren't expecting it).

> 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.

I actually do disagree here. While adding a field to a resource, or a
new action, probably won't break any clients, I do think it's a good
signal here. If clients wish to always have all the new features, they
should be looking for new versions often and doing the work to move up.
They probably can't use the new thing without a code change, anyway, so
I don't think it's a major problem to need to bump the version to get a
new thing.

That said, it is annoying as a developer to need to deal with all the
versioning things to simply add a field. I know plenty of folks that
agree with you here, and can understand why. :)

> 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.

I do agree we should advertise capabilities. However, those should
*also* be added behind a microversion (and not exposed in earlier
microversions), IMO.

> 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.

Again, I think microversions are good here.

Thanks for kicking this off, Andrew. It's a conversation I keep hearing
from quite a few people, and it's time we try and settle it.

// jim