Network Topology

The topology view is an editable desired-state graph overlaid with discovered libvirt runtime state. Keeping those two layers distinct prevents a card on the canvas from being mistaken for deployed infrastructure.

Graph model

Element	Desired state	Runtime evidence
VM node	Name, resources, disks, boot variant, position	Domain ID/name, power state, interfaces, deployment result
Network node	Logical name, type, subnet, position	Libvirt network name, bridge, active state, DHCP state
Edge	Intended VM-to-network attachment	Interface/MAC attached to the expected runtime network

Nodes can be planned, provisioning, running, stopped, or failed. Use the text state and deployment details; color is a secondary cue and can change with the UI theme.

Network choices

NAT networks provide guest egress through a managed libvirt network when the host and policy allow it.
Isolated networks provide VM-to-VM connectivity without an external route.
Additional bridge or direct-internet behavior is operator- and deployment-specific; it is not implied by drawing an edge.

For static addressing, the authored subnet, gateway, reserved addresses, DHCP range, MAC reservations, and guest configuration must agree. A graph edge alone does not configure an address inside an arbitrary guest.

Editing and deployment

Select the correct project/build scope before editing.
Add VM and network nodes and connect their handles.
Select a boot image and resources for every VM.
Save the topology and confirm the server revision advances.
Deploy nodes and wait for runtime overlay data.
Verify each desired edge against the VM’s actual interfaces.

Project topology is persisted on the server with revision checks. The UI also uses local caches and debounced saves, so wait for save completion before switching scope or closing the page. A save error means the canvas is not yet durable.

Example acceptance checks

For a client/API topology:


client -- isolated-lan -- api
                     \
                      nat-egress (only if required)

Verify all of the following:

both domains exist and are running;
both have an interface on the same runtime isolated network;
name/address resolution maps api to the intended guest;
a client-side http_responds assertion reaches the API health endpoint;
the isolated network has no unintended external route;
any NAT edge exists only where the recipe requires egress.

Refresh and export

Runtime state is refreshed from backend inventory and may lag a lifecycle request briefly. Manually refresh when validating a transition. Some topology views expose JSON export for documentation; an exported graph is desired-state data, not a backup of VM disks or proof that the runtime matched it.

See Creating VMs and Custom assertions.