[openstack-dev] [api] [Nova] [Ironic] [Magnum] Microversion guideline in API-WG

Dmitry Tantsur dtantsur at redhat.com
Thu Jun 25 08:31:21 UTC 2015


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, and
>> 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 version
>> is incompatible with the maximum supported version.  It does this by
>> rewriting responses to match what was expected in the requested (older)
>> version.
>>
>> 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 in
>> 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 not
>> 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 that
>> a change was made in v1.5 that added a new endpoint. Today, this is what the
>> 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: 1.2)
>> b) client requests v1.4, receives headers (min: 1.1, max: 1.5, current 1.4)
>> c) client requests v1.5, receives headers (min: 1.1, max: 1.5, current: 1.5)
>>
>> What we have implemented today is that in case (b), the service will *hide*
>> any changes that we introduced in v1.5. But those changes did not affect any
>> 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 the
>> last several months working on api versioning, I actually think all of those
>> 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.
>>
>> Discuss.
>
> 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[1] 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.

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

>
> 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
> microversion.
> 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.
>
> Thanks
> Ken Ohmichi
>
> ---
> [1]: 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
> http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev
>




More information about the OpenStack-dev mailing list