Skip to content

armgit / Pulse

Public Imported from GitHub
0

Real-time monitoring dashboard for Proxmox VE, PBS, Docker, Kubernetes, TrueNAS and vSphere. Self-hosted, with alerts for failed backups, full disks, unhealthy containers and offline nodes.

Explain guest IP selection without changing working networks

pulse-triage[bot]237c72afc938
diff --git a/docs/TROUBLESHOOTING.md b/docs/TROUBLESHOOTING.md
index 07e14f2c2f..75d796c6f5 100644
--- a/docs/TROUBLESHOOTING.md
+++ b/docs/TROUBLESHOOTING.md
@@ -279,6 +279,31 @@ restore, not by overwriting today's history. Follow
### Monitoring Data
+#### Primary IP shows a Podman or Docker bridge address
+
+On a Proxmox VM or LXC, **Primary IP** is Pulse's selected address, not proof of
+the guest's default route or reachability from your browser. In an agentless
+LXC, the collected addresses can be sorted independently of their interfaces,
+so a `podman0` or Docker bridge address can appear before the intended `eth0`
+address. The Proxmox API and Pulse agent use different collection paths; an
+agent's correct address does not establish that the API-only view is correct.
+
+For access, use the intended guest address from your existing Proxmox network
+configuration rather than assuming the displayed first address is suitable.
+In **Workloads**, hover over the guest's network icon to inspect **Network
+Interfaces**: when supplied, interface names appear beside their addresses.
+The guest's details also show **Other IPs** when more than one address is
+available. An address list without interface names does not establish which
+interface it belongs to; keep that association unknown rather than guessing
+from its prefix or position. These views do not test routing or connectivity.
+
+Do not remove a working bridge, renumber the guest, reinstall or add an agent,
+recreate the monitored connection, or run a guest-agent probe just to change
+this display. For a report, retain the collection path and the interface/address
+relationship already observed. Keep actual addresses, MACs and hostnames
+private, using consistent aliases to preserve which address belongs to which
+interface; a raw network or configuration dump is not needed.
+
#### Agent fleet update or identity issue
- If readings became mixed after adding another Proxmox installation, start
diff --git a/frontend-modern/public/docs/TROUBLESHOOTING.md b/frontend-modern/public/docs/TROUBLESHOOTING.md
index 07e14f2c2f..75d796c6f5 100644
--- a/frontend-modern/public/docs/TROUBLESHOOTING.md
+++ b/frontend-modern/public/docs/TROUBLESHOOTING.md
@@ -279,6 +279,31 @@ restore, not by overwriting today's history. Follow
### Monitoring Data
+#### Primary IP shows a Podman or Docker bridge address
+
+On a Proxmox VM or LXC, **Primary IP** is Pulse's selected address, not proof of
+the guest's default route or reachability from your browser. In an agentless
+LXC, the collected addresses can be sorted independently of their interfaces,
+so a `podman0` or Docker bridge address can appear before the intended `eth0`
+address. The Proxmox API and Pulse agent use different collection paths; an
+agent's correct address does not establish that the API-only view is correct.
+
+For access, use the intended guest address from your existing Proxmox network
+configuration rather than assuming the displayed first address is suitable.
+In **Workloads**, hover over the guest's network icon to inspect **Network
+Interfaces**: when supplied, interface names appear beside their addresses.
+The guest's details also show **Other IPs** when more than one address is
+available. An address list without interface names does not establish which
+interface it belongs to; keep that association unknown rather than guessing
+from its prefix or position. These views do not test routing or connectivity.
+
+Do not remove a working bridge, renumber the guest, reinstall or add an agent,
+recreate the monitored connection, or run a guest-agent probe just to change
+this display. For a report, retain the collection path and the interface/address
+relationship already observed. Keep actual addresses, MACs and hostnames
+private, using consistent aliases to preserve which address belongs to which
+interface; a raw network or configuration dump is not needed.
+
#### Agent fleet update or identity issue
- If readings became mixed after adding another Proxmox installation, start
diff --git a/scripts/tests/test_guest_network_troubleshooting_docs.py b/scripts/tests/test_guest_network_troubleshooting_docs.py
new file mode 100644
index 0000000000..70358d057d
--- /dev/null
+++ b/scripts/tests/test_guest_network_troubleshooting_docs.py
@@ -0,0 +1,74 @@
+#!/usr/bin/env python3
+"""Keep guest-address help on existing views, without changing guest networking.
+
+These are documentation/source checks, not a routing test or collector fix.
+"""
+
+from pathlib import Path
+import unittest
+
+
+ROOT = Path(__file__).resolve().parents[2]
+HEADING = "#### Primary IP shows a Podman or Docker bridge address\n"
+
+
+class GuestNetworkTroubleshootingDocsTest(unittest.TestCase):
+ def section(self):
+ guide = (ROOT / "docs/TROUBLESHOOTING.md").read_text(encoding="utf-8")
+ self.assertEqual(guide.count(HEADING), 1)
+ return " ".join(guide.split(HEADING, 1)[1].split("\n#### ", 1)[0].split())
+
+ def test_selected_address_is_not_default_route_or_collection_recovery(self):
+ text = self.section()
+ for distinction in (
+ "not proof of the guest's default route or reachability",
+ "agentless LXC",
+ "podman0",
+ "Proxmox API and Pulse agent use different collection paths",
+ "does not establish that the API-only view is correct",
+ "existing Proxmox network configuration",
+ "These views do not test routing or connectivity",
+ ):
+ with self.subTest(distinction=distinction):
+ self.assertIn(distinction, text)
+
+ def test_workaround_labels_and_interface_association_exist_in_product(self):
+ text = self.section()
+ row = (ROOT / "frontend-modern/src/components/Workloads/GuestRowCells.tsx").read_text()
+ drawer = (ROOT / "frontend-modern/src/components/Workloads/GuestDrawerOverview.tsx").read_text()
+ for label in ("Workloads", "Network Interfaces", "Other IPs"):
+ self.assertIn(label, text)
+ self.assertIn("Network Interfaces", row)
+ self.assertIn("props.networkInterfaces", row)
+ self.assertIn("iface.name", row)
+ self.assertIn("iface.addresses", row)
+ self.assertIn("'Other IPs', props.ipAddresses.slice(1)", drawer)
+ self.assertIn("when supplied", text)
+ self.assertIn("keep that association unknown", text)
+
+ def test_no_new_probe_network_change_or_public_identity_dump(self):
+ text = self.section()
+ for boundary in (
+ "Do not remove a working bridge",
+ "renumber the guest",
+ "reinstall or add an agent",
+ "recreate the monitored connection",
+ "run a guest-agent probe",
+ "relationship already observed",
+ "Keep actual addresses, MACs and hostnames private",
+ "consistent aliases",
+ "a raw network or configuration dump is not needed",
+ ):
+ with self.subTest(boundary=boundary):
+ self.assertIn(boundary, text)
+ self.assertNotIn("```", text, "use existing observations, not a copied command")
+
+ def test_shipped_help_is_byte_identical(self):
+ self.assertEqual(
+ (ROOT / "docs/TROUBLESHOOTING.md").read_bytes(),
+ (ROOT / "frontend-modern/public/docs/TROUBLESHOOTING.md").read_bytes(),
+ )
+
+
+if __name__ == "__main__":
+ unittest.main()