Open Stack

On Tue, Dec 01, 2015 at 07:16:00AM EST, Neil Jerram wrote:
> _What is important: the API, or documented use cases?_

Both are important - however I think I understand what you are trying to
tease out.

> 
> 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.)

No - you cannot implement only a subset of the API. For the Networking
API - that means that you must honor the Port, Network, and Subnet
API constructs. I think that's really it.

Everything else, like the Security Group API, L3, etc is an API
extension, which anyone can choose to implement, or not.

> 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?)


The problem with Neutron is that in a lot of implementations, there is a
ton of "unspecified" or "implicit" behavior. A lot of that is baked into
the reference implementation and as a result it colors perceptions of
the API itself.

A great example: the FwaaS API, in the reference implementation would
apply the firewall policy to all routers a tenant owned. Then later it
was chanced so you'd have to associate a router with a firewall policy.
The point being that now everyone who looks at the API thinks "oh, the
FwaaS API only works at the router level - what if I have a virtual firewall 
appliance that I want to use - or what if I want to filter at the port
level?" - and the answer is "You can't currently with our FwaaS API as
it exists now"

Another anecdote: Kevin Benton and I had a similar conversation with
someone on IRC about this.

http://eavesdrop.openstack.org/irclogs/%23openstack-neutron/%23openstack-neutron.2015-11-25.log.html#t2015-11-25T18:39:15

The tl;dr is that on RAX's Neutron you connect to a public external
network and it is unicast only.

The reason I bring this up is because the API MUST BE THE SAME ACROSS
DEPLOYMENTS DANGIT!

If I have two API endpoints for Neutron and they behave wildly
differently and the behavior is not actually documented at the API
level, that is a serious problem.  If I list a network and its
attributes and they are identical yet they behave differently, where one
has multicast and another doesn't then the API is not explicit enough
about these behaviors and as a user this is terrible. Which I guess is
why Monty is doing work on Shade:

http://docs.openstack.org/infra/shade/


> 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.

So, I at least believe that it is the former.

> 
> _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.

A pedantic note - the Neutron core API only handles Ports, Networks, and
Subnets. Everything else you listed is an API extension which is
optional for an implementation to implement. Which, most do, and we have
had discussions about "When does an API extension that is implemented by
everyone not become optional?"


> 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?

Sounds correct to me.


> 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!


The Networking guide is part of the solution, but we also have some
serious issues about the API documentation currently, and I asked on
openstack-doc about it a little while ago:

http://lists.openstack.org/pipermail/openstack-docs/2015-November/007777.html

-- 
Sean M. Collins