Open Stack

On 02/19/2016 10:57 AM, Sean Dague wrote:
> 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

It disagree that this (step 4) is a failure. Clients should not have to 
do a check at all. The client should tell the server what it wants to do 
(send the request and version) and the server should do exactly that if 
and only if it can. Any requirement that the client check the server's 
version is a massive violation of good API design and will cause either 
performance problems or correctness problems or both.

-Ben Swartzlander

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