[openstack-dev] [cinder] adding a new /v3 endpoint for api-microversions

Morgan Fainberg morgan.fainberg at gmail.com
Fri Feb 19 16:38:38 UTC 2016

On Fri, Feb 19, 2016 at 8:24 AM, Sean Dague <sean at dague.net> wrote:

> On 02/19/2016 11:15 AM, Ben Swartzlander wrote:
> > 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.
> That is a fair concern. However the Cinder API today doesn't do strict
> input validation (in my understanding). Which means it's never given
> users that guaruntee. Adding ?foo=bar to random resources, or extra
> headers, it likely to just get silently dropped.
> Strict input validation is a good thing to do, and would make a very
> sensible initial microversion to get onto that path.
> So this isn't really worse than the current situation. And the upside is
> easier adoption.
>         -Sean
> --
> Sean Dague
> http://dague.net
> __________________________________________________________________________
> 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

AS a point we are also trying to drop "versioned endpoints" as a thing from
the catalog going forward. Please do not add a "cinderv3" or "volumev3"
entry to the catalog. This is something that enourages adding for every
version a new endpoint. If every service had an entry for each endpoint
version in the catalog it rapidly balloons the size (think of, the ~14?
services we have now, each with now three entries per "actual api
endpoint"). The catalog is good to a point, but if everyone added a
versioned endpoint it would rapidly become more of a beast that it is and
potentially become a bigger bottleneck/performance issue than it already is.

Asking the endpoint a single time what versions it supports and relevant
information not encoded in the catalog (lets be fair, the catlog does not
contain everything, heck, you don't even know what version of v2 cinder API
an endpoint has, you should probably ask for discoverability to provide
good responses to the user vs random/spurious 404 because a new
cinderclient knows extra APIs than the juno cinder API provides).

I think Sean is giving good guidance on extending from /v2 personally. I
have other mixed feelings on microversions (see the nova thread on
indicating compatibility), but if microversions are to be supported, it
isn't terrible to extend from your existing point as long as the client is
expected to get "current" behavior without any negotiation done, and can
discover availability (among other required information) on an initial call
to the endpoint.

Just my $0.02.
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.openstack.org/pipermail/openstack-dev/attachments/20160219/25d414e4/attachment.html>

More information about the OpenStack-dev mailing list