NetworkSegment Resource Kind

Kind: NetworkSegmentapiVersion: pivirt.hu/v1Aliases: segment, segments

The NetworkSegment resource represents the host-local physical realization of a logical cluster Network.

While the Agent owns the logical definition of a network (which can span multiple physical nodes across a cluster), pivirtd owns the local network segment: which bridge interface to attach to, the local host’s gateway IP on that bridge, and the delegated DHCP range allocated exclusively to this physical node.

Accepted Kind Aliases

In pivirtctl commands, any of the following aliases are recognized: NetworkSegment, networksegment, networksegments, segment, segments.

Example Manifest

apiVersion: pivirt.hu/v1
kind: NetworkSegment
metadata:
  name: prod-segment-node-01
  labels:
    network: cluster-overlay
    node: node-01
spec:
  networkRef: cluster-overlay        # References the logical Network
  bridge: virbr10
  hostIP: "192.168.100.1/24"         # Local host gateway IP
  dhcp:
    enabled: true
    delegatedRangeStart: "192.168.100.10"
    delegatedRangeEnd: "192.168.100.50"
    dnsServers:
      - "1.1.1.1"
      - "8.8.8.8"
    defaultLeaseTime: 86400           # 24 hours

Specification Reference (`spec`)

Field	Type	Required	Default	Description
`networkRef`	`string`	Yes		Name of the parent logical `Network`
`bridge`	`string`	Yes		Local host Linux bridge device name (e.g. `virbr10`)
`overlay`	`string`	No		Name of an `OverlayNetwork` this segment rides on; `bridge` must then be the overlay’s OVS bridge, and this host’s address goes on its internal port
`hostIP`	`string`	Yes		Local host IPv4 address with CIDR prefix on the bridge
`dhcp.enabled`	`bool`	No	`true`	Enable host-level DHCP service for this segment
`dhcp.delegatedRangeStart`	`string`	Yes		Starting IP address of this node’s delegated lease pool
`dhcp.delegatedRangeEnd`	`string`	Yes		Ending IP address of this node’s delegated lease pool
`dhcp.dnsServers`	`list[string]`	No	`[]`	DNS nameservers advertised to DHCP clients
`dhcp.defaultLeaseTime`	`int`	No	`86400`	Lease lifetime duration in seconds

Delegated Range Partitioning

To allow multiple physical hypervisors to serve a single shared L2/L3 network without IP collisions:

The cluster Director or Agent divides the total network pool into non-overlapping delegated ranges.
Node 1 receives 192.168.100.10 – 192.168.100.50.
Node 2 receives 192.168.100.51 – 192.168.100.99.
pivirtd strictly enforces this range: it will refuse to allocate or lease any IP outside its assigned delegatedRangeStart and delegatedRangeEnd.

CLI Management Examples

# Apply a network segment manifest
pivirtctl apply -f segment.yaml

# List all local network segments
pivirtctl get segments

# Describe segment and view active delegation
pivirtctl describe segment prod-segment-node-01

# Delete a network segment
pivirtctl delete segment prod-segment-node-01