Activating the Virtual Network
Activation is a wizard on the datacenter: Datacenter › Virtual Network › Activate. It runs the same five steps for every mode; step 2 is the one that differs.
License
Activation requires the Virtual Network entitlement on your Cockpit license. If it is missing, add it to your subscription and import the updated license before you begin — see the note in the overview.
Before you start, every host in the datacenter should be connected in Cockpit. The wizard asks each host what it can do, and a host that cannot be reached is a host it cannot include.
Step 1 — Name and mode
Give the deployment a name and choose one of the three modes described in the overview. The mode cannot be changed afterwards; to switch, deactivate and activate again.
Step 2 — What the mode needs
Form a Vapor-native OVN deployment
Choose the centrals: the hosts that will run the OVN databases as a RAFT cluster.
- 1, 3 or 5. The wizard refuses 2 and 4. An even number is strictly worse than the odd number below it: two centrals cannot out-vote each other, so losing either one loses the cluster.
- Spread across clusters. When the datacenter has three or more clusters, the wizard defaults to one central per cluster. A cluster usually maps to a rack or a failure domain; three centrals in one rack survive a host failure but not a rack failure.
- Existing databases. If a chosen central already holds OVN databases from a previous life, the preflight will say so (see below). Those files may be the entire logical configuration of whatever they served. The wizard will not replace them without an explicit confirmation.
Every other host in the datacenter joins as a chassis. A single-central deployment works, with no redundancy; use it for a lab.
Join an existing external OVN deployment
Enter the northbound and southbound database addresses, for example tcp:10.0.0.1:6641 and tcp:10.0.0.1:6642.
If the external databases are clustered, list every member, comma-separated: tcp:10.0.0.1:6641,tcp:10.0.0.2:6641,tcp:10.0.0.3:6641. OVN clients only talk to the cluster leader, so a single address stops working the moment leadership moves to another member. Use ssl: instead of tcp: if the databases require TLS.
Bridge mappings are optional and apply to every host; leave them empty unless the external deployment expects a provider network.
Join an existing Kube-OVN cluster
Nothing is typed here. The wizard shows, per host, what it found:
| Column | Meaning |
|---|---|
| Kube-OVN | Whether kube-ovn is running on that host. Detected through the Kubernetes API where the host has a kubeconfig, or from kube-ovn's own daemon on the host where it does not (worker nodes usually do not). |
| Node | The Kubernetes node name. |
| --enable-external-vpc | The kube-ovn-controller flag. See the warning below. |
| Northbound (discovered) | The database address kube-ovn reports. |
The deployment's addresses are filled from the first host that reports them and shown read-only. Tick Override the discovered addresses only if you know better than the CNI. If hosts report different addresses, they belong to different kube-ovn clusters, and one datacenter can only join one.
Hosts that are not kube-ovn nodes are left out
A host that is not a kube-ovn node cannot join in this mode. If it did, it would register in kube-ovn's southbound database as a chassis kube-ovn does not know about — and kube-ovn's controller removes unknown chassis every time it restarts. The same applies to a node whose Vapor has no OVN client tools, because it could never read the database it had joined.
Such hosts are recorded as excluded, with the reason, and nothing is applied to them. To bring one in later, fix the cause (install kube-ovn, or the ovn-common and openvswitch-switch packages) and use Sync.
The --enable-external-vpc flag
kube-ovn's controller treats its northbound database as its own. Any object it cannot map to a Kubernetes resource is a leak to be cleaned: logical switch ports on a 360-second timer, and logical switches and routers in one sweep every time the controller restarts. The switch that exempts foreign objects is --enable-external-vpc=true on the kube-ovn-controller deployment, and it defaults to false.
Without it, every network you create through Cockpit survives until the next controller restart and then disappears — which can be weeks later, long after anyone would connect the two events. The preflight reports the flag; the wizard will not apply without an explicit acknowledgement when it is unset. Set the flag instead.
Step 3 — Hosts and encapsulation
One row per host in the datacenter, with the encapsulation IP each host will use for its Geneve tunnels. The wizard fills it from what the host itself proposes; edit a row if the host has a better interface for tunnel traffic (a dedicated storage or overlay network, say).
Two rules the wizard enforces:
- One address per host. Two hosts sharing an encapsulation IP would build a fabric in which tunnels never come up.
- Never copy one host's address to another. Each row is that host's own.
In vapor-native mode the centrals' encapsulation IPs also become the database addresses every host connects to.
Step 4 — Preflight
The wizard checks the whole datacenter before it changes anything. Every check is shown per host with its detail; a fail blocks activation, a warn needs acknowledging.
| Check | What it verifies |
|---|---|
| Central quorum | 1, 3 or 5 centrals (vapor-native). |
| Encapsulation path | Every host can reach every other host's encapsulation IP. This is a real probe, host to host, not a comparison of subnets. |
| Geneve MTU headroom | The same probe with a packet the size of a tunnelled 1500-byte guest frame. A warn here means the path works but guests on this fabric must use a smaller MTU (1442 with a 1500-byte underlay) or the underlay must be raised to 1558. Not fixing this produces VMs that connect but cannot pass full-sized packets. |
| Existing OVN databases | A would-be central already has database files. If they belong to a running cluster this passes; if they are standalone, it warns and the replace databases confirmation appears — back them up first. |
| Kube-OVN membership | Per host, whether it can take part; excluded hosts are listed with the reason. |
| Kube-OVN external VPC | The controller flag, as above. |
| Per-host checks | Each participating host's own preflight from Vapor: packages present, the databases reachable, the encapsulation IP valid on that host, a joining central able to reach the cluster member it will join. |
Activation is possible when nothing has failed and every warning is acknowledged.
Step 5 — Apply and verify
The wizard shows each host as it goes. In vapor-native mode this is sequential by design — the first central bootstraps, the others join one at a time, then the chassis in parallel — so it takes tens of seconds, not one.
Each host is reported at two levels: applied (Vapor accepted the configuration) and registered (the host actually appears in the southbound database as a chassis). A host can be one without the other; the wizard tells you which.
When it finishes:
- Active — every host is in. Finish takes you to the deployment.
- Partial or Error — some hosts are not. Their errors are listed per host. Retry failed hosts re-applies to every member and re-pushes the member list; Close leaves the deployment as it is, and the Virtual Network tab shows the same state with the same retry.
The most common reason for a partial result is a host that could not be reached at apply time. Fix the cause, then retry — nothing needs to be undone first.
After activation
Every host now reports its chassis under Host › Configure › Networking › Virtual Network, and the datacenter tab shows the fabric's inventory. From here, the day-to-day is described in Operating the Virtual Network.