Documenting and Monitoring Your Virtual Network Layout
A host fails at two in the morning. The cluster does its job: VMs restart on the surviving hosts, one by one. And the on-call phone stays mercifully quiet — except for one VM. It restarted fine, reports healthy, and is completely unreachable. The reason was discovered ninety minutes and much coffee later. The port group it needs exists on the host that died and on two others. But it does not exist on the host it landed on. Someone created it by hand, host by host, and missed one. The mistake was made months ago; it detonated tonight, because that is what undocumented virtual networks do — they save their surprises for failovers.
Physical networks get diagrams. Racks get elevation drawings, cables get labels, switch ports get spreadsheets — imperfect, but something. The virtual network almost never gets any of this. Which VM connects to which port group? Which VLANs are trunked to which host? Which uplink carries what? That topology exists only as dropdown selections scattered across a management interface, changeable in seconds, drawn by nobody. It is the layer of your network most likely to live entirely in one colleague's head. You can guess how durable that is.
This guide turns the invisible layout into something written down, and then — because documentation rots — into something monitored. You will learn what belongs in a virtual network inventory. You will learn why drift between hosts is the silent killer of migrations and failovers. The guide shows how to generate the inventory with exports and scripts instead of maintaining it by hand. It shows how to alert on configuration drift like any other fault. It explains which naming conventions prevent whole categories of mistakes. It also covers the quarterly audit ritual that keeps all of it honest.
In this guide
- The topology nobody draws
- What belongs in the inventory
- Drift between hosts: the silent migration killer
- Building the inventory: exports and scripts
- Keeping it beside the physical documentation
- Monitoring for drift
- Naming conventions that prevent mistakes
- The quarterly audit ritual
The topology nobody draws
Why does the virtual layer end up undocumented when the physical layer, mostly, does not? Three honest reasons. First, there is nothing to trace: no cable to follow, and no port LED to squint at. So the natural documentation trigger — standing in front of the rack, labeler in hand — never fires. Second, change is frictionless: adding a port group takes seconds and no purchase order, so configuration accumulates the way downloads folders do. Third, it mostly works anyway — the hypervisor does not need your diagram; only you do, and only on the bad days.
And the bad days are precisely when the gap hurts. Troubleshooting a VM's connectivity means answering "what is this VM actually connected to, and what does that connect to?" That is a thirty-second question with an inventory, an archaeology dig without one. The concepts in play (port groups, VLAN tagging at the virtual layer, uplinks) are covered in the virtual switch guide. This guide assumes them and deals with keeping track of the instances.
Be clear-eyed about who the inventory is for, because it is a longer list than "me, during outages." It is for the teammate covering your vacation, who has never opened your cluster. It is for the physical-network colleague who needs to know which trunks matter before touching a switch. It is for the auditor asking which systems can reach the payment VLAN. That is a question that is either an afternoon of clicking or a thirty-second grep. And it is for future you, who in a year will remember none of the reasons behind today's obvious-seeming choices.
What belongs in the inventory
A useful virtual network inventory answers questions at three layers, and it is worth being explicit about what each layer must record and why:
| Layer | Record | The question it answers at 2 AM |
|---|---|---|
| Host / virtual switch | Each host's vSwitches; port groups with VLAN IDs; MTU; teaming and failover policy; which pNICs are uplinks | "Can this VM run on that host?" |
| VM connections | Each VM: host, port group per vNIC, MAC address, IP address | "What is this unreachable VM supposed to be connected to?" |
| Physical boundary | Each uplink: which pNIC cables to which switch and port; VLANs allowed on that trunk | "Which cable and trunk does this VM's traffic actually ride?" |
The third layer is the one everyone skips and everyone regrets skipping. The uplink-to-switch-port mapping is the seam between two worlds — usually two teams' worlds. Most cross-layer outages live exactly on that seam. For example, a VLAN is present in a port group but missing from the physical trunk. Or a cable was moved to a different switch port during unrelated work. Or a teaming policy assumes both uplinks reach the same VLANs when only one does. Write the seam down. One clarification of scope: this is a topology inventory, deliberately narrow. The MTU column earns its place because a mismatch in MTU (the largest frame size a link will carry) produces the weirdest symptoms in networking. The mismatch can be between hosts or between host and switch. Small traffic flows while large transfers hang.
Just as important is what to leave out, because inventories die of obesity as often as neglect. Skip anything that churns hourly, such as VM power state and live traffic figures. That is monitoring's job, not documentation's. Also skip anything already mastered elsewhere. Your address-management records own IP assignments. Reference them rather than copying them into a second place that will disagree within a month. An inventory that tracks the slow-moving truths stays accurate enough to trust; one that tries to track everything is stale by design.
Drift between hosts: the silent migration killer
Drift is what happens when configurations that are supposed to be identical stop being identical. In a cluster, every host is supposed to offer the same virtual networks. That sameness is exactly what makes live migration and failover possible. That is because a VM can only move to a host that offers the network it is connected to. Per-host configuration plus human hands plus time equals drift, with a small bestiary of forms:
- The missing port group — present on three hosts, absent on the fourth. Migrations to that host fail or are quietly never offered; failover restarts land VMs there with nothing to connect to. This is the opening story of this guide, and the most common species by far.
- The same name with different settings — nastier than absence. The port group exists everywhere, but on one host it carries the wrong VLAN ID. The VM migrates successfully, connects successfully, and drops onto the wrong network — unreachable, or worse, reachable by the wrong things. Nothing errors, because nothing knows anything is wrong.
- Policy and MTU mismatches — different teaming policies or MTU values between hosts, producing performance personality changes and partial weirdness after a VM moves.
- Physical trunk drift — the virtual side matches perfectly, but one host's trunk no longer carries a VLAN the others carry. That is because a switch change missed a port. All virtual-layer comparisons pass; the VM still goes dark on that host.
Note the shared trait: drift is invisible during normal operation and detonates during abnormal operation — the failover, the evacuation, the emergency rebalance. It is a defect that waits for your worst moment by construction. Cluster-wide distributed switches (configured once, applied everywhere) eliminate much of the per-host species and are worth using where you have them. But they do not touch physical trunk drift, and plenty of environments still run per-host switches. Detection remains your job either way.
Building the inventory: exports and scripts
Here is the rule that makes this achievable for a busy admin: generated documentation beats hand-maintained documentation, every time, for anything a machine can enumerate. Every virtualization platform has a command-line interface or management API. It can list hosts, virtual switches, port groups with their VLAN IDs, and VMs with their connections. The exact commands vary by platform, but the capability is universal. A modest script (scheduled, not run-when-remembered) can walk those lists and write a dated snapshot to a file share or repository. Flat text or CSV is ideal — diffable, greppable, future-proof:
generated: (date) by inventory script, do not hand-edit host,vswitch,portgroup,vlan,mtu,uplinks hv-01,vsw0,pg-vlan20-servers,20,1500,pnic0+pnic1 hv-01,vsw0,pg-vlan30-app,30,1500,pnic0+pnic1 hv-01,vsw1,pg-vlan50-storage,50,9000,pnic2+pnic3 hv-02,vsw0,pg-vlan20-servers,20,1500,pnic0+pnic1 hv-02,vsw0,pg-vlan30-app,30,1500,pnic0+pnic1 hv-02,vsw1,pg-vlan50-storage,50,1500,pnic2+pnic3
The script itself follows the same skeleton on any platform, whatever the command names turn out to be:
- 1. Ask the management layer for the list of hosts (never hard-code it — hard-coded host lists are how the newest host escapes auditing).
- 2. For each host, list its virtual switches, then each switch's port groups with VLAN ID, MTU, and teaming policy, then its uplink assignments.
- 3. List every VM's connections: which port group each vNIC uses, plus MAC address.
- 4. Write it all to a dated file in a fixed column order, and keep the old files.
Two habits multiply the value. Keep every dated snapshot, not just the latest. History turns "when did this change?" from a shrug into a lookup. The diff between two snapshots is often the entire root-cause analysis of an incident. And let the machine-generated file be the authority for everything it covers. Reserve human-written notes for what scripts cannot know: why a port group exists, who owns the odd one, what the exception is for. (Sharp-eyed readers have already spotted the storage MTU mismatch sneaking through that sample — hold that thought for the drift-monitoring section.)
Keeping it beside the physical documentation
The virtual inventory must live next to the physical network documentation, not in a separate wiki nobody cross-references. The whole point of recording the seam is lost if the two sides cannot be read together. The craft of drawing and maintaining the physical side is its own topic, well covered in the network diagrams guide. The virtualization addition is one overlay view per cluster. Hosts go across the top, with each host's vSwitches and port groups (with VLAN IDs) beneath. Uplinks are drawn down to the named physical switch ports they cable into. One page per cluster, regenerated or redrawn when the export says something changed. A picture at this seam routinely answers in seconds what two teams' separate documents cannot answer in an hour. And it makes drift visually obvious, because the host whose column looks different is the problem.
Monitoring for drift
Documentation tells you what the layout was; monitoring tells you when it stops being that. Since drift is a defect that hides until failover, do not wait for failovers to find it — schedule the finding. The recipe is short: export each host's network configuration on a schedule (you already built this one section ago). Normalize the output (sort it, strip timestamps). And compare — each host against a chosen reference host in the same cluster, and today's export against yesterday's. Any difference is either an approved change (it should match a change record) or drift (it should page somebody, politely, during business hours). A drift check's output reads like this:
cluster prod-a, drift check vs reference hv-01 hv-02: OK hv-03: MISSING portgroup pg-vlan40-dmz hv-03: MISMATCH pg-vlan30-app vlan=31 (expected 30) hv-04: MISMATCH vsw1 mtu=1500 (expected 9000)
Every line is a failover incident that now will not happen — found on a calm Tuesday instead of during an evacuation. Compare, at minimum: port group names per host, VLAN ID per port group, MTU per vSwitch, teaming policy, and uplink count. Where your platform's API exposes physical trunk information (or your switches can be queried for it), compare the seam too. That means VLANs used by port groups versus VLANs allowed on each host's trunks. Do this because, as the drift bestiary showed, the virtual layers can agree perfectly while one trunk quietly ruins everything. Treat drift alerts with the seriousness of a failed disk in a mirror: nothing is down, but your redundancy is now partly fiction.
Keep the check trustworthy by keeping it quiet. Daily is a sensible cadence; drift is measured in weeks, not minutes. Normalize aggressively before diffing. Sort every list, fix the column order, and drop timestamps and cosmetic fields. That is because a comparison that cries wolf over reordered lines will be ignored within a fortnight. An ignored drift check is precisely as useful as no drift check. The standard for this alert is the standard for every alert: when it fires, somebody acts.
Naming conventions that prevent mistakes
Every VM connection is a human picking a name from a dropdown, which makes port group names a genuine safety mechanism — or a trap. Four principles do most of the work:
- Encode the VLAN and the purpose in the name. A tech seeing
pg-vlan30-appcan sanity-check it against the drift report and the trunk config without opening anything. - Be boringly consistent — same prefix, same order, same case, across every host and cluster. Consistency is what makes the missing one stand out in a sorted list.
- Never create near-twins. Names differing by one character are a misclick-shaped accident waiting in every dropdown.
- Rename rarely and deliberately. On many platforms, VM connections and automation reference port groups by name — a casual rename can strand VMs or break scripts. Treat a rename as a change project, not a tidy-up.
| Name | Verdict | Why |
|---|---|---|
| pg-vlan30-app | Good | Purpose and VLAN visible at a glance; sorts cleanly |
| pg-vlan50-storage-9k | Good | Even flags the jumbo MTU expectation |
| Production2 | Bad | Which VLAN? Which production? What was 1? |
| pg-app / pg-app2 / pg_app | Terrible | Three near-twins; the misclick is only a matter of time |
| TempTest-DO-NOT-USE | Famous | Will be in production use within the year |
Tip: resist deleting an unfamiliar port group just because it shows zero connected VMs today. Some things connect rarely — a replication target, a recovery-runbook network, the port group a failover process expects to find. Trace it to an owner first; the inventory's human-notes column is exactly where that answer should already be waiting.
The quarterly audit ritual
Scheduled comparisons catch mechanical drift; the audit catches what scripts cannot — the reality gap. Once a quarter, one afternoon, one named owner, this checklist:
- 1. Regenerate everything. Fresh inventory export from every host; confirm the scheduled exports and drift checks have actually been running (silent scheduled-task death is its own drift).
- 2. Diff against last quarter. Read every change and match it to a memory or a change record. Anything unexplained gets explained now, while the trail is warm.
- 3. Verify cluster symmetry. Every port group should be on every host in each cluster, with VLANs and MTU matching. Your drift check says this daily. The audit confirms the drift check itself is telling the truth.
- 4. Walk the seam. For each host, compare the VLANs its port groups use against the VLANs its uplink trunks allow. Spot-check that cable-to-switch-port records match the switches' own view of what is plugged where.
- 5. Fly the canary. Live-migrate a harmless test VM through every host in the cluster, one hop at a time. Ten minutes of clicking, and it proves — not assumes — that every host can actually receive a VM. The canary lands on the host with the missing port group so a production failover doesn't have to.
- 6. Spot-check five VMs. Pick a handful at random; confirm the inventory's claims about their host, port group, and addresses against reality.
- 7. Refresh the overlay diagram and file the dated audit note: what drifted, what was fixed, what exceptions remain and who owns them.
First run: expect findings and budget the afternoon generously. Subsequent runs shrink fast, and the ritual becomes pleasantly dull — which is the goal. A boring audit is the sound of failovers that will work.
Where to go next
The virtual network stops being folklore the day it is generated into a file, compared on a schedule, named with discipline, and audited on a calendar. None of it is glamorous; all of it is cheap next to one two-in-the-morning archaeology dig. This guide closes the loop the rest of the pillar opened. The concepts from virtual switch basics assume you can answer "what is connected to what." So do the traffic realities of the invisible east-west path and uplink contention. So does the host focus of hypervisor host monitoring. Now you can, in writing. The rest of the pillar lives at Virtualization & Hypervisor Networking.
Put this into practice with SysPeep Monitor
SysPeep Monitor is a monitoring tool rather than a documentation system — but it keeps the physical half of your inventory honest. It auto-discovers devices and interfaces as they appear. Its live network maps and dashboards show what is actually connected and how it is doing. That makes a wonderful cross-check for the virtual layout you just documented. The free trial installs in minutes on any Windows machine.
Download Free TrialLearn About SysPeep