ZEDEDA WiKi

This page is read only. You can view the source, but not change it. Ask your administrator if you think this is wrong.
====== Local NI -- VM deployment trace (confirmed live) ======

[[zededa:edge-node-clustering:how-zed-cloud-directs-enc:network-instance-info|← Back to Network Instance]]

This page documents a full confirmed live trace of deploying a VM into a
Local (NATed) Network Instance on EVE-K, including all host-side and k3s-side
observations.

Device: ''c86eddc2-9a2f-4a0e-a761-25e70e7cbb89''\\
App Instance UUID: ''68766b45-9eeb-45a8-819f-26d1f60ca3d0''\\
Network Instance UUID: ''d07fe671-87bc-4576-8031-bde9b42bf90f'' (Local type, eth0)\\
Image volume: ''e9579d78-99f3-4b8f-9c16-3adbb32b2fd8'' (20Gi Longhorn)

-----

===== Phase timeline (confirmed live) =====

<code>
16:12:28 → Pending    VMI created by zedkube in k3s
16:12:30 → Scheduling KubeVirt scheduler running
16:12:48 → Scheduled  placed on node tf-demo-adv-en-1
16:12:52 → Running    VM booted
</code>

**Total time: 24 seconds from VMI creation to running.**

-----

===== EVE host side =====

==== NetworkInstanceStatus (confirmed live) ====

<code bash>
cat /run/zedrouter/NetworkInstanceStatus/d07fe671-87bc-4576-8031-bde9b42bf90f.json | \
  jq '{Activated, BridgeName, BridgeIPAddr, BridgeNum, MirrorIfName, Vifs, IPAssignments}'
</code>

^ Field ^ Value ^ Meaning ^
| ''Activated'' | ''true'' | NI fully programmed |
| ''BridgeName'' | ''"bn1"'' | New bridge created (BridgeNum 1) |
| ''BridgeIPAddr'' | ''"10.33.0.1"'' | Gateway IP on bridge |
| ''MirrorIfName'' | ''""`'' | No mirror interface for Local NI |
| ''Vifs'' | ''[{Name: nbu1x1, AppID: 68766b45...}]'' | VM VIF attached to bridge |

IP assignments confirmed:

^ MAC ^ IP ^ Assigned by ^
| ''00:16:3e:c2:c1:01'' | ''10.33.0.1'' | Static (bridge gateway, AssignedBy: 2) |
| ''02:11:22:33:44:55'' | ''10.33.0.20'' | DHCP via dnsmasq (AssignedBy: 4) |

==== VIF naming convention ====

The VM's virtual interface is named ''nbu1x1''. EVE's VIF naming scheme:

<code>
n  b  u  1  x  1
|  |  |  |  |  |
|  |  |  |  |  +-- app number
|  |  |  |  +----- separator
|  |  |  +-------- bridge number (matches bnX)
|  |  +----------- unit
|  +-------------- bridge
+----------------- network
</code>

So ''nbu1x1'' = network bridge unit, bridge 1, app 1.

==== Bridge confirmed (brctl show) ====

<code bash>
brctl show
</code>

<code>
bridge name   bridge id           STP   interfaces
bn1           8000.00163ec2c101   no    nbu1x1
</code>

''bn1'' has ''nbu1x1'' as its only interface when one VM is attached.
Before the VM was deployed, ''bn1'' existed but had no interfaces (state DOWN).
After VM deployment, ''nbu1x1'' appears in the bridge and state becomes UP.

==== dnsmasq lease (confirmed live) ====

<code bash>
cat /run/zedrouter/dnsmasq.leases/bn*
</code>

<code>
1781889194  02:11:22:33:44:55  10.33.0.20  68766b45-9eeb-45a8-819f-26d1f60ca3d0  *
</code>

^ Field ^ Value ^
| Lease expiry | ''1781889194'' (Unix timestamp) |
| VM MAC | ''02:11:22:33:44:55'' |
| Assigned IP | ''10.33.0.20'' |
| Hostname | App Instance UUID |

==== iptables MASQUERADE (confirmed live) ====

<code bash>
iptables -t nat -L POSTROUTING-apps -n | grep d07fe671
</code>

<code>
MASQUERADE  all  --  10.33.0.0/24  0.0.0.0/0
  /* SNAT traffic from NI d07fe671-... leaving via port eth0.253 */
</code>

**Key finding:** The uplink is ''eth0.253'' not bare ''eth0'' -- this NI uses a
VLAN subinterface (VLAN ID 253) on eth0 as its uplink.

==== AppNetworkStatus -- full VIF chain (confirmed live) ====

<code bash>
cat /run/zedrouter/AppNetworkStatus/68766b45-9eeb-45a8-819f-26d1f60ca3d0.json | jq
</code>

Key confirmed fields:

^ Field ^ Value ^ Meaning ^
| ''AppNetAdapterList[0].Name'' | ''enp1s0'' | Interface name inside the VM guest |
| ''AppNetAdapterList[0].Vif'' | ''nbu1x1'' | EVE VIF on the host bridge |
| ''AppNetAdapterList[0].Bridge'' | ''bn1'' | Host bridge |
| ''AppNetAdapterList[0].Network'' | ''d07fe671-...'' | NI UUID |
| ''AppNetAdapterList[0].AssignedAddresses'' | ''10.33.0.20'' | IP assigned by dnsmasq |
| ''AppNetAdapterList[0].IPv4Assigned'' | ''true'' | IP confirmed assigned |
| ''PodVif.GuestIfName'' | ''pod6c270ef2f25'' | Multus pod interface name |
| ''AppPod.Name'' | ''virt-launcher-tf-stnd-atl-vm-1-68766-0rt75r-sztt4'' | KubeVirt launcher pod |
| ''AppPod.NetNsPath'' | ''/var/run/netns/cni-0cd387de-...'' | Pod network namespace |

==== Full confirmed VIF chain ====

<code>
enp1s0                          inside the VM (guest interface)
    |
nbu1x1                          EVE VIF on host (in bridge bn1)
    |
pod6c270ef2f25                  Multus pod interface (in virt-launcher netns)
    |
bn1  (10.33.0.1/24)             Linux bridge -- gateway for 10.33.0.0/24
    |
eth0.253                        VLAN subinterface (VLAN ID 253) -- uplink
    |
eth0                            Physical NIC
    |
MASQUERADE (SNAT)               10.33.0.0/24 → external network
</code>

==== DomainStatus (confirmed live) ====

<code bash>
cat /run/domainmgr/DomainStatus/68766b45-9eeb-45a8-819f-26d1f60ca3d0.json | \
  jq '{State, VifList, BootTime}'
</code>

^ Field ^ Value ^ Meaning ^
| ''State'' | ''115'' | Running in EVE state machine |
| ''VifList[0].Bridge'' | ''"bn1"'' | Bridge the VIF is in |
| ''VifList[0].Vif'' | ''"nbu1x1"'' | VIF name on host |
| ''VifList[0].VifUsed'' | ''"nbu1x1"'' | Confirmed in use |
| ''VifList[0].PodVif.GuestIfName'' | ''"pod6c270ef2f25"'' | Multus pod VIF |
| ''BootTime'' | ''2026-06-19T16:12:52Z'' | VM boot time |

-----

===== k3s side =====

==== VMI spec (confirmed live) ====

The k3s VMI spec is **identical** to the Switch NI VMI spec. Kubernetes has
no knowledge of which NI type is being used. All NI-type logic is handled
entirely by the ''eve-bridge'' CNI plugin at the host level.

<code yaml>
networks:
- multus:
    networkName: network-instance-attachment   # same bootstrap NAD as Switch NI
  name: net1

interfaces:
- bridge: {}                                   # same bridge mode as Switch NI
  macAddress: "02:11:22:33:44:55"              # same EVE-assigned MAC format
  name: net1
  podInterfaceName: pod6c270ef2f25
  linkState: up
  infoSource: domain, multus-status            # confirmed by both KubeVirt and Multus
</code>

-----

===== Switch NI vs Local NI -- full comparison (both confirmed live) =====

^ Feature ^ Switch NI ^ Local NI ^
| Bridge | ''eth1'' itself | New ''bnX'' (e.g. ''bn1'') |
| VIF name in bridge | not yet observed | ''nbu1x1'' |
| VIF naming scheme | N/A | ''nbuBxA'' (B=bridge num, A=app num) |
| VifList in AppNetworkStatus | ''null'' | Populated with VIF + IP |
| IP assigned by EVE | No | Yes -- via dnsmasq (10.33.0.20) |
| dnsmasq lease | None | ''02:11:22:33:44:55 → 10.33.0.20'' |
| MASQUERADE rule | None | ''10.33.0.0/24 → eth0.253'' |
| Uplink | eth1 (L2 pass-through) | ''eth0.253'' (VLAN subinterface) |
| Mirror interface | ''eth1-m'' created | None |
| k3s VMI spec | ''bridge: {}'' · ''network-instance-attachment'' | Identical |
| NAD used | ''network-instance-attachment'' | ''network-instance-attachment'' |
| eve-bridge CNI | handles L2 bridging | handles L2 bridging + DHCP context |

**The VMI spec is identical for both NI types.** The NI type is completely
opaque to Kubernetes. The ''eve-bridge'' CNI plugin resolves all NI-specific
behaviour at runtime on the host.

-----

===== How to inspect a running VM on a Local NI =====

<code bash>
# NI status -- VIFs and IP assignments
cat /run/zedrouter/NetworkInstanceStatus/<ni-uuid>.json | \
  jq '{Activated, BridgeName, BridgeIPAddr, Vifs, IPAssignments}'

# App network status -- full VIF chain
cat /run/zedrouter/AppNetworkStatus/<app-uuid>.json | jq

# DHCP leases -- what IP did the VM get
cat /run/zedrouter/dnsmasq.leases/bn*

# Bridge -- confirm VIF is attached
brctl show bn1

# NAT rules -- confirm MASQUERADE
iptables -t nat -L POSTROUTING-apps -n | grep <ni-uuid>

# Domain status -- EVE's view of the running VM
cat /run/domainmgr/DomainStatus/<app-uuid>.json | jq '{State, VifList, BootTime}'

# k3s -- VMI
kubectl get vmis -n eve-kube-app
kubectl get vmi <name> -n eve-kube-app -o yaml
</code>

-----

===== Source references =====

  * ''pkg/pillar/cmd/zedrouter/'' -- zedrouter VIF and bridge management
  * ''pkg/pillar/cmd/domainmgr/'' -- domainmgr VIF list and domain status
  * ''pkg/kube/eve-bridge/'' -- eve-bridge CNI plugin
  * [[https://github.com/lf-edge/eve|lf-edge/eve on GitHub]]