On Wed, Oct 9, 2019 at 2:42 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]> > Acked-by: Han Zhou <[email protected]> > Acked-by: Numan Siddique <[email protected]> > --- > v3 -> v4: > * Addressed grammatical fixes > --- > 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 | 2 + > Documentation/internals/contributing/index.rst | 1 + > .../contributing/ovs-ovn-compatibility.rst | 153 > +++++++++++++++++++++ > Documentation/topics/index.rst | 1 + > Documentation/topics/ovs-compatibility.rst | 70 ++++++++++ > 5 files changed, 227 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..bfb0a87bc 100644 > --- a/Documentation/automake.mk > +++ b/Documentation/automake.mk > @@ -25,6 +25,7 @@ DOC_SOURCE = \ > Documentation/topics/high-availability.rst \ > Documentation/topics/integration.rst \ > Documentation/topics/ovn-news-2.8.rst \ > + Documentation/topics/ovs-compatibility.rst \ > Documentation/topics/role-based-access-control.rst \ > Documentation/howto/index.rst \ > Documentation/howto/docker.rst \ > @@ -56,6 +57,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..125640fec > --- /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 compatibility, please see > +: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 common > time > +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..50d84803d > --- /dev/null > +++ b/Documentation/topics/ovs-compatibility.rst > @@ -0,0 +1,70 @@ > +.. > + 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 OVS versions prior to > + A.(B-6).0. > + > +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
