Open Stack

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".

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.

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.


>
> 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).

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.


> 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
>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.openstack.org/pipermail/openstack-dev/attachments/20150728/d2afe4a1/attachment.html>