[openstack-dev] [neutron] Purpose and documentation of the API

Ihar Hrachyshka ihrachys at redhat.com
Wed Dec 2 13:16:25 UTC 2015

Sean M. Collins <sean at coreitpro.com> wrote:

> 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

Another anecdote: sometimes your backend just cannot express what you  
expose thru API, so you do wild things like:


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

I agree we should define API explicitly, not thru use cases. Isn’t that  
what we actually look for?


If you ask me, it’s indeed lack details, and show define expected behaviour  
more clearly.

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

Right. Though it does not answer the question of how plugins should  
implement those extensions once they opt in the game.

>> 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
> __________________________________________________________________________
> OpenStack Development Mailing List (not for usage questions)
> Unsubscribe: OpenStack-dev-request at lists.openstack.org?subject:unsubscribe
> http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev

More information about the OpenStack-dev mailing list