Glossary & concepts

Concepts

Short explanations of concepts used across the test plans — networking, storage, secrets management, and more — for anyone who does not work with them every day.

macvtap (NOT supported) vs. OVN-K localnet (official path)

macvtap gives a VM its own MAC — but is NOT officially supported in OpenShift Virtualization. The correct approach is OVN-K localnet.

A VM that must speak on the LAN (real IP, reachable from outside, no NAT) needs its own MAC address — otherwise the switch cannot tell which traffic belongs to the host and which belongs to the VM. macvtap (a KubeVirt upstream feature) solves this via a virtual interface directly on the physical NIC. In practice, macvtap was attempted on this cluster — registering it via the HyperConverged CR fails ('unknown field spec.networking'), and VM start fails with 'couldn't find configuration for network binding: macvtap'. OpenShift Virtualization does not support macvtap as a network binding plugin. Official documentation (OCP 4.20) confirms: Bridge CNI and VLAN are not supported; OVN-Kubernetes secondary overlay networks are recommended instead.

✓ ADVANTAGES

OVN-K localnet: officially supported, documented, works even when the NIC is already in use
Uses the existing br-ex infrastructure — no additional bridge required
NetworkPolicies and other OVN-K features remain available

⚠ LIMITATIONS

macvtap: NOT supported in OCP — the NAD can be created, but VM start fails
OVN-K localnet requires a NodeNetworkConfigurationPolicy with bridge-mappings (NMState >= 2.2.x)
Somewhat more configuration effort than a simple macvtap NAD

COMPARISON

macvtap (do NOT use): KubeVirt upstream feature, not registered in OCP. Causes runtime errors on VM start.

OVN-K localnet ([TC-NET-002](TC-NET-002)): Officially supported path. Maps a second logical network onto br-ex via NodeNetworkConfigurationPolicy + NAD with topology: localnet.

Linux bridge: All VMs sit 'behind' one shared bridge MAC. Only works if the NIC is still free (not the case with eno2/br-ex).

📍 WHY IT MATTERS HERE

On this Hetzner SNO, eno2 is already fully consumed by OVN-K on br-ex. An additional Linux bridge directly on eno2 is not possible. macvtap would have bypassed that in theory, but is not usable in OCP — the official and tested path is OVN-K localnet (see TC-NET-002), which works via br-ex without occupying the NIC again. Verified on 30 Jun 2026: the NNCP with ovn.bridge-mappings was applied successfully on this cluster (Status Available, 'successfully reconciled') — the correct field name is bridge (not bridge-mapping, a common pitfall).

WaitForFirstConsumer (StorageClass binding mode)

A PVC stays deliberately 'Pending' until a pod/VM actually uses it — not an error!

NodeNetworkConfigurationPolicy (NNCP)

Declarative node network configuration via the Kubernetes API — instead of manual nmcli commands.

OVN-Kubernetes & br-ex

OpenShift's default network plugin uses an OVS bridge (br-ex) that takes over the physical NIC.

HCP: does every hosted cluster need its own public IP?

No — only the API server (with the KubeVirt/on-prem provider) needs a dedicated IP or dedicated port. OAuthServer, Konnectivity, and Ignition already share the management cluster's existing Ingress route today.

Sealed vs unsealed — why pods stay 0/1 Ready

A sealed OpenBao holds only encrypted data and refuses almost every request — the pod runs but is not Ready. Unsealing reconstructs the barrier key.

KV v2 — versions, soft delete, and check-and-set (CAS)

KV v2 keeps a version history per secret and can require a version number on every write — a write is a whole new version, not a field update.

Kubernetes auth method — SA token in, OpenBao token out

Pods authenticate with their projected ServiceAccount JWT; OpenBao validates it against the kube-apiserver and returns a short-lived token carrying the role's policies.

OpenBao vs Vault — why /vault/ still appears everywhere

OpenBao is the Linux Foundation fork of HashiCorp Vault and keeps API and tooling compatibility — so UI routes, sidecar paths, and third-party integrations still say 'vault'.

Raft integrated storage — leader, quorum, snapshots

OpenBao stores data itself and replicates it with the Raft consensus protocol — no external database, but quorum rules apply.

📚 Glossary & concepts

Glossary & concepts