On 07/27/2015 10:41 PM, Sean Dague wrote:
On 07/27/2015 04:35 PM, Jim Rollenhagen 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. 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.
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.
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.
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.
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.
Actually what Nova is doing is slight different than this, the CLI will
default to "latest" on the server. There will be an extra round trip to
figure out what that is. And the CLI will (long term) just not present
commands that aren't available at the server level you are talking to.
Consider the CLI an auto negotiating microversion application of the
python API client. And, realistically, should solve some of the issues
of people running "nova foo" and getting cryptic errors from the server
when they are hitting an old version of Nova that doesn't know how to foo.
So the CLI should actually break less often, and will expose the most
functionality you can get out of your cloud.
What I find weird about this and similar approaches is that we treat CLI
and any different from other ways to use API. And I *suspect* this is
because we, the developers, use it the most and point newcomers to it.
And I agree it's troublesome to explain that to use "manage" provision
verb you have to provide --ironic-api-version 1.6. Or was 1.6 for
inspect? Hmm, I really don't remember.
CLI is not different, CLI is not special and CLI is not "an auto
negotiating microversion application of the python API client". By
saying any of these we just refusing it eat our dog's food. If we
consciously believe (I personally don't) that versioning is the right
thing to do for people using our API - lets stop dodging it ourselves.
Otherwise it looks like we've invented an architecture that people
presumably dream of, but we don't know if it's even usable (to say
nothing about useful). I tried writing versioning-aware code for our
devstack yesterday, and it wasn't that nice and shiny.
If our versioning requires negotiations, lets have it on API level, so
that all users get it. Actually, server has the same level of
information as the client. Let's have "X-OpenStack-XXX-Version:
negotiate" figure out a proper version for us - or refuse to process a
request if it's not possible. And if we think that versioning as it is
now is unusable at all, lets rework the whole idea.
tl;dr my vote if for CLI to strictly follow whatever server API does.
That is, default to the lowest version, require explicit version
argument to get new features. (it's up to a follow up discussion what to
do during the deprecation period).
-Sean
__________________________________________________________________________
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
