- Rust 69.9%
- Shell 15.6%
- Python 14.5%
| Filename | Latest commit message | Latest commit date |
|---|---|---|
| .forgejo/workflows | ||
| packaging | ||
| src | ||
| tests | ||
| tools | ||
| .gitignore | ||
| Cargo.lock | ||
| Cargo.toml | ||
| README.md | ||
netavark-ovs
Netzwerk-Plugin für netavark (den Netzwerk-Stack von Podman), das Container über Open vSwitch an OVN Logical Switches anbindet. Damit hängen Podman-Container im selben SDN wie VMs oder andere Workloads, hostübergreifend über die OVN-Overlay-Tunnel.
Pro Container und Netz legt das Plugin
- auf dem Host ein veth-Paar an, hängt das Host-Ende an die OVN-Integrationsbridge (
br-int) und schiebt das andere Ende in den Container, - in der OVN-Northbound-DB einen Logical Switch Port (LSP) mit Adressen und Port-Security an,
- und verknüpft beides über
external_ids:iface-id, sodassovn-controllerden Port bindet.
Voraussetzungen
-
Rootful Podman mit netavark-Backend (
podman info --format '{{.Host.NetworkBackend}}'→netavark). -
Auf dem Host laufen Open vSwitch und
ovn-controller, d. h. der Host ist als OVN-Chassis eingerichtet. -
Im
Open_vSwitch-Table des Hosts gesetzt:Key Bedeutung external_ids:ovn-nbVerbindung zur Northbound-DB, z. B. ssl:10.0.0.1:6641oderunix:/run/ovn/ovnnb_db.sock(Pflicht); mehrere Ziele kommagetrennt (Cluster)external_ids:ovn-nb-private-key,ovn-nb-certificate,ovn-nb-ca-certTLS-Dateien für ssl:(optional, siehe TLS)external_ids:ovn-bridgeIntegrationsbridge, Standard br-intexternal_ids:system-idChassis-Name; wird als Eigentümer an den Ports vermerkt ovs-vsctl set open_vswitch . external_ids:ovn-nb=ssl:10.0.0.1:6641 -
Werkzeuge:
ip(iproute2),nsenter(util-linux),ovs-vsctl(openvswitch-switch),ovsdb-client(openvswitch-common),ovn-nbctl(ovn-common).
TLS zur Northbound-DB
Bei ssl:-Zielen meldet sich das Plugin mit einem Client-Zertifikat an. Die drei Dateien (Schlüssel, Zertifikat, CA-Zertifikat der NB-DB) kommen jeweils aus
external_ids:ovn-nb-private-key/ovn-nb-certificate/ovn-nb-ca-certimOpen_vSwitch-Table, sonst- der SSL-Konfiguration des lokalen OVS (
ovs-vsctl set-ssl), die auchovn-controllerfür die Southbound-Verbindung nutzt.
# eigenes Zertifikat nur für die NB-Verbindung
ovs-vsctl set open_vswitch . \
external_ids:ovn-nb=ssl:10.0.0.1:6641 \
external_ids:ovn-nb-private-key=/etc/ovn/podman-nb-privkey.pem \
external_ids:ovn-nb-certificate=/etc/ovn/podman-nb-cert.pem \
external_ids:ovn-nb-ca-cert=/etc/ovn/nb-cacert.pem
Fehlt eine Datei oder ist sie nicht lesbar, bricht das Plugin mit einer Meldung ab, die die fehlende Einstellung nennt. Bei tcp: gibt podman network create eine Warnung aus. Das Migrationsskript löst die Dateien genauso auf (zusätzlich --private-key/--certificate/--ca-cert).
Auf der NB-Seite z. B. ovn-nbctl set-connection pssl:6641 und ovn-nbctl set-ssl <key> <cert> <ca-cert>, wobei das CA-Zertifikat nur die Clients (Hosts) signiert, die schreiben dürfen.
Installation
Paket (Ubuntu 26.04 „resolute“)
Die CI baut bei jedem Commit auf master ein Paket und lädt es in die Forgejo-Debian-Registry:
echo "deb https://git.bocc.de/api/packages/jochen/debian resolute main" \
> /etc/apt/sources.list.d/forgejo-jochen.list
# Signing-Key der Registry einrichten, falls noch nicht geschehen
apt update && apt install netavark-ovs
Das Paket installiert das Plugin nach /usr/libexec/netavark/ovs. Das Verzeichnis steht in der Standardliste netavark_plugin_dirs (containers.conf), es ist also keine weitere Konfiguration nötig.
Manuell
apt install protobuf-compiler # vom build.rs des netavark-Crates benötigt
cargo build --release --locked
install -m 0755 target/release/ovs /usr/libexec/netavark/ovs
Kontrolle: podman info --format '{{.Plugins.Network}}' listet ovs.
Benutzung
# Netz anlegen -- legt den Logical Switch an, falls es ihn noch nicht gibt
podman network create --driver ovs --subnet 10.10.0.0/24 --gateway 10.10.0.1 net1
# Container starten
podman run -d --name web --network net1 --ip 10.10.0.5 nginx
Optionen am Netz (podman network create --opt key=value)
| Option | Bedeutung |
|---|---|
ovn_switch=NAME |
Name des Logical Switch; Standard ist der Netzname. Mehrere Hosts mit gleichem ovn_switch landen im selben L2-Segment. |
ovn_keep_ports=true |
Ports beim Stoppen des Containers nicht löschen (Adressen bleiben über Neustarts erhalten). |
ovn_external_ports=allow |
Container dürfen Ports nutzen, die nicht von Podman angelegt wurden (siehe unten). |
port_security=strict|mac-only|off |
Port-Security für Ports, die Podman gehören (siehe unten). Standard strict. |
Statische Routen (--route) werden im Container gesetzt.
Optionen pro Container-Anbindung
Das Plugin wertet zusätzlich zwei Optionen aus netavarks network_options.options (pro Container und Netz) aus:
| Option | Bedeutung |
|---|---|
lsp_name=NAME |
Fester Name des Logical Switch Ports statt des Standardnamens. Nützlich für eine stabile Identität (MAC/IP) über Neuanlagen des Containers hinweg. |
lsp_cleanup=keep|delete |
Überschreibt für diesen Container die Lösch-Policy des Netzes. |
Ab Podman 5.4 reicht --network unbekannte Schlüssel ungeprüft an netavark-Plugins durch:
podman run -d --network net1:lsp_name=web-01 nginx
Adressen
- Trägt der Logical Switch Port schon Adressen (vorprovisioniert, oder von einem früheren Start behalten), sind diese maßgeblich und werden nicht überschrieben. Steht dort nur
dynamic, werden die vonovn-northdvergebenen Adressen übernommen (Einschränkungen bei<mac> dynamicsiehe #7). - Sonst kommen MAC und IPs von Podman (
--mac-address,--ip); ohne MAC wird eine lokal administrierte erzeugt. Das Plugin schreibt sie dann alsaddressesundport_securityin den LSP. - Die Präfixlänge (und das Gateway) stammt aus dem netavark-Subnetz; fehlt das, aus
other_config:subnet(und optionalother_config:gateway) des Logical Switch; sonst wird die Adresse als /32 bzw. /128 ohne Gateway gesetzt (mit Warnung).
Port-Security
| Port | Verhalten |
|---|---|
| Von Podman angelegt oder übernommen | port_security wird bei jedem Start gesetzt, je nach Netzoption port_security: strict (Standard) = MAC und alle IPs; ohne bekannte IP startet der Container nicht, weil sonst jede Quell-IP durchginge. mac-only = nur die MAC. off = keine Port-Security (z. B. Router, VRRP/keepalived-VIPs). Das gilt auch, wenn die Adressen schon am Port stehen (behaltene Ports, dynamic). |
Außerhalb von Podman provisioniert (z. B. Netbox, freigegeben über podman-allowed=true bzw. ovn_external_ports=allow) |
port_security wird nie verändert, der Provisionierer ist maßgeblich – auch für zusätzliche Adressen wie VIPs. Ist das Feld leer, gibt das Plugin nur eine Warnung aus. |
Beispiel für einen in Netbox bzw. per Hand vorbereiteten Port mit VIP:
ovn-nbctl lsp-add net1 web-01 \
-- lsp-set-addresses web-01 "02:00:00:00:00:77 10.10.0.77" \
-- lsp-set-port-security web-01 "02:00:00:00:00:77 10.10.0.77 10.10.0.100" \
-- set logical_switch_port web-01 external_ids:podman-allowed=true
podman run -d --network net1:lsp_name=web-01 nginx
Ports und Eigentum
- Name:
<logical switch>-<erste 12 Zeichen der Container-ID>, z. B.net1-3f2a9c1b7d4e– eindeutig im ganzen OVN-Cluster, auch wenn auf mehreren Hosts gleichnamige Container laufen. Mitlsp_namefrei wählbar. - Eigentum steht in den
external_idsdes Ports:podman-owned=true,podman-container-id,podman-chassis. Anlegen und Markieren passiert in einer NB-Transaktion. - Vorhandene Ports werden nur verwendet, wenn sie auf dem richtigen Switch liegen, ein normaler VIF-Port sind (keine
router-/localnet-/…-Ports) und nicht von einem anderen laufenden Container belegt sind. Bei explizitemlsp_namewird ein Port übernommen, dessen bisheriger Container nicht mehr läuft. - Fremde Ports (nicht von Podman angelegt) nur mit Freigabe:
ovn-nbctl set logical_switch_port P external_ids:podman-allowed=trueoder--opt ovn_external_ports=allowam Netz. Solche Ports löscht das Plugin nie. - Beim Stoppen wird der Port gelöscht, wenn er diesem Container gehört und weder
ovn_keep_ports=truenochlsp_cleanup=keepgesetzt ist. - Übernehmen und Löschen eines Ports passieren als Compare-and-Swap (
ovsdb-client transactmitwait): Hat sich der Port seit dem Lesen geändert – etwa weil ein anderer Container ihn gerade übernommen hat –, schlägt die Übernahme mit Fehlermeldung fehl bzw. das Löschen unterbleibt. - Auf dem Host trägt das OVS-Interface
external_ids:podman-attachment=<container-id>/<netz-id>. Der Host-Interface-Nameveo<hash>ist ein 32-Bit-Hash; eine (sehr unwahrscheinliche) Namenskollision mit einer anderen laufenden Anbindung wird erkannt, der fremde Port bleibt unangetastet und der Start schlägt mit Fehlermeldung fehl.
Umstieg vom alten Namensschema
Ältere Versionen nannten Ports <switch>-<containername>. Behaltene Ports lassen sich auf jedem Host umbenennen (Probelauf ohne --apply):
python3 /usr/share/netavark-ovs/migrate-lsp-names.py # zeigt, was passieren würde
python3 /usr/share/netavark-ovs/migrate-lsp-names.py --apply
Fehlerverhalten
- Schlägt ein Containerstart fehl (z. B. ungültige Route), wird alles zurückgebaut, was dieser Start angelegt hat: OVS-Port, veth und – nur wenn neu angelegt – der Logical Switch Port.
- Reste früherer Fehlstarts derselben Anbindung werden beim nächsten Start entfernt.
- Teardown ist „best effort“: erst lokal (OVS-Port, veth), dann OVN; Fehler werden gesammelt gemeldet. Ist die NB-DB beim Stoppen nicht erreichbar, bleibt der LSP stehen, der OVS-Port wird trotzdem entfernt.
- Alle
ovs-vsctl/ovn-nbctl-Aufrufe haben ein Timeout von 30 s. - Das Plugin ruft seine Werkzeuge mit festem
PATHauf (/usr/sbin:/usr/bin:/sbin:/bin:/usr/local/sbin:/usr/local/bin).
Sicherheit
- Das Plugin läuft als root und braucht Schreibzugriff auf die Northbound-DB – damit lässt sich die gesamte logische Topologie ändern. Die DB-Verbindung daher auf vertrauenswürdige Hosts beschränken.
- Verbindung zur NB-DB über
ssl:mit Client-Zertifikaten (siehe TLS).tcp:ist unverschlüsselt und unauthentifiziert: Wer den Port erreicht, kann die komplette logische Topologie lesen und ändern. Die Northbound-DB kennt kein RBAC wie die Southbound-DB; der Schutz liegt allein darin, wer ein von der NB-CA signiertes Zertifikat hat und wer den Port erreicht (Firewall). - Port-Security: siehe oben. Für Ports, die das Plugin anlegt, ist sie standardmäßig streng (MAC und IPs).
Bekannte Einschränkungen
Siehe offene Issues, u. a.: MTU-Option wird ignoriert (#8, bei Geneve wichtig), route_type blackhole/unreachable/prohibit (#6), <mac> dynamic-Adressen (#7), Default-Route nur für die erste Adresse (#9), MAC-Erzeugung (#5).
Entwicklung
cargo fmt --check
cargo clippy --all-targets --locked -- -D warnings
cargo test --locked
Integrationstests gegen eine echte, frische Northbound-DB (ovn-central installiert):
mkdir -p /tmp/nb && ovsdb-tool create /tmp/nb/nb.db /usr/share/ovn/ovn-nb.ovsschema
ovsdb-server --detach --pidfile=/tmp/nb/pid --unixctl=/tmp/nb/ctl --remote=punix:/tmp/nb/nb.sock /tmp/nb/nb.db
OVN_NB_TEST_DB=unix:/tmp/nb/nb.sock cargo test --locked
OVN_NB_TEST_DB=unix:/tmp/nb/nb.sock python3 -m unittest tools/test_migrate_lsp_names.py
End-to-End-Test (root, braucht Network-Namespaces): startet in einem Temp-Verzeichnis ovsdb-server/ovs-vswitchd mit Userspace-Datapath (kein Kernelmodul) und eine NB-DB und ruft das Plugin-Binary wie netavark auf – Rollback bei Fehlstart, Reste alter Fehlstarts, behaltene Ports, Teardown bei nicht erreichbarer DB, Namenskollision, Port-Security eigener und extern provisionierter Ports, NB-Verbindung über ssl: mit eigener Test-CA:
cargo build --locked && sudo bash tests/e2e.sh target/debug/ovs
CI (.forgejo/workflows/): rust (fmt, clippy, Tests, Integrationstests, cargo audit, Release-Build) → deb (Paket in ubuntu:26.04, Installationstest, Upload bei master) → e2e (Paket im privilegierten ubuntu:26.04-Container auf dem podman-Runner); dazu gitleaks über die komplette Historie.
Release: Die Version steht nur in Cargo.toml (das Plugin meldet sie über CARGO_PKG_VERSION an netavark, das Paket heißt <Version>+git<N>.<sha>-1). packaging/check-version.sh prüft in der CI, dass Cargo.lock, das gebaute Binary (ovs info) und das Paket dazu passen, und bei einem Tag-Push, dass der Tag v<Version> ist:
bash packaging/check-version.sh --tag v0.2.0 --bin target/release/ovs