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

Devananda van der Veen devananda.vdv at gmail.com
Fri Jun 26 14:58:07 UTC 2015


Dmitry,

Feature strings won't work. It only makes things more complex, without
addressing the underlying issue.

What happens when we change, even in a small way, the API surface exposed
by an existing feature? How is that change exposed -- unless we include a
version number along with your feature string? And now we're right back
where we started.

-Deva

On Fri, Jun 26, 2015, 07:41 Dmitry Tantsur <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.
>
> >
> > 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
> >
>
>
> __________________________________________________________________________
> 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
>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.openstack.org/pipermail/openstack-dev/attachments/20150626/61694cbf/attachment.html>


More information about the OpenStack-dev mailing list