Contribute to our code¶
This page covers topics on how to make/build/test your changes to the MicroOVN source code.
Get the source code¶
MicroOVN development happens on GitHub. You can find, and contribute to, its source code in in our GitHub repository.
Build and install MicroOVN from source¶
Build requirements¶
MicroOVN is distributed as a snap and the only requirements for building it
are Make and snapcraft. You can install them with:
sudo apt install make
sudo snap install snapcraft --classic
Snapcraft requires LXD to build snaps. So if your system does not have LXD
installed and initiated, you can check out either LXD getting started
guides or go with following default setup:
sudo snap install lxd
lxd init --auto
Build MicroOVN¶
To build MicroOVN, go into the repository’s root directory and run:
make
This will produce the microovn.snap file that can be then used to install
MicroOVN on your system.
Adjust build parameters¶
snapcraft.yaml is by nature a very static build recipe that does not allow
build-time modification without changing the file itself. To achieve some
level of control over MicroOVN builds, we are using a
microovn/build-aux/environment file that is loaded and during the build
process. Environment variables defined in this file can influence properties
of the final build. Currently supported variables are:
MICROOVN_COVERAGE(default:no) - When set toyes, MicroOVN binaries will be built with coverage instrumentation and output coverage data into$SNAP_COMMON/data/coverage.
Install MicroOVN¶
Using the microovn.snap file created in the previous section, you can
install MicroOVN in this way:
sudo snap install --dangerous ./microovn.snap
Note
If you are building latest MicroOVN from the main branch, it’s possible
that it’s using a non-stable core snap as its base. In that case, you may
get a message like this:
Ensure prerequisites for "microovn" are available (cannot install snap base "core24": no snap revision available as specified)
In such a case, you will need to install the required core snap manually
from the edge risk level. For example:
snap install core24 --edge
Then repeat the installation step.
You will also need to manually connect required plugs, as snapd won’t
do it automatically for locally installed snaps.
for plug in firewall-control \
hardware-observe \
hugepages-control \
network-control \
network-setup-control \
openvswitch-support \
process-control \
system-trace; do \
sudo snap connect microovn:$plug;done
Note
Once this is done you will need to restart running MicroOVN processes as certain newly added permissions do not apply to running process.
snap restart microovn
To verify that all the required plugs are correctly connected to their slots, you can run:
snap connections microovn
An example of correctly connected connected plugs would look like this:
Interface Plug Slot Notes
content - microovn:ovn-certificates -
content - microovn:ovn-chassis -
content - microovn:ovn-env -
firewall-control microovn:firewall-control :firewall-control manual
hardware-observe microovn:hardware-observe :hardware-observe manual
hugepages-control microovn:hugepages-control :hugepages-control manual
microovn - microovn:microovn -
network microovn:network :network -
network-bind microovn:network-bind :network-bind -
network-control microovn:network-control :network-control manual
openvswitch-support microovn:openvswitch-support :openvswitch-support manual
process-control microovn:process-control :process-control manual
system-trace microovn:system-trace :system-trace manual
And if the plugs are not connected, the output would look like this:
Interface Plug Slot Notes
content - microovn:ovn-certificates -
content - microovn:ovn-chassis -
content - microovn:ovn-env -
firewall-control microovn:firewall-control - -
hardware-observe microovn:hardware-observe - -
hugepages-control microovn:hugepages-control - -
microovn - microovn:microovn -
network microovn:network :network -
network-bind microovn:network-bind :network-bind -
network-control microovn:network-control - -
openvswitch-support microovn:openvswitch-support - -
process-control microovn:process-control - -
system-trace microovn:system-trace - -
Tests¶
The tests mainly focus on functional validation of MicroOVN and how we build and configure OVN itself.
We expect Go unit tests for pure functions.
For impure functions, i.e. functions with side effects, if you find yourself redesigning interfaces or figuring out how to mock something to support unit tests, then stop and consider the following strategies instead:
Extract the logic you want to test into pure functions. When done right the side effect would be increased composability, setting you up for future code reuse.
Contain the remaining functions with side effects in logical units that can be thoroughly tested in the integration test suite.
MicroOVN has two types of tests, linter checks and functional tests and this page will show how to run them.
Linter checks¶
Go code¶
We make use of golangci-lint and you can find a list of enabled linters in
the microovn/.golangci.yml configuration file.
Successfully running the tool requires build dependencies to be installed and build environment variables properly set up.
Developer ergonomics are important to us, and we want the same experience in local development environments as in our gate.
As such we have opted to run golangci-lint as part of the snap build process as it gives us consistent results in both environments and relieves the developer of the burden of manually installing build dependencies to perform the checks locally.
If you use an IDE with golangci-lint support and want to utilise it, the
tool should automatically discover this configuration. You will however need
to install additional build dependencies and set up environment variables
to make it work. Refer to the definition of the microovn part in
snap/snapcraft.yaml for more information.
Test code¶
The prerequisites for running linting on the test code are:
makeshellcheck
You can install them with:
sudo apt install make shellcheck
To perform linting, go into the repository’s root directory and run:
make check-lint
Functional tests¶
These tests build the MicroOVN snap and use it to deploy the OVN cluster in LXD containers. This cluster is then used for running functional test suites.
Satisfy the test requirements¶
There is no need to run tests in dedicated VMs or in isolated environments as all functional tests run inside containers and no changes are made to the host running them.
Ensure that you have installed
Bash Automated Testing System (BATS), a software dependency. Due to the
reliance on its latest features, MicroOVN uses BATS directly from its
source. If you cloned the MicroOVN repository with submodules (using
--recurse-submodules flag), you are all set and you will have the following
non-empty directories:
.bats/bats-assert/.bats/bats-core/.bats/bats-support/
If they are empty, you can fetch the submodules with:
git submodule update --init --recursive
Run functional tests¶
Once you have your environment set up, running tests is just a matter of
invoking the appropriate make target. To run all available test suites