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 <j...@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-requ...@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-requ...@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-requ...@lists.openstack.org?subject:unsubscribe http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev
