OVN Central Deployment#

ovn-central is the Kube-OVN control-plane component that bundles OVN Northbound DB, Southbound DB, and ovn-northd into a single pod. It can be deployed in two modes 1:

The Helm chart implements both modes in central-deploy.yaml.

Single-Replica Mode#

When to use it#

Pick single-replica when you do not have three master nodes, or when a simpler failure model is acceptable and you can tolerate a multi-minute recovery window on host loss 2.

Single-replica mode is also a prerequisite for Kamaji-style split-cluster deployments, where ovn-central runs in a management cluster and exposes the OVN DB to tenant clusters via a LoadBalancer Service. A non-elected single backend means the LB always has exactly one healthy endpoint with no leader flapping 3.

How it works#

In single-replica mode the Deployment strategy is set to Recreate (rather than RollingUpdate) to avoid two replicas ever touching the PVC at the same time. The host-config-ovn volume is backed by the PVC ovn-central-data (configurable via existingClaim) instead of a hostPath. Pod anti-affinity is not applied in single-replica mode 4.

On host failure the pod is rescheduled; it reattaches to the PV and recovers DB state automatically 5.

StorageClass requirements#

The PVC is ReadWriteOnce. For pod drift between nodes, the StorageClass must support detach/attach on a new node 6:

• Works: NFS (csi-driver-nfs), cloud block storage (EBS, GCE PD, Azure Disk), Ceph RBD, Longhorn, Portworx
• Will not drift: hostPath provisioners (e.g. local-path-provisioner) — the pod will stay Pending after rescheduling

volumeBindingMode: WaitForFirstConsumer is recommended 7.

Installation#

Helm#

Set OVN_CENTRAL_MODE: single and provide storage config in values.yaml 8:

OVN_CENTRAL_MODE: single

ovn-central:
  storage:
    storageClassName: my-csi
    size: 10Gi
    accessModes:
      - ReadWriteOnce

helm install kube-ovn ./charts/kube-ovn -f values.yaml

install.sh#

ENABLE_SINGLE_REPLICA_OVN=true \
  OVN_CENTRAL_STORAGE_CLASS=my-csi \
  OVN_CENTRAL_PVC_SIZE=10Gi \
  bash dist/images/install.sh

After install, verify one pod, the PVC, and that ovn-nb Service selector is {"app":"ovn-central"} with no ovn-nb-leader selector 9.

Failover Drill#

To test failover of a single-replica instance 10:

node=$(kubectl get pod -n kube-system -l app=ovn-central \
  -o jsonpath='{.items[0].spec.nodeName}')

kubectl cordon "$node"
kubectl delete pod -n kube-system -l app=ovn-central

kubectl wait pod -n kube-system -l app=ovn-central \
  --for=condition=Ready --timeout=5m
kubectl exec -n kube-system deployment/ovn-central -- ovn-nbctl show

Note: kubectl exec does not support the -l label selector (it fails with unknown shorthand flag: 'l'). The command targets deployment/ovn-central instead, which runs the check in the newly rescheduled pod without needing to look up its new name. The kubectl wait and kubectl delete pod commands still use -l app=ovn-central.

For a real host-loss test, the CSI driver must support fencing. Without it, the volume stays attached to the dead node and the new pod hangs in ContainerCreating until Kubernetes force-detaches (typically 6+ minutes) 11.

Health Checks#

The readiness and liveness probes both run /kube-ovn/ovn-healthcheck.sh every 15 seconds with a 45-second timeout. In single-replica mode, ovn-healthcheck.sh uses ovsdb-server/get-db-storage-status instead of cluster/status — raft-specific issues are not surfaced (there are none in this mode) 12.

Backup, Restore, and Mode Migration#

• Hot backup: kubectl exec into the pod and run ovsdb-client backup unix:/var/run/ovn/ovnnb_db.sock 13.
• Restore: bash dist/images/restore-ovn-nb-db.sh single <backup.db> — scales to 0, mounts the PVC in a helper pod, copies the file, scales back to 1 14.
• Cluster → single migration: Scale existing ovn-central to 0, run ovsdb-tool cluster-to-standalone, then restore 15.
• Single → cluster migration: Take a backup, reinstall in cluster mode, and load into the leader 16.

Warning: The Helm chart actively guards against in-place mode switches — it will fail with explicit migration instructions if OVN_CENTRAL_MODE changes on an existing Deployment without following the documented migration procedure.

Limitations#

• kube-ovn-leader-checker raft queries, ovn_northd lock stealing, and raft header backup are all skipped 17.
• During failover, all kube-ovn-controller / ovs-ovn / ovn-controller clients see connection errors until the new pod is Ready. They reconnect automatically; in-flight ovsdb transactions may be retried 18.

Related References#

• docs/single-replica-deployment.md — full deployment and operations guide
• charts/kube-ovn/templates/central-deploy.yaml — Helm template implementing both modes
• docs/kamaji-deployment.md — split-cluster deployment walkthrough