Sean M. Collins <s...@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
DEPLOYMENTS DANGIT!
Another anecdote: sometimes your backend just cannot express what you
expose thru API, so you do wild things like:
https://github.com/openstack/neutron/blob/0381e290d088389702ed176fbaeb45b95102648c/neutron/plugins/ml2/drivers/mech_sriov/agent/eswitch_manager.py#L186
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?
http://developer.openstack.org/api-ref-networking-v2.html
http://developer.openstack.org/api-ref-networking-v2-ext.html
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-requ...@lists.openstack.org?subject:unsubscribe
http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev
__________________________________________________________________________
OpenStack Development Mailing List (not for usage questions)
Unsubscribe: openstack-dev-requ...@lists.openstack.org?subject:unsubscribe
http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev
