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

Dmitry Tantsur dtantsur at redhat.com
Fri Jun 26 15:10:09 UTC 2015

On 06/26/2015 04:57 PM, Joe Gordon wrote:
> On Fri, Jun 26, 2015 at 7:39 AM, Dmitry Tantsur <dtantsur at redhat.com
> <mailto:dtantsur at redhat.com>> wrote:
>     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.
> Does Ironic have a document explaining each API version? I quick search
> in the source tree didn't turn anything up. Being able to easily figure
> out what each API version do is important for end users.  As a user,
> when I see the cloud I use now supports nova API 2.26 I want an easy way
> of figuring out what that actually means.

I think we don't.

> To address this, nova has the following document:
> http://docs.openstack.org/developer/nova/api_microversion_history.html

Btw 2.3 looks big, were it really one feature (and one commit, as we're 
talking about people deploying from master)?

>         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.
> Nova has already been down that path, our microversion spec discusses a
> few of the issues we found (It doesn't go into a lot of detail though):
> http://specs.openstack.org/openstack/nova-specs/specs/kilo/implemented/api-microversions.html#problem-description
> Additionally the extensions model doesn't support backwards incompatible
> changes.

Fair, this model is also not good.

>                  -Sean
>     __________________________________________________________________________
>     OpenStack Development Mailing List (not for usage questions)
>     Unsubscribe:
>     OpenStack-dev-request at lists.openstack.org?subject:unsubscribe
>     <http://OpenStack-dev-request@lists.openstack.org?subject:unsubscribe>
>     http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev
> __________________________________________________________________________
> 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