Thanks Mark. Please see minor comments inlined. Also: Acked-by: Han Zhou <[email protected]>
On Wed, Sep 25, 2019 at 10:33 AM Mark Michelson <[email protected]> wrote: > > This document serves to provide an explanation for how OVN will remain > compatible with OVS. It provides instructions for OVN contributors for > how to maintain compatibility even across older versions of OVS when > possible. > > It also creates a document to detail compatibility of specific OVN > versions. > > Signed-off-by: Mark Michelson <[email protected]> > --- > v2 -> v3: > * Removed RFC designation > * Added the compatibility document for specific versions of OVS and OVN > * Clarified compatibility concerns prior to the split > * Mentioned possibility of a change to OVS major version as a reason for > dropping compatibility. > * Clarified where warning messages should be output in the case that > feature incompatibility is detected. > * Added mention of "tested" and "untested" versions of OVS for > compatibility. > --- > Documentation/automake.mk | 1 + > Documentation/internals/contributing/index.rst | 1 + > .../contributing/ovs-ovn-compatibility.rst | 153 +++++++++++++++++++++ > Documentation/topics/index.rst | 1 + > Documentation/topics/ovs-compatibility.rst | 69 ++++++++++ > 5 files changed, 225 insertions(+) > create mode 100644 Documentation/internals/contributing/ovs-ovn-compatibility.rst > create mode 100644 Documentation/topics/ovs-compatibility.rst > > diff --git a/Documentation/automake.mk b/Documentation/automake.mk > index f7e1d2628..d9bd4be1f 100644 > --- a/Documentation/automake.mk > +++ b/Documentation/automake.mk > @@ -56,6 +56,7 @@ DOC_SOURCE = \ > Documentation/internals/contributing/documentation-style.rst \ > Documentation/internals/contributing/libopenvswitch-abi.rst \ > Documentation/internals/contributing/submitting-patches.rst \ > + Documentation/internals/contributing/ovs-ovn-compatibility.rst \ > Documentation/requirements.txt \ > $(addprefix Documentation/ref/,$(RST_MANPAGES) $(RST_MANPAGES_NOINST)) > FLAKE8_PYFILES += Documentation/conf.py > diff --git a/Documentation/internals/contributing/index.rst b/Documentation/internals/contributing/index.rst > index a46cb046a..7ef57a1e2 100644 > --- a/Documentation/internals/contributing/index.rst > +++ b/Documentation/internals/contributing/index.rst > @@ -36,3 +36,4 @@ The below guides provide information on contributing to Open vSwitch itself. > coding-style-windows > documentation-style > libopenvswitch-abi > + ovs-ovn-compatibility > diff --git a/Documentation/internals/contributing/ovs-ovn-compatibility.rst b/Documentation/internals/contributing/ovs-ovn-compatibility.rst > new file mode 100644 > index 000000000..0ff4f5ba9 > --- /dev/null > +++ b/Documentation/internals/contributing/ovs-ovn-compatibility.rst > @@ -0,0 +1,153 @@ > +.. > + Copyright (c) 2019 Red Hat, Inc. > + > + Licensed under the Apache License, Version 2.0 (the "License"); you may > + not use this file except in compliance with the License. You may obtain > + a copy of the License at > + > + http://www.apache.org/licenses/LICENSE-2.0 > + > + Unless required by applicable law or agreed to in writing, software > + distributed under the License is distributed on an "AS IS" BASIS, WITHOUT > + WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the > + License for the specific language governing permissions and limitations > + under the License. > + > + Convention for heading levels in Open vSwitch documentation: > + > + ======= Heading 0 (reserved for the title in a document) > + ------- Heading 1 > + ~~~~~~~ Heading 2 > + +++++++ Heading 3 > + ''''''' Heading 4 > + > + Avoid deeper levels because they do not render well. > + > +=============================== > +Keeping OVN Compatible with OVS > +=============================== > + > +This document discusses the general policy of compatibility between OVS and OVN. > +If you are looking for a listing of version compatiblity, please see s/compatiblity/compatibility > +:doc:`topics/ovs-compatibility` > + > +OVN has split from OVS. Prior to this split, there were few issues with > +compatibility. All code changes happened at the same time and in the same repo. > +New releases contained the latest OVS and OVN changes. The most commonon time s/commonon/common > +that compatibility typically came into question was during an upgrade; there > +might be a brief period where mismatched versions of OVS and OVN are running. > +That situation was transient. > + > +With OVN and OVS being developed and versioned separately, previous assumptions > +regarding compatibility are no longer valid. It is valid to permanently run a > +version of OVN that is different from the concurrent version of OVS. > + > +OVS and OVN versions > +-------------------- > + > +Prior to the split, the release schedule for OVN was bound to the release > +schedule for OVS. OVS releases a new version approximately every 6 months. OVN > +has not yet determined a release schedule, but it is entirely possible that it > +will be different from OVS. Eventually, this will lead to a situation where it > +is very important that we publish which versions of OVN are compatible with > +which versions of OVS. When incompatibilities are discovered, it is important to > +ensure that these are clearly stated. > + > +The split of OVS and OVN happened in the run-up to the release of OVS 2.12. As a > +result, all versions of OVN *must* be compiled against OVS version 2.12 or > +later. Before going further into compatibility, let's explore the ways that OVN > +and OVS can become incompatible. > + > +Compile-time Incompatibility > +---------------------------- > + > +The first way that the projects can become incompatible is if the C code for OVN > +no longer can compile. > + > +The most likely case for this would be that an OVN change requires a parallel > +change to OVS. Those keeping up to date with OVN but not OVS will find that OVN > +will no longer compile since it refers to a nonexistent function or out of date > +function in OVS. > + > +Most OVN users will consume OVN via package from their distribution of choice. > +OVN consumes libopenvswitch statically, so even if the version of OVS installed > +on a user's machine is incompatible at compile time, it will not matter. > + > +OVN developers are the only ones that would be inconvenienced by a compile-time > +incompatibility. OVN developers will be expected to regularly update the version > +of OVS they are using. If an OVN developer notices that OVN is not compiling, > +then they should update their OVS code to the latest and try again. > + > +Developers who are making changes to both OVS and OVN at the same time *must* > +contribute the OVS change first and ensure it is merged upstream before > +submitting the OVN change. This way, OVN should never be in a state where it > +will not compile. > + > +The other aspect to consider is compiling an older release of OVN against a > +newer release of OVS. In practice, this is not typically something that someone > +would want to do. However, if it is desired for some reason, then the ABI and > +API guarantees for OVS's libraries should allow for OVN to compile properly. An > +exception to this may be if OVS changes major versions. When OVS changes major > +versions, they reserve the right to make breaking changes to the API and ABI. > + > +Runtime Incompatibility > +----------------------- > + > +The next way that the projects may become incompatible is at runtime. The most > +common way this would happen is if new OpenFlow capabilities are added to OVS as > +part of an OVN change. In this case, if someone updates OVN but does not also > +update OVS, then OVN will not be able to install the OpenFlow rules it wishes > +to. > + > +Unlike with compile-time incompatibilities, we can't wallpaper over the fact > +that the OVS installation is not up to date. The best we can do is make it very > +clear at runtime that a certain feature is not present, and if the feature is > +desired, OVS must be upgraded. > + > +The following is the process that OVN developers should use when making a > +runtime compatibility change to OVS and OVN. > + > +1. Submit the change to OVS first. See the change through until it is merged. > +2. Make the necessary changes to OVN. > + > + a. At startup, probe OVS for the existence of the OpenFlow addition. If it > + is not present, then output an informational message to the logs that > + explains which OVN feature(s) cannot be used. > + b. If a user attempts to explicitly configure the feature that is not usable > + due to the incompatibility, then output a warning message to the logs. If > + the lack of the feature can be detected from a utility (such as ovn-nbctl > + or ovn-sbctl), then the utility should return an error and print to the > + console why the feature cannot be used. > + c. Ensure that the code that installs the OpenFlow will only do so if the new > + feature is present. > + > +Compatibility Statement > +----------------------- > + > +Given the above, the OVN team will try its hardest to maintain any released > +version of OVN with any released version of OVS after version 2.12. Versions of > +OVS prior to 2.12 are not guaranteed to run properly since OVN does not have > +appropriate OpenFlow feature probes in place. > + > +It may seem prudent to only guarantee compatibility with certain releases of > +OVS (e.g. the current and previous versions of OVS). However, dropping > +compatibility would involve actively removing code that ensures runtime safety. > +It seems unwise to do so. > + > +This, however, is a "best effort" policy. The OVN project reserves the right to > +withdraw compatibility support with a previous OVS version, for reasons such as: > + > +- Security risks. > +- Earthshatteringly large changes in OVS (e.g. no longer using OpenFlow or the > + OVSDB). This likely would coincide with a change in the OVS major version > + number. > +- Difficulty in safely maintaining compatibility across versions. > + > +In the event that compatibility for a certain version or versions of OVS is > +dropped, the OVN project will clearly document it. > + > +At some point, the compatibility matrix between OVS and OVN will likely become > +too complex to explicitly test every version of OVN against every version of > +OVS. Therefore, we will maintain a list of "tested" and "untested" compabitility > +options for OVS and OVN. "untested" combinations *should* work, but since they > +have not had explicit testing done, they cannot be guaranteed. > diff --git a/Documentation/topics/index.rst b/Documentation/topics/index.rst > index a34925f2e..d3a4eb70a 100644 > --- a/Documentation/topics/index.rst > +++ b/Documentation/topics/index.rst > @@ -41,6 +41,7 @@ OVN > role-based-access-control > ovn-news-2.8 > testing > + ovs-compatibility > > .. list-table:: > > diff --git a/Documentation/topics/ovs-compatibility.rst b/Documentation/topics/ovs-compatibility.rst > new file mode 100644 > index 000000000..c324a24cd > --- /dev/null > +++ b/Documentation/topics/ovs-compatibility.rst As mentioned by 0-day robot, this file should be added to automake. > @@ -0,0 +1,69 @@ > +.. > + Copyright (c) 2019 Red Hat, Inc. > + > + Licensed under the Apache License, Version 2.0 (the "License"); you may > + not use this file except in compliance with the License. You may obtain > + a copy of the License at > + > + http://www.apache.org/licenses/LICENSE-2.0 > + > + Unless required by applicable law or agreed to in writing, software > + distributed under the License is distributed on an "AS IS" BASIS, WITHOUT > + WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the > + License for the specific language governing permissions and limitations > + under the License. > + > + Convention for heading levels in Open vSwitch documentation: > + > + ======= Heading 0 (reserved for the title in a document) > + ------- Heading 1 > + ~~~~~~~ Heading 2 > + +++++++ Heading 3 > + ''''''' Heading 4 > + > + Avoid deeper levels because they do not render well. > + > +================================= > +Compatibility between OVN and OVS > +================================= > + > +This document lists versions of OVN and details their compatibility against > +versions of OVS. This document will be updated as new versions of OVS and OVN > +are released. > + > +For a more detailed look into OVN and OVS compatibility, see > +:doc:`internals/contributing/ovs-ovn-compatiblity`. > + > +The following is a template for how a version might be documented: > + > +:: > + > + OVN version X.Y is 100% feature compatible with OVS versions A.B.C and higher. > + > + - OVN feature "foo" is unavailable in OVS versions A.(B-2).0 until version > + A.B.C. > + > + OVN version X.Y has been explicitly tested against > + > + - OVS version A.(B-3).0 - A.(B-3).4 > + - OVS version A.(B-2).0 - A.(B-2).2 > + - OVS version A.(B-1).0 - A.(B-1).2 > + - OVS version A.B.0 - A.B.C > + - OVS master A.B.90 > + > + OVN version X.Y has not been tested against OVS versions prior to A.(B-3).0, > + but it is expected to be able to run as far back as OVS version A.(B-6).0. > + > + OVN version X.Y is not runtime compatible with versions prior to A.(B-6).0. Better to be: "... with OVS versions prior to ..." > + > +OVN master (2.12.90) > +-------------------- > + > +OVN master is 100% feature compatible with OVS versions 2.12.0 and higher. > + > +OVN master (version 2.12.90) has been explicitly tested against > + > +- OVS 2.12.0 > +- OVS master (2.12.90) > + > +OVN master is not compatible with versions of OVS prior to 2.12.0. > -- > 2.14.5 > > _______________________________________________ > dev mailing list > [email protected] > https://mail.openvswitch.org/mailman/listinfo/ovs-dev _______________________________________________ dev mailing list [email protected] https://mail.openvswitch.org/mailman/listinfo/ovs-dev
