Open Stack

Our current top level shipped example paste.ini for Nova includes the
following set of endpoint definitions:

[composite:osapi_compute]
use = call:nova.api.openstack.urlmap:urlmap_factory
/: oscomputeversions
/v1.1: openstack_compute_api_v2
/v2: openstack_compute_api_v2
/v2.1: openstack_compute_api_v21
/v3: openstack_compute_api_v3


The real question I have is what should this look like in the Kilo
release. And this has a couple of axes.

 Who uses our paste.ini?
=========================

paste.ini is an etc file, so we assume that during upgrade you'll be
using your existing config. Changes to the default paste.ini will
really only be effective in new deploys. So this should not impact
existing users, but instead only new users.

Cleaning up Cruft
=================

Drop of /v3
-----------

v3 is no longer a supported thing. I think v3 in the paste.ini causes
confusion. It also causes us to keep around untested / unsupported
code.

This seems kind of a no brainer.

Drop of /v1.1 ?
---------------

Only new deploys are really going to base off of our in tree
config. I'm not convinced that we want to encourage people setting up
new /v1.1 endpoint in tree.

I'm not convinced there is a deprecation path here because the ones I
could imagine would involve people changing their paste.ini to include
a deprecation checking piece of code.

Honestly, I don't care strongly either way on this one. It's cruft,
but not dangerous cruft (unlike v3).

Nova v2
=======

This is where things get interesting.

v2.1 is supposed to be equivalent to v2. The difference is moving the
validation for datastructures from the database to the wsgi layer. The
ways in which this doesn't react like the existing APIs should be
basically not letting you create corrupt data models which will
explode later in unexpected and hard to determine ways. The reality is
objects validation has been sneaking this in all along anyway.

The full monty approach
-----------------------

[composite:osapi_compute]
use = call:nova.api.openstack.urlmap:urlmap_factory
/: oscomputeversions
/v1.1: openstack_compute_api_v2
/v2: openstack_compute_api_v21
# starting in Kilo the v21 implementation replaces the v2
# implementation and is suggested that you use it as the default. If
# this causes issues with your clients you can rollback to the
# *frozen* v2 api by commenting out the above stanza and using the
# following instead::
# /v2: openstack_compute_api_v2
# if rolling back to v2 fixes your issue please file a critical bug
# at - https://bugs.launchpad.net/nova/+bugs

This would make the v2 endpoint the v21 implementation for new
deploys. It would also make it easy for people to flip back if they
hit an edge condition we didn't notice.

In functional testing we'd still test both v2 and v2.1

Tempest would move to v2.1 by default, and I think we should put an
old v2 job on nova stable/kilo -> master to help us keep track of
regressions.

The slow roll approach
----------------------

Ship the existing file (minus v3):

[composite:osapi_compute]
use = call:nova.api.openstack.urlmap:urlmap_factory
/: oscomputeversions
/v1.1: openstack_compute_api_v2
/v2: openstack_compute_api_v2
/v2.1: openstack_compute_api_v21

The advantages here is that out of the box stuff keeps working. The
dilema here is it's not really clear that we'll get people poking at
v2.1 because it will be out of the main path. The point of the
microversioning was to get folks onto that train soon because it falls
back to existing API. And once we are convinced we're good we can
deprecate out the old implementation.

Also, things like out of tree EC2 support requires v2.1, which is
going to make deploys start relying on a /v2.1 endpoint that want EC2,
so our options for grafting that back onto /v2 in the future are more
limitted.

Decision Time
=============

Anyway, this is a decision we should make before freeze. The 'no
decision' case gives us the slow roll. I think from an upstream
perspective the full monty will probably serve us a little
better. Especially with robust release notes that explain to people
how to move their endpoints forward.


	-Sean

-- 
Sean Dague
http://dague.net