Open Stack

Excerpts from Sean Dague's message of 2015-07-27 13:41:20 -0700:
> 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 odd about this is that I want the CLI to be a faithful
representation of the API, because many times the CLI is the only way I
can access the API for integration purposes.

So lets say I just want a very simple bash script to do something with
nodes:

id=$(ironic node-create ...|getid)
while true ; do
  state=$(ironic node-get $id | get_state)
  case $state in
  AVAILABLE)
    break;;
  ERROR)
    # retry or something
    ;;
  *)
    splode("UNKNOWN STATE")
    ;;
  esac
done

Then the script is going to start exploding with a CLI that shows me
ENROLL state.

So I'm not sure having the CLI go faster than the python client is a
great way to avoid breakage. It might be the opposite of that, and that
might just be a large burden on users.