Open Stack

Hey everybody!

I have submitted two potential goals for Queens:

https://review.openstack.org/#/c/468436 - add collection links
https://review.openstack.org/#/c/468437 - full discovery alignment

One is a subset of the other, so the decision is two-fold

* do we do this at all?
* do we do the smaller or the larger of the two?

Both of these are work driven by the version-discovery API-WG specs, 
which are in turn driven by trying to improve the interop story for our 
APIs to include more SDKs/libs than just shade. So the overall story 
here is "implement things to improve life for folks consuming the 
catalog and version discovery"

Quick summaries:

Add Collection Links
--------------------

This is the simpler of the two. It involves adding a "collection" link 
to the list of links in the version discovery documents. That is, this:


     {
       "version": {
         "id": "v2.0",
         "links": [
           {
             "href": "https://image.example.com/v2",
             "rel": "self"
           }
         ],
         "status": "CURRENT"
       }
     }

Becomes this:

     {
       "version": {
         "id": "v2.0",
         "links": [
           {
             "href": "https://image.example.com/v2",
             "rel": "self"
           },
           {
             "href": "https://image.example.com/",
             "rel": "collection"
           }
         ],
         "status": "CURRENT"
       }
     }

The reason for this is as a path to the unversioned discovery document 
on clouds where the versioned endpoint is the thing that's in the 
catalog. The current way to do that is to take the versioned endpoint 
and pop things off of the end.

'collection' is proposed for the rel name. From the list of official 
names: 
https://www.iana.org/assignments/link-relations/link-relations.xhtml it 
seems like the best choice. (If a single-version version document is a 
"Version", then the list of those in the unversioned document seems like 
the "collection" of them)

This one should be _very_ little work per-project. I took a stab at 
implementing this for nova while sitting in the goals room in Boston and 
without any knowledge of how version discovery works in nova I got most 
of it done in about 15 minutes.

Full Discovery Alignment
------------------------

Full discovery alignment includes the collection link work, but also 
includes a few more things. There isn't a TON more per-project coding 
work. Most of the openstack-side work is in adding support to 
keystoneauth - and I've already written most of those patches. The other 
main bit of work is in updating SDKs and libs for other languages to 
implement the consumption support as well - but we've made good contacts 
with folks and can get that done (and will, regardless of the goal)

The main per-project additional things to do after the keystoneauth 
patches land on top of the collection link are:

* modifying devstack plugins and deployment projects to register the 
service using the official name from the service-types-authority
* modifying devstack plugins and deployment projects to register the 
unversioned endpoint in the catalog
* modifying devstack and plugins to stop using "RegionOne" as the region 
name

The goal also calls out a few specific tempest tests we need to write to 
verify discovery works as expected across the board.

I *think* the Full Alignment goal is doable and not a terrible amount of 
per-project work. But as with everything, it is work.

Thoughts?
Monty