Open Stack

On Tue, Jul 28, 2015 at 08:05:49PM +0000, Devananda van der Veen wrote:
> I'm going to reply to several emails in this thread - but separately,
> because they're from separate people and with separate POV, and I think it
> will be even harder to discern what I'm saying if I merge the contexts
> before replying... so bear with me ...
> 
> 
> On Mon, Jul 27, 2015 at 1:36 PM Jim Rollenhagen <jim at jimrollenhagen.com>
> wrote:
> 
> > Hi friends.
> >
> > Ironic implemented API "micro" versions in Kilo. We originally did this
> > to allow for breaking changes in the API while allowing users to opt in
> > to the breakage.
> >
> > Since then, we've had a "default version" for our client that we bump to
> > something sensible with each release. Currently it is at 1.8.
> > Negotiation is done with the server to figure out what is supported and
> > adjust accordingly.
> >
> > Now we've landed a patch[0] with a new version (1.11) that is not
> > backward compatible.
> 
> 
> No, that patch isn't backwards compatible -- ** but it could be **.
> 
> That's the biggest reason that I disagree with what's proposed here -- it
> would be trivially easy for us to make this change be backwards compatible
> by allowing an optional parameter in the POST command that changes the
> initial state of a node from AVAILABLE to ENROLL.
> 
> Allow users to opt-in to the new behavior *and* discover its presence from
> the API version header. There is simply no reason for this to be a breaking
> change. I simply do not understand how folks think "we can version the API"
> means "we should break users even when we don't have to".

I tend to think specifying that version *is* opting in.

> 
> Anyway, I've said that before. There are other points I want to respond to
> as well, so I'll carry on...
> 
> 
> 
> > It causes newly added Node objects to begin life in
> > the ENROLL state, rather than AVAILABLE. This is a good thing, and
> > people should want this! However, it is a breaking change. Automation
> > that adds nodes to Ironic will need to do different things after the
> > node-create call.
> >
> > Our API versioning scheme makes this opt-in (by specifying the API
> > version). However, some folks have a problem with releasing this change
> > as-is. The logic is that we might release a client that defaults to 1.11
> > or higher, or the user may request 1.12 later to get a new feature, thus
> > breaking their application that enrolls nodes.
> >
> 
> The current approach is supposed to allow users "to make use of new
> features as they become available, while also ensuring they don’t break due
> to incompatibilities" [0] However, you're advocating against providing that
> right now -- if a user wants a feature added in 1.12, they will be forced
> to accept the breaking change in 1.11.

I believe stating that users won't put in work to make their software
work with the breaking change in 1.11, but will put in work to use a
feature in 1.12, is a bit of a logical fallacy. However, even if someone
gets themselves into that situation, there's nothing wrong with them
using <1.11 for the call that breaks them, and 1.12 for the others.

> 
> While I have proposed some changes to our specification for API versioning
> [1], removing this statement of intent is not one of the changes I've
> proposed.
> 
> [0]
> http://specs.openstack.org/openstack/ironic-specs/specs/kilo/api-microversions.html#problem-description
> 
> [1]
> https://review.openstack.org/#/c/196320/2/specs/devref/api-version-negotiation.rst,cm
> 
> 
> >
> > This is clearly backwards. Users should read release notes and be aware
> > of what changes between versions in the API. Users need to be aware of
> > the fact that our API is versioned, and use that to their advantage.
> >
> 
> You're conflating "user" and "operator" -- which I understand, because you
> are both. But not everyone is, and I'm concerned about the impact on "users
> who are not operators". I'd say maybe we have none of those, except then I
> hear from folks like Clint that they care about this sort of change and how
> it affects them.

In an admin-only API, I tend to think operators and users are very
close, if not the same.

I also think that:

1) API version things, especially incompatibilities, should also be in
   the release notes for the client.
2) Operators should be distributing release notes that affect users to
   the users. When I deploy a new version of Ironic, I certainly
   distribute a note with any changes other users/operators should be
   aware of.

> 
> 
> >
> > It seems to me that the goal of the version negotiation in our client
> > has been to pretend that our API versions don't exist, from a user
> > perspective. We need to stop doing this and force users to think about
> > what they are doing when they interact with our API.
> >
> 
> The intent is to allow users' tooling to continue working while we evolve
> the REST API *and* to give users the ability to work with both old and new
> service installations (eg, because the user doesn't control what version of
> server they are using).

If the user pins the version, this just works.

> 
> Again, that goal is based on the assumption that some users are not also
> operators.
> 
> 
> >
> > It seems to me we have a few options here:
> >
> > 1) Default the python client and CLI to the earliest supported version.
> > This will never break users by default.
> >
> > 2) Default the python client and CLI to use the special version
> > 'latest'. This will always use the latest API version, and always
> > break people when a new server version (that is not backwards
> > compatible) is deployed.
> >
> 
> In an environment where a user is interacting with >1 Ironic service of
> different versions, this default would lead to what I'll just call "odd"
> behavior. It ends up being your option 4 implicitly, to avoid frustration.
> 
> 
> >
> > 3) Do what Nova does[1]. Default CLI to latest and python client to
> > earliest. This assumes that CLI is typically used for one-time commands
> > (and it isn't a big deal if we break a one-off command once), and the
> > python client is used for applications.
> >
> > 4) Require a version to use the client at all. This would be a one-time
> > break with how applications initialize the client (perhaps we could fall
> > back to the earliest version or something for a deprecation period).
> > This isn't a great user experience, however, it's the best way to get
> > users to think about versioning. And no, "this requires typing another
> > argument every time!" is not a valid argument against this; we already
> > require a number of arguments, anyone sane doesn't type --ironic-api-url
> > or --os-username every time they use the client.
> >
> 
> Do you think about what version of XMPP protocol this or that service
> implements? Your XMPP client certainly does, if you use a client that can
> talk to both hangouts and facebook and $(insert any other of a dozen
> variants here). You, as the user, have to tell your client "this account
> uses the FB variant of XMPP". I don't think users of Ironic (or more
> generally, users of OpenStack) want to have to think about that.

If I'm writing an application, I would certainly think about it. I tend
to think this example is solved by something like supernova:
https://github.com/major/supernova

// jim

> 
> 
> > 5) Do what we're doing now. Bump the client's default version with every
> > release. This mostly hides these versions from end users, and in general
> > those users probably won't know they exist. And then we run into
> > arguments every time we want to make a breaking change to the API. :)
> >
> > I think I like option 1 or 3 the best. I certainly don't like option 5
> > because we're going to break users every time we release a new client.
> >
> > What do other folks think we should do?
> >
> > // jim
> >
> > [0]
> > https://github.com/openstack/ironic/commit/1410e59228c3835cfc4f89db1ec482137a3cfa10
> > [1]
> > http://specs.openstack.org/openstack/nova-specs/specs/liberty/approved/novaclient-api-microversions.html
> >
> > __________________________________________________________________________
> > 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
> >

> __________________________________________________________________________
> 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