Activating the Virtual Network
Until OVN is activated, the Network > OVN pages have nothing to show: Vapor does not know where the OVN databases live or what part this host plays. Activation settles both, and takes effect without restarting Vapor.
Open Network > OVN and start the activation wizard. On a host that is already activated the same wizard is available as Reconfigure.
Where the settings are kept
Activation is stored in Vapor's own database, so it survives a restart and can be changed at any time. Three sources can supply the database addresses, and the first one that has a value wins:
- Environment variables —
VAPOR_OVN_NB_DBandVAPOR_OVN_SB_DB - Vapor's database — what the wizard writes
vapor.conf—ovn_nb_dbandovn_sb_db, useful for preseeding a host before anyone opens the UI
If none is set, the OVN tools fall back to a local socket, which is correct only on a host that holds the databases itself.
The status card shows which source is in use, so if a change does not seem to take effect, look there first — an environment variable set on the service will override anything the wizard stores.
The wizard, step by step
1. Mode
Choose the deployment shape. The three modes are described below; the differences matter, so read the one you intend to use before continuing.
2. Discovery
Vapor inspects the host and shows what it found: which OVN and OVS programs are installed and their versions, which services are running, the existing system-id if there is one, candidate tunnel addresses with the subnet each belongs to, and — if a kubeconfig is reachable — whether this is a Kubernetes node and whether kube-ovn is present.
Discovery only reads. Nothing is changed until you reach the apply step.
One entry can look contradictory on a Kubernetes node: ovn-controller may be reported as not installed while also running. That is expected, because kube-ovn runs it inside a pod rather than as a host service.
3. Addresses and peers
For an external or kube-ovn deployment, this is where the northbound and southbound addresses go. For a Vapor-native deployment, this is where you say whether the host is a central (it runs the databases) or a chassis (a hypervisor that connects to them), and, for a central, whether it starts a new cluster or joins an existing one.
4. Local chassis
The system-id, the tunnel encapsulation type and address, and optional bridge mappings.
Pick the tunnel address from the candidates discovery offers, and pick one on a subnet that every other host in the deployment shares. A chassis with an address its peers cannot reach registers successfully and then never forms a tunnel, which looks like a working deployment that silently drops traffic between hosts.
Bridge mappings are only needed if you intend to give a logical router a path to a physical network — see Routing and external connectivity.
5. Preflight
Vapor runs a list of checks and shows each one with its reason. A fail blocks the apply; a warning requires you to acknowledge it explicitly.
| Check | What it means |
|---|---|
ovs_installed | ovs-vsctl is present. Without it, attaching a virtual machine to a logical switch fails when the machine starts |
ovn_tools_installed | ovn-nbctl and ovn-sbctl are present, with their versions |
nb_reachable / sb_reachable | The databases answer. Skipped for a Vapor-native central, which creates its own |
central_capable | This host has the systemd units an OVN central needs. ovn-ctl alone is not enough — it ships with the host package too |
cluster_remote_reachable | For a central joining a cluster, the member it will contact is reachable |
encap_ip_valid | The tunnel address exists on this host |
system_id_valid | The system id is unset or already matches what we intend |
no_stale_chassis | No leftover chassis registration for this host under a different id |
kube_ovn_external_vpc | kube-ovn is configured not to delete objects it does not recognise |
kube_ovn_node_match | This host is a Kubernetes node |
6. Review and apply
Apply is idempotent: running it again with the same configuration reports that nothing needed changing. If a step fails partway, Vapor rolls back what it changed and tells you what it restored, so a failed activation leaves the host no worse than it was.
Mode 1: Vapor-native
Vapor runs the OVN databases. This is the recommended shape for a deployment that is not already running OVN, because nothing else owns the databases and nothing else will remove what you create.
A host is either a central or a chassis:
- A central runs
ovn-northdand the northbound and southbound databases, and is also a chassis. - A chassis runs only
ovn-controllerand connects to the centrals.
One central is a complete, working deployment with no redundancy. For high availability use three or more. Two is worse than one: it cannot form a majority, so losing either host stops the deployment.
Cluster formation, join tokens and adding hosts are covered in Vapor-native clusters.
Mode 2: Existing external OVN
Someone else runs ovn-central. Supply its northbound and southbound addresses; Vapor joins as a client and configures this host as a chassis. Vapor will not attempt to reconfigure that central.
This is the simplest mode. If the addresses answer and the tunnel address is right, there is nothing else to decide.
Mode 3: Existing kube-ovn cluster
Vapor shares the OVN databases that belong to a Kubernetes CNI. It works, but kube-ovn assumes it owns those databases, so there are conditions. Vapor checks all three during preflight.
kube-ovn must be told not to collect foreign objects
kube-ovn reconciles OVN against Kubernetes resources and deletes anything it cannot account for. With its default settings, one restart of kube-ovn-controller deletes every logical switch and router Vapor created, and its periodic sweep deletes logical switch ports within two cycles.
Set --enable-external-vpc=true on the kube-ovn-controller deployment. With that flag, objects that do not carry kube-ovn's own marker are excluded from its garbage collection entirely.
Vapor reads this flag during discovery and warns prominently if it is not set. Do not dismiss that warning on a deployment you care about.
Enabling that flag has a consequence
With --enable-external-vpc=true, kube-ovn creates a cluster-scoped Vpc custom resource for every logical router it does not own, including Vapor's. Deleting that custom resource deletes the router in OVN.
Protect them before you rely on this:
- exclude
Vpcresources from any GitOps pruning, and - consider an admission policy that refuses deletion of
Vpcresources labelledovn.kubernetes.io/vpc_external=truefor everyone except kube-ovn's own service account.
A cluster-scoped resource that nobody declared is exactly what cleanup tooling removes.
Every Vapor hypervisor must also be a Kubernetes node
kube-ovn removes any chassis registration that does not correspond to a Kubernetes node, and the flag above does not change that. A hypervisor that is not a node loses its chassis at the next controller restart, and with it its tunnels.
Preflight treats this as a hard failure rather than a warning.
Version note
The exclusions above rely on kube-ovn tagging its own objects, which it does from v1.15.0 onward. On an older cluster, or one upgraded without its tagging migration having run, enabling the flag can also affect KubeVirt live migration, which uses the same filter to find a virtual machine's port. Check that your existing ports carry the vendor=kube-ovn marker before enabling it.
Deactivating
Deactivate stops this host's ovn-controller, clears its database pointers and marks it inactive. It does not delete logical switches, routers, ACLs or anything else from the OVN databases, because on a shared deployment those belong to everyone.
On a host whose workloads are currently using OVN, deactivation interrupts their networking. Treat it as a maintenance operation.