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

Dmitry Tantsur dtantsur at redhat.com
Fri Jun 26 14:39:33 UTC 2015

On 06/26/2015 04:08 PM, Sean Dague wrote:
> On 06/26/2015 07:43 AM, Dmitry Tantsur wrote:
>> On 06/26/2015 01:14 PM, Sean Dague wrote:
>>> On 06/16/2015 09:51 AM, Dmitry Tantsur wrote:
>>>> On 06/16/2015 08:56 AM, Dmitry Tantsur wrote:
>>>>> To sum this long post up, I'm seeing that hiding new features based on
>>>>> microversions brings much more problems, than it solves (I'm not aware
>>>>> of the latter at all). I'm very opposed to continuing doing it in
>>>>> Ironic, and I'm going to propose patch stopping gating Kilo changes
>>>>> (non-breaking obviously).
>>>> I'm talking about this patch: https://review.openstack.org/#/c/192196/
>>>> We have to do it right now, as otherwise we can't test inspection in
>>>> tempest (it does not seem to be microversion-aware).
>>> Dmitry,
>>> How do you solve for the following situation?
>>> 2 Clouds (A and B), both being Continuously Deployed.
>>> Assume both clouds start at same revision of code. At point in time T a
>>> new "compatable change" is added to the API. For instance, another field
>>> returned by some resource.
>>> Cloud B upgrades to that change.
>>> Brand new developer shows up. Starts writing application against Cloud
>>> B. Sees that change is available at version 1.4. Hard codes her
>>> application to use this parameter.
>>> Then she points her application at Cloud A. And it explodes.
>> I clearly agree that my solutions do not solve this situation. Neither
>> does yours. Now let us see:
>> A compatible change is getting added and is guarded behind version 1.5.
>> A new developer starts requiring this new version, because she needs
>> this new feature (that's your assumption).
>> Then she points her application at cloud A. And it explodes. But with
>> different error message and probably a bit earlier. But explodes.
>> Which, by the way, means we still must know precisely which API version
>> is served by all clouds we might apply our utility to.
> But it fails with "Your application is attempting to use API 1.5 which
> is not supported in this cloud". Because if you don't specify a version,
> you get the base 1.0, and never had new features.
> That's an error which is extremely clear to understand what went wrong.
> Has docs to figure out if the application could work at an earlier
> release version, and provides the ability for the client to do some
> selection logic based on supported versions.

I agree that error is clear. I'm not sure it's worth doing despite all 
the problems that I mentioned in the beginning of this thread. In 
particular, situation around official CLI and testing.

E.g. do you agree with Jim that we should make API version a required 
argument for both CLI and Python library?

> 	-Sean
>> So I agree, hitting API version error could make a person realize that a
>> change to the utility is no longer compatible with the current version
>> of API. So if this change wasn't intended - fine. If it was (which is
>> the most likely situation), it won't help you.
>> By the way, I've heard some people wanting to deprecate API version with
>> time. If we do so, it will open some new horizons for breakages.
>> If we don't, we'll soon end put with dozens of version to support and
>> test. How to solve it? (in Ironic IIRC we just only gate test one
>> version, namely Kilo aka 1.6, which is very, very bad IMO).
>>> I feel like in your concerns there has been an assumption that the
>>> operation across all clouds effectively always goes forwards. But
>>> because we're trying to encourage and create a multicloud ecosystem a
>>> user application might experience the world the following way.
>>> Cloud A -> Cloud A' -> Cloud A'' -> Cloud D -> Cloud B' -> Cloud C ->
>>> Cloud C'.
>> I think that versioning actually encourages this (wrong) assumption.
>> Because versions grow with time naturally, and we, the developers, like
>> new and shiny stuff so much :) see below for my alternative idea.
>>> While no individual cloud is likely to downgrade code (though we can't
>>> fully rule that out), the fact that we'd like applications to work
>>> against a wide range of deployments means effectively applications are
>>> going to experience the world as if the code bases both upgrade and
>>> downgrade over time.
>>> Which means that a change is only "compatable" if the inverse of the
>>> change is also "compatable". So a field add is only compatable if the
>>> field delete is also considered compatible, because people are going to
>>> experience that when they hop to another cloud.
>>> Which is also why feature hiding is a thing. Because we don't control
>>> when every cloud is going to upgrade, and what they'll upgrade to. So
>>> the best idea so far about getting this right is that API 1.4 is
>>> *exactly* a specific surface. Features added in 1.5 are not visibile if
>>> you ask for 1.4. Because if they were, and you now wrote applications
>>> that used that bleed through, when you jump to a cloud without 1.5 yet
>>> deployed, all your application code breaks.
>> Note that if you rely on version 1.4 with feature hiding, your
>> application will also break. I.e. I agree it's a valid situation to fix,
>> I just don't see feature hiding fixing *all* cases of this problem.
>> While an API exposing feature explicitly might be more handy, imagine e.g.
>> $ curl http://ironic.host/v1/features
>> ['inspection', 'raid', ...]
>> Exposing interface like that would encourage people to think about their
>> application in terms of mandatory and optional features, not some numbers.
> Yes, version number is being used as a proxy for a feature description.
> Which is what version numbers are used for in software. It's a way to
> let people think about bundles of things, instead of having to mentally
> map out every single feature in their head.

Why do you think it's good? People are using features, not numbers. They 
don't need to map out features - on the contrary they do need to map 
versions to features. We've reached 1.8 with Ironic - and I (the core) 
don't remember what were these version about, except for 1.6.

> Maybe we can some day to a place where we can have an API that's fully
> feature describing, and doesn't need numbers. But after 2.5 years of
> trying to do a major rewrite of the Nova API, it was pretty clear that
> APIs of any reasonable size just can't do that. And can't rely on
> software to keep up with your changes. This provides a mechanism for
> evolution with a stability contract that API 1.4 is going to keep
> looking exactly the same over time. So you can upgrade client code on
> your schedule, not on the schedule of the server upgrades.

I don't see any problem with creating an API serving list of strings, 
and then making contributors update this list every time they change 
API. It's the same as making contributors bump version number.

> 	-Sean

More information about the OpenStack-dev mailing list