Open Stack

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
> 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-request at lists.openstack.org?subject:unsubscribe
> http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev