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!
-------------------
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
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.
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.
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.
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
[email protected]
https://mail.openvswitch.org/mailman/listinfo/ovs-dev
