Network Resource Kind

Kind: NetworkapiVersion: pivirt.hu/v1Aliases: net, nets, bridge

The Network resource manages host-level network connectivity, virtual switches, Linux bridges, DHCP servers, and firewall routing domains on the hypervisor.

---

Accepted Kind Aliases

In pivirtctl commands, any of the following aliases are recognized: Network, network, networks, net, nets, bridge, bridges, hostbridge, hostbridges.

---

Example Manifests

Bridged Network (Uplink)

apiVersion: pivirt.hu/v1
kind: Network
metadata:
  name: physical-lan
  labels:
    scope: local-lan
spec:
  mode: bridged
  bridge: br0
  physicalPorts:
    - eth0
  mtu: 1500

NAT Network with Gateway

apiVersion: pivirt.hu/v1
kind: Network
metadata:
  name: internal-nat
  labels:
    scope: private
spec:
  mode: nat
  bridge: virbr10
  subnet: "192.168.100.0/24"
  gateway: "192.168.100.1"
  uplink: eth0
  mtu: 1500

Isolated Host Network

apiVersion: pivirt.hu/v1
kind: Network
metadata:
  name: airgapped-dmz
spec:
  mode: isolated
  bridge: virbr-dmz
  mtu: 1500

VLAN Filtering Trunk

apiVersion: pivirt.hu/v1
kind: Network
metadata:
  name: trunk-bridge
spec:
  mode: bridged
  bridge: br-trunk
  physicalPorts:
    - eth1
  vlanFiltering: true
  mtu: 9000 # Jumbo frames

---

Specification Reference (spec)

Field	Type	Required	Default	Description
mode	string	Yes	bridged	Network mode: isolated, nat, routed, bridged
bridge	string	No	br-<name>	Underlying Linux bridge device name in kernel
subnet	string	No		CIDR subnet block for NAT or routed addresses (e.g. 10.0.0.0/24)
gateway	string	No		Gateway IP address for the subnet
uplink	string	No		Physical parent interface for outbound NAT/routing
physicalPorts	list[string]	No	[]	Physical NICs bound to this bridge
vlanFiltering	bool	No	false	Enable kernel 802.1Q VLAN filtering on bridge
mtu	int	No	1500	MTU frame size in bytes

Network Modes Explained

• bridged: Directly attaches guest virtual interfaces to the host’s physical network uplink. Guests obtain IP addresses from the external LAN’s DHCP server.
• nat: Creates an isolated private subnet behind host NAT (masquerade). Guests can reach outbound networks through the host’s uplink interface.
• routed: Connects guests to a private subnet that is routed without NAT (requires upstream routing tables).
• isolated: Complete host-only network with no outbound traffic forwarding.

---

CLI Management Examples

# Apply network manifest
pivirtctl apply -f network-nat.yaml

# List all networks
pivirtctl get networks

# List using short alias
pivirtctl get nets

# Inspect bridge status and assigned TAP ports
pivirtctl describe network internal-nat

# Delete network (safely tears down bridge, iptables chains, and routing)
pivirtctl delete network internal-nat