Open Stack

On 02/18/2016 10:38 AM, D'Angelo, Scott wrote:
> Cinder team is proposing to add support for API microversions [1]. It came up at our mid-cycle that we should add a new /v3 endpoint [2]. Discussions on IRC have raised questions about this [3]
> 
> Please weigh in on the design decision to add a new /v3 endpoint for Cinder for clients to use when they wish to have api-microversions.
> 
> PRO add new /v3 endpoint: A client should not ask for new-behaviour against old /v2 endpoint, because that might hit an old pre-microversion (i.e. Liberty) server, and that server might carry on with old behaviour. The client would not know this without checking, and so strange things happen silently.
> It is possible for client to check the response from the server, but his requires an extra round trip.
> It is possible to implement some type of caching of supported (micro-)version, but not all clients will do this.
> Basic argument is that  continuing to use /v2 endpoint either requires an extra trip for each request (absent caching) meaning performance slow-down, or possibility of unnoticed errors.
> 
> CON add new endpoint:
> Downstream cost of changing endpoints is large. It took ~3 years to move from /v1 -> /v2 and we will have to support the deprecated /v2 endpoint forever.
> If we add microversions with /v2 endpoint, old scripts will keep working on /v2 and they will continue to work.
> We would assume that people who choose to use microversions will check that the server supports it.

The concern as I understand it is that by extending the v2 API with
microversions the following failure scenario exists

If:

1) a client already is using the /v2 API
2) a client opt's into using microversions on /v2
3) that client issues a request on a Cinder API v2 endpoint without
microversion support
4) that client fails check if micoversions are supported by a GET of /v2
or by checking the return of the OpenStack-API-Version return header
5) that client issues a request against a resource on /v2 with
parameters that would create a radically different situation that would
be hard to figure out later.

And, only if all these things happen is there a concern.

So let's look at each one.

1) clients already using /v2 API

Last cycle when we tried to drop v1 from devstack we got a bunch of
explosions. In researching it it was determined that very little
supported cinder v2 -
http://lists.openstack.org/pipermail/openstack-dev/2015-September/075760.html


At that point not even OpenStack Client itself, or Rally. And definitely
no libraries except python cinderclient. So the entire space of #1 is
python cinderclient, or non open rest clients.

2 & 4) are coupled. A good client that does 2 should do 4, and not only
depend on the 406 failure. cinderclient definitely should be made to do
that. Which means we are completely left with only custom non open
access code that's a concern. That's definitely still a concern, but
again the problem space is smaller.

3) can be mitigated if cinder backports patches to stable branches to
throw the 406 when sending the header. It's mitigation. Code already is
out in the wild, however it does help. And given other security fixes
people will probably take these patches into production.

5) is there an example where this is expected? or is this theoretical.


My very high concern is the fact that v2 adoption remains quite low, and
that a v3 will hurt that even further. Especially as it means a whole
other endpoint... "volumev2" was already a big problem in teaching a
bunch of software that it needs a new type, "volumev3" is something I
don't think anyone wants to see. I'd really like to see more of these
improvements get out there.

At the end of the day, this is the call of the Cinder team.

However, I've seen real 3rd party vendor software hitting the Nova API
that completely bypasses the service catalog, and hits /v2.1 directly
(it's not using microversions). Which means that it can't work on a Kilo
cloud. For actually no reason. As /v2.1 and /v2 are semantically
equivalent. Vendors do weird things. They read the docs, say "oh this is
the latest API" and only implement to that. They don't need any new
features, don't realize the time delay in these things getting out
there. It's a big regret that we have multiple endpoints because it
means these kinds of applications basically break for no good reason.

So my recommendation is to extend out from the /v2 endpoint. This is
conceptually what you are actually doing. The base microversion will be
v2 API as it exists today, and you are negotiating up from there.

	-Sean

-- 
Sean Dague
http://dague.net