[ovs-dev] [PATCH ovn v4] Document process for compatibility between OVS and OVN.

Numan Siddique nusiddiq at redhat.com
Wed Oct 9 07:07:20 UTC 2019


On Wed, Oct 9, 2019 at 2:42 AM 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.
>
> It also creates a document to detail compatibility of specific OVN
> versions.
>
> Signed-off-by: Mark Michelson <mmichels at redhat.com>
> Acked-by: Han Zhou <hzhou8 at ebay.com>
>

Acked-by: Numan Siddique <nusiddiq at redhat.com>




> ---
> 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
> dev at openvswitch.org
> https://mail.openvswitch.org/mailman/listinfo/ovs-dev
>


More information about the dev mailing list