Open Stack

There have now been a few iterations on the specification for Neutron
micro-versioning [1].
It seems that no-one in the community opposes introducing versioning. In
particular API micro-versioning as implemented by Nova and Ironic seems a
decent way to evolve the API incrementally.

What the developer community seems not yet convinced about is moving away
from extensions. It seems everybody realises the flaws of evolving the API
through extensions, but there are understandable concerns regarding impact
on plugins/drivers as well as the ability to differentiate, which is
something quite dear to several neutron teams. I tried to consider all
those concerns and feedback received; hopefully everything has been
captured in a satisfactory way in the latest revision of [1].
With this ML post I also seek feedback from the API-wg concerning the
current proposal, whose salient points can be summarised as follows:

#1 extensions are not part anymore of the neutron API.

Evolution of the API will now be handled through versioning. Once
microversions are introduced:
   - current extensions will be progressively moved into the Neutron
"unified" API
   - no more extension will be accepted as part of the Neutron API

#2 Introduction of "features" for addressing diversity in Neutron plugins

It is possible that the combination of neutron plugins chosen by the
operator won't be able to support the whole Neutron API. For this reason a
concept of "feature" is included. What features are provided depends on the
plugins loaded. The list of features is hardcoded as strictly dependent on
the Neutron API version implemented by the server. The specification also
mandates a minimum set of features every neutron deployment must provide
(those would be the minimum set of features needed for integrating Neutron
with Nova).

#3 Advanced services are still extensions

This a temporary measure, as APIs for load balancing, VPN, and Edge
Firewall are still served through neutron WSGI. As in the future this API
will live independently it does not make sense to version them with Neutron
APIs.

#4 Experimenting in the API

One thing that has plagued Neutron in the past is the impossibility of
getting people to reach any sort of agreement over the shape of certain
APIs. With the proposed plan we encourage developers to submit experimental
APIs. Experimental APIs are unversioned and no guarantee is made regarding
deprecation or backward compatibility. Also they're optional, as a deployer
can turn them off. While there are caveats, like forever-experimental APIs,
this will enable developer to address user feedback during the APIs'
experimental phase. The Neutron community and the API-wg can provide plenty
of useful feeback, but ultimately is user feedback which determines whether
an API proved successful or not. Please note that the current proposal goes
in a direction different from that approved in Nova when it comes to
experimental APIs [3]

#5 Plugin/Vendor specific APIs

Neutron is without doubt the project with the highest number of 3rd party
(OSS and commercial) integration. After all it was mostly vendors who
started this project.
Vendors [4] use the extension mechanism to expose features in their
products not covered by the Neutron API or to provide some sort of
value-added service.
The current proposal still allows 3rd parties to attach extensions to the
neutron API, provided that:
- they're not considered part of the Neutron API, in terms of versioning,
documentation, and client support
- they do not redefine resources defined by the Neutron API.
- they do not live in the neutron source tree
The aim of the provisions above is to minimize the impact of such
extensions on API portability.

Thanks for reading and thanks in advance for your feedback,
Salvatore

The title of this post has been inspired by [2]  (the message in the banner
may be unintelligible to readers not fluent in european football)

[1] https://review.openstack.org/#/c/136760/
[2]
http://a.espncdn.com/combiner/i/?img=/photo/2015/0502/fc-banner-jd-1296x729.jpg&w=738&site=espnfc
[3]
http://specs.openstack.org/openstack/nova-specs/specs/kilo/implemented/api-microversions.html
[4] By "vendor" here we refer either to a cloud provider or a company
providing Neutron integration for their products.
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.openstack.org/pipermail/openstack-dev/attachments/20150506/31939628/attachment.html>