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

Dmitry Tantsur dtantsur at redhat.com
Fri Jun 26 11:43:27 UTC 2015

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.

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.

> If we were only working on a single install of OpenStack in the world,
> like EC2, github, meetup, or any other proprietary API service out
> there, it would be a different story. We'd control time's arrow, and
> never would have to worry about "going back in time". But we're not
> working on that. We're working on software we hope will bloom 10,000+
> clouds. At all scales. And the challenge to provide a consistent
> programming experience for application writers that want to work against
> any of those clouds means we needed to come up with some new models here.
> If you have other solutions to the time's arrow issue, that would be
> great to here. But it is the crux of why the model looks like it does.

I see, thanks for explanation.

> 	-Sean

More information about the OpenStack-dev mailing list