[ovs-dev] [RFC v2] Document process for compatibility between OVS and OVN.
Han Zhou
zhouhan at gmail.com
Thu Sep 12 20:51:23 UTC 2019
Thanks Mark for writing this up.
On Fri, Sep 6, 2019 at 2:08 PM Mark Michelson <mmichels at redhat.com> 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.
>
> Note that the document currently makes reference to some non-existent
> items. For instance, it refers to an ovs-compat directory in the OVN
> project. Also, it refers to some macros for testing the OVS version.
> These will be added in a future commit if the process documented here is
> approved.
>
> I'm submitting this as an RFC, since I imagine there are some details I
> have not thought about, and there will also be some great suggestions
> from others on this matter.
>
> Signed-off-by: Mark Michelson <mmichels at redhat.com>
> ---
> Documentation/automake.mk | 1 +
> Documentation/internals/contributing/index.rst | 1 +
> .../contributing/ovs-ovn-compatibility.rst | 129
+++++++++++++++++++++
> 3 files changed, 131 insertions(+)
> create mode 100644
Documentation/internals/contributing/ovs-ovn-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..d40b58c32
> --- /dev/null
> +++ b/Documentation/internals/contributing/ovs-ovn-compatibility.rst
> @@ -0,0 +1,129 @@
> +..
> + Copyright (c) 2019 Nicira, 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
> +===============================
> +
> +OVN has split from OVS. Prior to this split, there was no issue with
> +compatibility. All code changes happened at the same time and in the
same repo.
> +New releases contained the latest OVS and OVN changes. But now these
assumptions
> +are no longer valid, and so care must be taken to maintain compatibility.
> +
> +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.
> +
> +When compiling older releases of OVN, it should be able to compile
against newer
> +versions of OVS due to API and ABI guarantees in OVS's libaries.
> +
> +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
> +updage OVS, then OVN will not be able to install the OpenFlow rules it
wishes
> +to.
> +
Although unlikely, is it possible in theory that an OVS update breaks
existing feature for OVN?
> +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 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.
> + 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).
> +- 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.
It is always good to document compatibility issues. Even if probing and
warnings are implemented, I think it is still very important to maintain a
document that list the compatibility between OVS and OVN releases. For
example,
OVN release <r1>: requires OVS release from <a> to <b>
- For feature F1: requires OVS release from <c> to <b>
- For feature F2: requires OVS release from <d> to <b>
OVN release <r2>: ...
...
<b> can be just "latest" , if OVS update never breaks existing features.
Otherwise, <b> must also be explicitly stated.
This way, users can get a clear picture of what version should be used
without having to actually run the combinations and figure out the issues
by looking at the runtime warnings.
> --
> 2.14.5
>
> _______________________________________________
> dev mailing list
> dev at openvswitch.org
> https://mail.openvswitch.org/mailman/listinfo/ovs-dev
More information about the dev
mailing list