[openstack-dev] [api] [Nova] [Ironic] [Magnum] Microversion guideline in API-WG
dtantsur at redhat.com
Thu Jun 25 09:16:20 UTC 2015
On 06/25/2015 11:11 AM, Ken'ichi Ohmichi wrote:
> 2015-06-25 17:31 GMT+09:00 Dmitry Tantsur <dtantsur at redhat.com>:
>> On 06/25/2015 10:18 AM, Ken'ichi Ohmichi wrote:
>>> Sorry for late response here,
>>> 2015-06-20 9:14 GMT+09:00 Devananda van der Veen
>>> <devananda.vdv at gmail.com>:
>>>> Long version...
>>>> Every HTTP response from Ironic today includes three headers: min, max,
>>>> version. The service can present an older API version, as long as it is
>>>> greater-than-or-equal-to the minimum supported version, even if that
>>>> is incompatible with the maximum supported version. It does this by
>>>> rewriting responses to match what was expected in the requested (older)
>>>> When the newer version is identical *for all interfaces present* in the
>>>> older version, this can be called compatible. Dmitry's point is that we
>>>> don't need to hide newer interfaces from users who request an older API
>>>> version, because the client won't know or care about things that weren't
>>>> the version it requested.
>>>> However, we *do* need to signal their presence, and we don't have a good
>>>> means for that right now. We also need to signal to the client that the
>>>> response given is "compatible with" a certain "age" of API, even if it's
>>>> exactly the same. And we don't have any means for that, either.
>>>> Time for an example....
>>>> Let's say that an incompatible change was made in v1.3. Let's also say
>>>> a change was made in v1.5 that added a new endpoint. Today, this is what
>>>> response headers would look like when calling a server running v1.5.
>>>> a) client requests v1.2, receives headers (min: 1.1, max: 1.5, current:
>>>> b) client requests v1.4, receives headers (min: 1.1, max: 1.5, current
>>>> c) client requests v1.5, receives headers (min: 1.1, max: 1.5, current:
>>>> What we have implemented today is that in case (b), the service will
>>>> any changes that we introduced in v1.5. But those changes did not affect
>>>> functionality of the v1.4 API, so Dmitry objects to this. So do I.
>>>> The issue at hand is the response in case (b) ... though after spending
>>>> last several months working on api versioning, I actually think all of
>>>> are poor responses.
>>>> What I believe we should have:
>>>> a) client requests v1.2, receives headers (min: 1.1, max: 1.5,
>>>> compatible-with: 1.1)
>>>> b) client requests v1.4, receives headers (min: 1.1, max: 1.5,
>>>> compatible-with: 1.3)
>>>> b) client requests v1.5, receives headers (min: 1.1, max: 1.5,
>>>> compatible-with: 1.3)
>>>> Yes -- (b) and (c) are identical responses.
>>> I think it is good that backwards compatible changes(new features) are
>>> available on older microversion also *only* if the clouds which are
>>> used by users continue upgrading.
>>> I think Sophia's role on "The Backwards Compatibility Fallacy" of
>>> Sean's blog has answered to this question, but I'd like to try
>>> explaining it here for considering Ironic situation.
>>> As the example, there are multiple public clouds which provide
>>> different max microversions like:
>>> Cloud A: Max microversion: v1.5
>>> Cloud B: Max microversion: v1.1
>>> A user wrote his own application for running on cloud A and specifying
>>> v1.1 on the first application implementation.
>>> The first application used small number of APIs, and he wanted to
>>> extend the application.
>>> If all backwards compatible changes(v1.2 - v1.5) appear on lower
>>> microversion(in this case v1.1), he can use all new features even if
>>> specifying v1.1.
>>> That seemed really great for users at this time, and he extended the
>>> application for using all features as possible.
>>> but the specified microversion still is v1.1 because his application
>>> worked fine even if using newer features.
>> It's a valid concern, but it does not justify such a insanely complex
>> measure with so many downsides. We can't and shouldn't prevent people from
>> trying to work around the API contract. It's like people who will claim
>> version 1.3 while they actually are not compatible with it: they are asking
>> for breakage. And with hiding new features you WILL get this situation.
> Sorry, to be honest, I cannot understand your comment here.
> Are you saying the above interoperable issue is not matter by
> comparing downsides requirements?
> If so, is that just for Ironic? or for whole OpenStack projects including Nova?
> What is the reason for justifying your requirement?
> Just many people are saying so around you without considering this
> interoperable issue?
I'm only saying that these (theoretical) issue is smaller than issues
that your approach introduces. Please see all my upper posts for details.
> Ken Ohmichi.
>> On the other hand, I've put up a lot of concerns with Nova's implementation,
>> that people didn't even try to address. I'm not going to consider this one
>>> After that, he needed to switch to the other cloud because of cost
>>> merit or something.
>>> The specified microversion was v1.1, so he did think his application
>>> can work fine on cloud B also because of cloud B's max microversion.
>>> But yes, his application could not work because his application had
>>> already used newer features which are implemented on v1.2+.
>>> In the real world, there are a lot of clouds and it is easy to imagine
>>> this situation.
>>> Current microversion implementation of Nova is blocking this situation
>>> by making backwards every compatible change appear on each
>>> Nova team needs to consider interoperability between clouds so well
>>> because Nova API is one of general external interfaces for end users.
>>> On the other hand, Ironic API is for administrators, not for end users.
>>> I am imaging that:
>>> * Some administrator wrote his application for using Ironic API.
>>> * From the viewpoint of administrator, the switching destination cloud
>>> in newer in most cases.
>>> * The application can continue working on newer clouds even after
>>> switching many times.
>>> So I feel the above interoperable issue example would not happen on
>>> Ironic in most cases unless hiding backwards compatible changes on
>>> lower microversion.
>>> I guess this is the difference between Nova and Ironic on
>>> interoperability discussion.
>>> I cannot/don't want to enforce Ironic way at all, and it's fine to
>>> find the best way on each project as OSS projects.
>>> But only my concern here is that we cannot use "Microversions" as a
>>> perfect keyword for OpenStack interoperability on whole OpenStack
>>> projects if Ironic goes to the other way.
>>> Ken Ohmichi
>>> : https://dague.net/2015/06/05/the-nova-api-in-kilo-and-beyond-2/
>>> OpenStack Development Mailing List (not for usage questions)
>>> Unsubscribe: OpenStack-dev-request at lists.openstack.org?subject:unsubscribe
>> OpenStack Development Mailing List (not for usage questions)
>> Unsubscribe: OpenStack-dev-request at lists.openstack.org?subject:unsubscribe
> OpenStack Development Mailing List (not for usage questions)
> Unsubscribe: OpenStack-dev-request at lists.openstack.org?subject:unsubscribe
More information about the OpenStack-dev