[ovs-dev] OVN/OVS split document: Feedback requested

Tue Sep 25 20:40:54 UTC 2018

Mark Michelson <mmichels at redhat.com> writes:

> What's below the dashed line was originally a Google Doc, which I have
> copy-pasted into text form. Some of the formatting has been lost as a
> result, but it should still be readable.
>
> There are quite a few open points of discussion below, including
> 1) Ideal repo structure for OVN, including method for isolating OVN
> from the OVS code.
> 2) Ideal method for making OVN compile against multiple versions of OVS
> 3) Ideal method for enforcing ABI/API compatibility in OVS moving forward
> 4) Ideal packages for OVS and OVN.
>
> Please comment on these or any other points you want to discuss. Also
> let me know if there are any tasks that are not on this document that
> should be. Thanks!
>
> -------------------

Thanks for this document, Mark.

Some thoughts inline.

> This document attempts to account for the technical aspects of an
> OVN/OVS split. Administrative concerns such as the determining the
> governing body, creating separate email lists, designing a website,
> rethinking the release schedule, and changing the version numbering
> are outside the scope of this document.
>
> Below we divide the work into 4 distinct phases. Phase 1 describes the
> physical task of separating out the OVN code. It contains the lion’s
> share of the actual separation work and is thus divided into
> sub-phases. Phases 2 and 3 focus on maintaining sanity once the split
> is accomplished. And Phase 4 focuses on distribution of the
> components.
>
> Here is a simple checklist of items to complete.
>
> 1(a) Determine new repo structure
> 1(b) Make common OVS source code libraries into a shared library
> 1(c) Migrate OVN source code into its repo
> 1(d) Make OVS testsuite tools accessible to both OVS and OVN
> 1(e) Migrate OVN testsuite to its repo
> 1(f) Migrate OVN documentation to its repo
> 1(g) Make common libraries for development/build tools
> 2(a) Devise scheme for OVS/OVN compatibility
> 2(b) Devise a way to enforce API/ABI compatibility across versions of
> libopenvswitch
> 3 Write code in OVS to allow for runtime checks for high-level features.
> 4 Develop new packaging for OVS/OVN
>
> Phase 1: A Separate Repo
> Goal: To have a compiling version of OVN that lives in a repo separate
> from OVS, whose tests pass, and whose documentation is present.
>
> Phase 1a: Determine repo structure
> Goal: To determine what repos need to exist in order to support a
> split OVN/OVS
>
> Task: Create new repo or repos for OVN.
>
> Possible options:
> OVN contains OVS as a git submodule.
> There is an ovs repo and an ovn repo.
> All subcomponents of OVS live in separate repos (ovs-vswitchd,
> ovs-lib, ovs-test-lib, ovsdb, etc), and OVN gets its own repo as well.
>
> Option a has some advantages. By cloning the OVN repo and updating the
> OVS submodule, you will have all necessary components in one
> place. You can independently update the OVS submodule as
> necessary. The Makefile for OVN can rely on the submodule being
> present and compile both OVS and OVN.
>
> Option a has the disadvantage that it requires a hard dependency on
> all of OVS by OVN. It doesn’t play nicely in the case where OVS is
> already installed on the system and OVN gets cloned later. It also
> doesn’t play nicely in the case where multiple clones of OVN exist on
> a system and want to share the same underlying installation of OVS. It
> also “bloats” the size of the OVN repo.
>
> Option b is essentially the same as option a except that OVS is not a
> git submodule. Instead, you must clone and install OVS, then you must
> clone and install OVN separately. This solves some of the
> disadvantages of option a, but it still requires a hard dependency on
> all of OVS by OVN.
>
> Option c places all separate components of OVS into their own
> repos. This allows for OVN to be installed on systems without needing
> all of OVS to also be installed. However, this also creates a lot of
> confusion by having so many repos present.
>
> Phase 1b: Make common OVS source code libraries into a shared library

One thing I'll add is that there already exists an initial stab at
a shared library, but as you outline below, it will need quite a bit
more work.

> Goal: To create a shared library of OVS source code that OVN can use.
> Task: Move source code used by OVN and OVS to a common source
> location, and create a library from this.
>
> With OVN living in the same repo as OVS, the source code has been
> pretty lax when it comes to organization of files. There is a lib/
> directory that contains both headers and source files for common code
> used by OVS and OVN. There is also an include/openvswitch directory
> that contains header files used by OVS, OVN, and is intended to be
> include-able by code outside of OVS. For the split, all header files
> for libraries need to be moved to include/openvswitch since they all
> potentially will be used by an outside application (OVN).
>
> After reorganizing the code, the OVS makefile needs to build its
> common libraries into a shared object (dll on windows) that is
> installed in a common location (e.g. /usr/lib). This way, OVN will be
> able to link against the shared object. Whether the emitted library is
> static or dynamic should be left to the discretion of the
> builder/packager.

This already happens - albeit, I don't know that it's maintained in a
way that openvswitch-libs is really usable.  See
./lib/libopenvswitch.pc.in for an example pkg-config file that will go
with libopenvswitch.

OTOH, the pkgconfig definition there is incomplete.  There are no
Requires flags, and some of the non-pkg-config supported libraries (I
think -lpthread, and maybe -lrt).  So a simple test where one might want
to use the dynamic string library results in huge numbers of linker
errors (needing to specify things like Requires: openssl, etc.).  And
that list will need to be filled in depending on config options.

Not that those are the only things required for this step.  I think this
ties pretty closely to a part of 2b; which means the processes for ABI /
API deprecation should be considered a bit more carefully.

And then it's important for OVN makefiles to actually check for this and
try to link against it.

> Phase 1c: Separate OVN source code from OVS source code
> Goal: For OVN to compile living in a separate repo from OVS
>
> Task: Separate OVN source code so that it exists in the repo(s)
> created in Phase 1a. Ensure that code compiles and runs.
>
> This is mostly done as a way of detecting that the work done in Phase
> 1b was done correctly. Note that OVN test code is handled in a
> separate task.
>
> How the code gets moved is still an open question. Jiri Benc brought
> up two potential methods:
> Use git-filter-branch. This allows for OVN git history to be retained,
> but it makes commits pre-split unbuildable.
> Copy the OVS repo and then remove the OVS code from that repo, leaving
> OVN. This also retains history, and it allows for code pre-split to be
> built and tested. It also locks us into the current directory
> structure of the repo, which may be a downside. It also results in a
> larger repo.
>
> Phase 1d: Make OVS testsuite tools accessible to both OVS and OVN.
> Goal: To create a library of OVS unit test code that the OVN testsuite
> can use.
> Task: Create library of helper applications and m4 macros for tests
> used by OVS and OVN.
>
> This is similar to Phase 1b, except that it relates to the testsuite
> rather than the main source code.
>
> Rather than generating a shared object that can be loaded by C code,
> the target here should be a collection of M4 and executables that can
> be called from testsuite code.

This suggests to me that the common macros should be distributed.

> Phase 1e: Separate OVN testsuite code to its repo.
> Goal:  For OVN testsuite tests to pass from outside the OVS repo.
> Task: Move OVN tests into its repo.
>
> This is similar to phase 1c except that you are moving tests instead
> of source code. Like with phase 1c, this involves changes to the build
> systems in both OVS and OVN in order for tests in both repos to pass.
>
> Phase 1f: Separate OVN documentation into its repo
> Goal: For OVN documentation to be available within the OVN repo.
> Task: Migrate OVN documentation from the OVS repo to the OVN repo
>
> Like with other separation tasks, this involves both moving the files
> from one repo to another as well as updating the builds of OVS and OVN
> to ensure that output is correct for each project.
>
> Phase 1g: Move development tools to a common location accessible to
> both OVS and OVN
> Goal: Make sure that development tools are available to both OVN and OVS
> Task: Create a “library” of build/development tools that can be
> accessed by both OVS and OVN.
>
> For this task, consider tools used during building and development
> that currently live in the OVS repo. These same tools should be just
> as easily available to the OVN code. This includes tools in the
> build-aux/ directory, as well as utilties/checkpatch.py (are there
> others?).
>
> Phase 2: Maintaining code compatibility with OVS
> Goal: To be able to detect from OVN whether OVS library functions are
> present
>
> Phase 2a: Determining code availability within OVS
> Task: Devise a way of ensuring OVN can compile against multiple
> versions of OVS.
>
> Once OVS and OVN are moving at different release cadences, the version
> of OVN has no bearing on what version of OVS libraries are installed
> on the system.
>
> This task is purposely a bit vague because there are very different
> paths that can be taken to accomplish this.
>
> One path to take is that with any given version of OVN, a minimum
> version of OVS libraries must be installed. As long as OVS is at the
> minimum version or later, then we should be able to guarantee that OVN
> will build. The potential drawback here is that vendors may be locked
> into earlier versions of OVS than the minimum and wish to upgrade to a
> newer OVN version. Or, it may be that a downstream distribution of OVS
> may have features not present in the upstream OVS version.
>
> Another possible path to take is to test for specific code in OVS when
> configuring OVN. This can allow for code to be conditionally compiled
> in when present. This way, a build of OVN isn’t tied to a specific
> version of OVS.
>
>
> Phase 2b: Maintaining ABI/API compatibility
> Goal: To be able to ensure that ABI/API across different versions of
> OVS is maintained.
> Task: Devise a way to ensure API/ABI compatibility across versions of OVS.
>
> This should be pretty self-explanatory. It’s important for OVN not to
> break due to the version of OVS changing underneath. Therefore, OVS
> needs to develop a policy where it does not break API or ABI.
>
> What is the best way to enforce this?
>
>
> Phase 3: Detecting OVS features in OVN
> Goal: To be able to detect that a semantic feature of OVS is present
> from within OVN.
> Task: Create runtime calls in OVS that test if a particular feature is
> present.
>
> This is similar to the work being done in phase 2, except that it
> refers to compatibility outside the source code of OVS.
>
> A good example of this would be if new OpenFlow match criteria are
> added to OVS, and OVN wants to be able to make use of these.
>
> The best way to do this is to add functions to OVS that allow for
> probing of features at runtime.
>
> An alternate method might be to use the OVS version to determine the
> presence of a feature. Using version numbering as a detection method
> has downsides, especially when it comes to vendor-specific versions of
> OVS. Thus probing for individual features is preferred.

I think probing for features is really the only way to go.

>
>
> Phase 4: New Packaging
> Goal: To create sane packages of all OVS/OVN components across
> supported platforms.
> Task: Devise new packaging scheme for OVS and OVN and develop the
> appropriate packages.
>
> As it stands, OVS is a single package, and OVN is split into two
> packages. OVN is split into ovn-central, which provides ovn-northd;
> and ovn-host, which provides ovn-controller.
>
> Much like was discussed earlier with regards to repositories, does it
> make sense to re-think what packages are offered? For example,
> ovn-central will make use of OVS libraries and the ovsdb, but it does
> not require ovs-vswitchd to be present. Does it make sense to create
> additional packages for OVS sub-components so that “unnecessary”
> software is not installed?
>
> As part of this task, if packages are re-thought, then init-scripts
> and systemd units should be examined to ensure that they are still
> written with the correct parameters.
> _______________________________________________
> dev mailing list
> dev at openvswitch.org
> https://mail.openvswitch.org/mailman/listinfo/ovs-dev