[openstack-dev] [api] [Nova] [Ironic] [Magnum] Microversion guideline in API-WG
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:
> We have to do it right now, as otherwise we can't
> test inspection in
> tempest (it does not seem to be microversion-aware).
> 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
> 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
> is not supported in this cloud". Because if you don't specify a
> you get the base 1.0, and never had new features.
> That's an error which is extremely clear to understand what went
> 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?
> 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)
> Because versions grow with time naturally, and we, the
> developers, like
> new and shiny stuff so much :) see below for my alternative
> 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
> 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
> 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
> 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
> 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:
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
> 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
> 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):
> Additionally the extensions model doesn't support backwards incompatible
Fair, this model is also not good.
> OpenStack Development Mailing List (not for usage questions)
> OpenStack-dev-request at lists.openstack.org?subject:unsubscribe
> OpenStack Development Mailing List (not for usage questions)
> Unsubscribe: OpenStack-dev-request at lists.openstack.org?subject:unsubscribe
More information about the OpenStack-dev