[openstack-dev] [neutron] Purpose and documentation of the API
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 . 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
>>  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
> 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.
> 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!
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:
>> 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
>> _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)?
>> 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:
> Sean M. Collins
> OpenStack Development Mailing List (not for usage questions)
> Unsubscribe: OpenStack-dev-request at lists.openstack.org?subject:unsubscribe
More information about the OpenStack-dev