Open Stack

Sometimes when I'm discussing or reviewing proposed specs, I feel as
though I may have incorrect assumptions about what the Neutron API is
_for_.  And certainly I feel that we lack good unified documentation of
it - or at least, that I haven't yet found that documentation, if it
exists.  So I'd like to start a conversation about that here.

_What is important: the API, or documented use cases?_

Being theoretically inclined, I tend to assume that if an API exists, it
is the primary thing, and hence that everything that is expressible in
that API should make sense and be implemented by at least some
implementations.  (It's fine for the API to explicit exclude certain
combinations of properties or calls; those exclusions then become part
of the definition of 'the API'.  It's also fine for particular
implementations only to implement a subset of the API.)

But a perfectly consistent alternative position would be to say that
that is _not_ the case with the Neutron API, and - rather - what really
matters is our set of documented use cases [1].  If that was the view,
then the API would simply be a piece of how we provide those use cases,
and anything _else_ that the resulting API happened to be able to
express would be regarded technically as an accident or 'unspecified
behavior'.

[1] http://docs.openstack.org/networking-guide/deploy.html

Which of those positions do we actually take?  (What is the overall
contract that Neutron provides to the rest of the OpenStack world?)

If it's the latter, then much of the rest of this email may be moot. 
But I'll write it anyway in case it's the former - i.e. that we believe
the Neutron API is important as a more general thing than just the
documented use cases - or in case it's interesting for other reasons.

_What should be expressed on the Neutron API?_

My first intuition is that the Neutron API should _only_ describe the
connectivity and networking services that it provides to instances - L2,
L3, security, service chains, DNS, DHCP etc. etc. - and primarily this
is indeed what it does.  But it only takes a slightly longer look to see
other things that are not part of specifying the connectivity or
services that can be observed by instances, but instead directions to
the (assumed) implementation about how that connectivity should be
implemented.  For example, the 'provider' API extension is entirely in
the latter camp.

So in practice it seems we use the Neutron API for two purposes:

1. To describe the connectivity and networking services that Neutron
provides to instances.

2. As a convenient central distribution point for instructions to
assumed networking implementations.

Is that right, as a description of current reality?

Is it right, in terms of what we _should_ be doing?  Should we, for
example, perhaps have a clearer formal separation between (1) and (2)?

_Documentation_

Whatever is the consensus on the questions raised here, I'd like that to
be explicitly recorded somewhere, and volunteer to do that.  Not sure
yet whether that should be in the Neutron devref, or in the networking
guide - opinions welcome!

Also, if we agree that the Neutron API is a primary thing, I think we
should have some unified documentation of it that explains what all the
data model objects mean.  I'm not sure I can do all of that myself, but
I'd be happy to make a start - so again, opinions welcome on where and
how to do that.

Apologies if either of these things already exists - in that case please
just point to them.


Thanks for reading!  Please let me know what you think.

    Neil