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.

Preserve Proxmox guest interface names in Workloads

pulse-triage[bot]3efa4d84422e
diff --git a/docs/release-control/v6/internal/HIGH_RISK_RELEASE_VERIFICATION_MATRIX.md b/docs/release-control/v6/internal/HIGH_RISK_RELEASE_VERIFICATION_MATRIX.md
index cb94e54643..d26860c606 100644
--- a/docs/release-control/v6/internal/HIGH_RISK_RELEASE_VERIFICATION_MATRIX.md
+++ b/docs/release-control/v6/internal/HIGH_RISK_RELEASE_VERIFICATION_MATRIX.md
@@ -8,6 +8,22 @@ A gate is only `passed` when its automated proof still passes and the manual
scenario has been exercised in a staging-like environment with the expected
result.
+## Workloads guest interface source selection — issue #2757
+
+Automated: `useWorkloads.test.ts` (both REST and owning-snapshot VM/LXC
+projections) and `GuestDrawer.test.tsx` (independent platform/agent freshness).
+Consume actual collector/HTTP/broadcast JSON through the production hook,
+GuestRow network tooltip and GuestDrawer details on desktop and narrow touch.
+The primary IP stays first; secondary addresses stay beside their producer's
+interface names. Live and silent linked-agent lists retain precedence, and
+explicitly empty lists are not replaced by the other source. Change producers
+on the same mounted guest: only selected agent interfaces inherit agent-stale
+copy/tone, while the agent's other last-known readings remain last known.
+
+Synthetic browser fixtures are not installed Proxmox routing or reporter
+acceptance. No guest query, networking change, agent installation or native
+recovery action is required to validate this consumer repair.
+
## Workloads locked-guest identity on phones
Automated: `GuestRow.test.tsx` lock-label cases and
diff --git a/docs/release-control/v6/internal/subsystems/performance-and-scalability.md b/docs/release-control/v6/internal/subsystems/performance-and-scalability.md
index 42d0bab240..e2f3be1802 100644
--- a/docs/release-control/v6/internal/subsystems/performance-and-scalability.md
+++ b/docs/release-control/v6/internal/subsystems/performance-and-scalability.md
@@ -15,6 +15,17 @@
## Purpose
+### Existing Workloads snapshots retain guest interface names
+
+The Workloads mapper selects the existing agent interface list, otherwise the
+existing Proxmox list, on both REST and owning-snapshot paths. It adds no fetch,
+sort, cross-producer merge or retained cache. Explicitly empty agent lists keep
+precedence. Source provenance travels with the selected list so a source change
+on the same canonical row updates only its owning last-known presentation.
+`useWorkloads.test.ts` checks VM/LXC transitions, unchanged ordered IPs and
+identities, eight normal REST reads versus zero Workloads requests for the
+owning-snapshot path. This is consumer proof, not native collection recovery.
+
### Guest filesystem guidance remains reachable by touch and keyboard (13 October 2026)
The existing Filesystems footer link in the guest drawer has a 44px minimum
diff --git a/docs/release-control/v6/internal/subsystems/unified-resources.md b/docs/release-control/v6/internal/subsystems/unified-resources.md
index 2dca89f9d5..220c2bbe8b 100644
--- a/docs/release-control/v6/internal/subsystems/unified-resources.md
+++ b/docs/release-control/v6/internal/subsystems/unified-resources.md
@@ -23,6 +23,28 @@ and sort the complete canonical change table while startup and ingestion wait.
## Purpose
+### Workloads preserve platform guest interfaces — issue #2757
+
+Both the `/api/resources` and owning canonical-snapshot Workloads projections
+retain `proxmox.networkInterfaces` when the linked agent reports no interface
+list. A present agent list still wins, including an explicit empty list;
+lists from different producers are not merged. Names, addresses, MACs and
+reported traffic retain their association. The selected identity/IP order,
+canonical row and History coordinates do not change.
+
+`networkInterfacesFromAgent` is internal frontend provenance. Only the selected
+agent list inherits `agentStale` in the drawer's Network section. A silent linked
+agent still marks its other readings last known, but cannot mark independently
+supplied Proxmox interfaces as its last report. Legacy drawer callers keep their
+existing agent-freshness semantics. This adds no wire field, guest query,
+collection command, permission or native freshness/recovery guarantee.
+
+`useWorkloads.test.ts` checks REST/snapshot VM and LXC source transitions,
+agent precedence, empty/absent lists, IP order and stable canonical identity;
+`GuestDrawer.test.tsx` checks reactive source-specific last-known presentation
+without clearing agent RAID/filesystem warnings. Desktop and narrow browser
+proof must consume producing JSON, not manually populated WorkloadGuest rows.
+
### Independently known PBS remains available in Backups (13 October 2026)
The resource-owned PBS table is outside backup-inventory loading/error gates.
diff --git a/frontend-modern/src/components/Workloads/GuestDrawer.test.tsx b/frontend-modern/src/components/Workloads/GuestDrawer.test.tsx
index ac3c326022..eb268a507e 100644
--- a/frontend-modern/src/components/Workloads/GuestDrawer.test.tsx
+++ b/frontend-modern/src/components/Workloads/GuestDrawer.test.tsx
@@ -1480,6 +1480,37 @@ describe('GuestDrawer', () => {
);
});
+ it('keeps Proxmox interface freshness independent of a silent linked agent', () => {
+ const [guest, setGuest] = createSignal(
+ makeAgentGuest({ agentStale: true, networkInterfacesFromAgent: false }),
+ );
+ render(() => <GuestDrawer guest={guest()} onClose={vi.fn()} />);
+ const staleNetwork =
+ 'Using last known interface details. The Pulse Agent in this guest stopped reporting.';
+ const networkValue = () =>
+ technicalDetails()
+ .getByText(/^192\.168\.1\.5/)
+ .closest('td');
+ expect(technicalDetails().getByText('eth0')).toBeInTheDocument();
+ expect(technicalDetails().queryByText(staleNetwork)).toBeNull();
+ expect(networkValue()).not.toHaveClass('text-muted');
+ // This source distinction does not make the agent's other readings current.
+ expect(technicalDetails().getByText(/^Last known 75%/)).toBeInTheDocument();
+ expect(screen.getByTestId('raid-card-array')).toHaveAttribute(
+ 'data-raid-reading',
+ 'last-known',
+ );
+
+ setGuest({ ...guest(), networkInterfacesFromAgent: true });
+ expect(technicalDetails().getByText(staleNetwork)).toBeInTheDocument();
+ expect(networkValue()).toHaveClass('text-muted');
+
+ setGuest({ ...guest(), networkInterfacesFromAgent: false });
+ expect(technicalDetails().queryByText(staleNetwork)).toBeNull();
+ expect(networkValue()).not.toHaveClass('text-muted');
+ expect(technicalDetails().getByText(/^Last known 75%/)).toBeInTheDocument();
+ });
+
it('keeps a live in-guest agent current when Proxmox has no guest reads', () => {
render(() => <GuestDrawer guest={makeAgentGuest()} onClose={vi.fn()} />);
diff --git a/frontend-modern/src/components/Workloads/GuestDrawerOverview.tsx b/frontend-modern/src/components/Workloads/GuestDrawerOverview.tsx
index 0c7a97bd9c..9092924370 100644
--- a/frontend-modern/src/components/Workloads/GuestDrawerOverview.tsx
+++ b/frontend-modern/src/components/Workloads/GuestDrawerOverview.tsx
@@ -140,6 +140,8 @@ export function GuestDrawerOverview(props: GuestDrawerOverviewProps) {
// the guest, so its RAID, network and filesystem rows read as last known.
const agentLastKnownReason = () =>
props.guest.agentStale ? HOST_AGENT_STOPPED_REPORTING_REASON : undefined;
+ const networkLastKnownReason = () =>
+ props.guest.networkInterfacesFromAgent === false ? undefined : agentLastKnownReason();
const coverageLabel = () => {
if (props.hasWorkloadActionAgent) return WORKLOAD_ACTION_AGENT_LABEL;
if (props.hasAgentInfo) return `${props.agentHeading} observed`;
@@ -327,10 +329,11 @@ export function GuestDrawerOverview(props: GuestDrawerOverviewProps) {
? {
label: 'Network',
rows: compactDetailRows([
- // Only the linked Pulse agent reports guest interfaces.
+ // Agent freshness applies only to the selected agent list,
+ // not interfaces supplied independently by Proxmox.
makeDetailRow(
'Status',
- agentLastKnownReason()
+ networkLastKnownReason()
? 'Using last known interface details. The Pulse Agent in this guest stopped reporting.'
: null,
{ layout: 'stacked', wrap: true },
@@ -353,7 +356,7 @@ export function GuestDrawerOverview(props: GuestDrawerOverviewProps) {
iface.name || `Interface ${index + 1}`,
detail || 'No details',
{
- tone: agentLastKnownReason() ? 'muted' : undefined,
+ tone: networkLastKnownReason() ? 'muted' : undefined,
wrap: true,
},
);
diff --git a/frontend-modern/src/hooks/__tests__/useWorkloads.test.ts b/frontend-modern/src/hooks/__tests__/useWorkloads.test.ts
index 420ad6cdae..a3df954eb8 100644
--- a/frontend-modern/src/hooks/__tests__/useWorkloads.test.ts
+++ b/frontend-modern/src/hooks/__tests__/useWorkloads.test.ts
@@ -3,6 +3,7 @@ import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
import useWorkloadsSource from '../useWorkloads.ts?raw';
import { guestDiskDeferrals } from '@/components/Workloads/__fixtures__/guestDiskDeferrals';
import type { VM } from '@/types/api';
+import type { Resource } from '@/types/resource';
import { getWorkloadGuestDiskRead } from '@/utils/workloadGuestPresentation';
import { getDiskUsagePercent, getWorkloadGroupKey } from '@/components/Workloads/workloadSelectors';
@@ -82,6 +83,121 @@ describe('useWorkloads', () => {
resetWorkloadsCacheForTests();
});
+ it.each(
+ (['api', 'snapshot'] as const).flatMap((transport) =>
+ (['vm', 'system-container'] as const).map((type) => ({ transport, type })),
+ ),
+ )(
+ 'preserves selected guest network interfaces through $transport for $type',
+ async ({ transport, type }) => {
+ const platformInterfaces = [
+ { name: 'eth0', addresses: ['192.0.2.80'], mac: '02:00:00:00:00:80' },
+ { name: 'podman0', addresses: ['10.88.0.1'] },
+ ];
+ const agentInterfaces = [
+ { name: 'ens18', addresses: ['192.0.2.80'], rxBytes: 1024, txBytes: 2048 },
+ ];
+ const resource: Resource = {
+ id: `${type}-site-a-2757`,
+ type,
+ name: 'guest-2757',
+ displayName: 'guest-2757',
+ platformId: 'site-a',
+ platformType: 'proxmox-pve',
+ sourceType: 'api',
+ sources: ['proxmox'],
+ status: 'running',
+ identity: { ips: ['192.0.2.80', '10.88.0.1'] },
+ metricsTarget: { resourceType: type, resourceId: 'site-a-node-a-2757' },
+ proxmox: {
+ vmid: 2757,
+ nodeName: 'node-a',
+ instance: 'site-a',
+ networkInterfaces: platformInterfaces,
+ },
+ };
+ const apiResource = (value: Resource) => ({
+ ...value,
+ identity: { ipAddresses: value.identity?.ips },
+ });
+ const [snapshot, setSnapshot] = createSignal([resource]);
+ apiFetchJSONMock.mockResolvedValue({ data: [apiResource(resource)] });
+ let dispose = () => {};
+ let result!: ReturnType<UseWorkloadsModule['useWorkloads']>;
+ createRoot((d) => {
+ dispose = d;
+ result = useWorkloads(
+ () => true,
+ transport === 'snapshot' ? { resourceSnapshot: snapshot } : {},
+ );
+ });
+ const update = async (value: Resource) => {
+ if (transport === 'snapshot') setSnapshot([value]);
+ else {
+ apiFetchJSONMock.mockResolvedValue({ data: [apiResource(value)] });
+ await result.refetch();
+ }
+ await flushAsync();
+ };
+ const check = (
+ interfaces: typeof platformInterfaces | typeof agentInterfaces,
+ fromAgent: boolean,
+ ) => {
+ const guest = result.workloads()[0];
+ expect(guest).toMatchObject({
+ id: resource.id,
+ canonicalResourceId: resource.id,
+ metricsTarget: resource.metricsTarget,
+ vmid: 2757,
+ node: 'node-a',
+ instance: 'site-a',
+ ipAddresses: ['192.0.2.80', '10.88.0.1'],
+ networkInterfacesFromAgent: fromAgent,
+ });
+ expect(guest.networkInterfaces).toEqual(interfaces);
+ };
+ try {
+ await waitForWorkloadCount(() => result.workloads().length);
+ check(platformInterfaces, false);
+ // An agent facet without interfaces does not erase API-provided names
+ // or make those API readings part of the silent agent's last report.
+ await update({ ...resource, agent: { agentId: 'linked-agent', stale: true } });
+ check(platformInterfaces, false);
+ expect(result.workloads()[0].agentStale).toBe(true);
+ await update({
+ ...resource,
+ agent: { agentId: 'linked-agent', networkInterfaces: agentInterfaces },
+ });
+ check(agentInterfaces, true);
+ await update({
+ ...resource,
+ agent: { agentId: 'linked-agent', stale: true, networkInterfaces: agentInterfaces },
+ });
+ check(agentInterfaces, true);
+ expect(result.workloads()[0].agentStale).toBe(true);
+ // A reported empty list remains authoritative; do not resurrect a
+ // different producer's interfaces merely because this list is empty.
+ await update({ ...resource, agent: { agentId: 'linked-agent', networkInterfaces: [] } });
+ check([], true);
+ await update({ ...resource, proxmox: { ...resource.proxmox, networkInterfaces: [] } });
+ check([], false);
+ await update({
+ ...resource,
+ proxmox: { ...resource.proxmox, networkInterfaces: undefined },
+ });
+ expect(result.workloads()[0].networkInterfaces).toBeUndefined();
+ expect(result.workloads()[0].networkInterfacesFromAgent).toBeUndefined();
+ await update(resource);
+ check(platformInterfaces, false);
+ if (transport === 'snapshot') expect(apiFetchJSONMock).not.toHaveBeenCalled();
+ else expect(apiFetchJSONMock).toHaveBeenCalledTimes(8);
+ expect(resource.proxmox?.networkInterfaces).toEqual(platformInterfaces);
+ } finally {
+ dispose();
+ }
+ },
+ );
+
it.each(['invalid', '0002-01-01T00:00:00Z'])(
'does not turn a present unusable backup time %s into absence',
async (lastBackup) => {
diff --git a/frontend-modern/src/hooks/useWorkloads.ts b/frontend-modern/src/hooks/useWorkloads.ts
index 28a3bcfe25..84ec52bd19 100644
--- a/frontend-modern/src/hooks/useWorkloads.ts
+++ b/frontend-modern/src/hooks/useWorkloads.ts
@@ -116,6 +116,7 @@ type APIResource = {
diskStatusReason?: string;
guestAgentStatus?: string;
guestAgentExpected?: boolean;
+ networkInterfaces?: APINetworkInterface[];
lock?: string;
swapUsed?: number;
swapTotal?: number;
@@ -588,7 +589,18 @@ const mapResourceToWorkload = (resource: APIResource): WorkloadGuest | null => {
agentKind: resource.agent?.agentVersion ? 'pulse' : undefined,
agentId: resource.agent?.agentId,
agentRaid: resource.agent?.raid,
- networkInterfaces: mapNetworkInterfaces(resource.agent?.networkInterfaces),
+ // Agent reports retain precedence, including an explicitly empty list.
+ // Agentless PVE guests already supply named interfaces on their platform
+ // facet; both the REST and owning-snapshot paths must preserve them.
+ networkInterfaces: mapNetworkInterfaces(
+ resource.agent?.networkInterfaces ?? resource.proxmox?.networkInterfaces,
+ ),
+ networkInterfacesFromAgent:
+ resource.agent?.networkInterfaces != null
+ ? true
+ : resource.proxmox?.networkInterfaces != null
+ ? false
+ : undefined,
// A linked agent past its reporting lease keeps its last report on the
// resource, so its RAID, network and filesystem rows are not current.
agentStale: resource.agent?.stale === true || undefined,
diff --git a/frontend-modern/src/types/workloads.ts b/frontend-modern/src/types/workloads.ts
index c2dfff6acc..a60c650297 100644
--- a/frontend-modern/src/types/workloads.ts
+++ b/frontend-modern/src/types/workloads.ts
@@ -71,6 +71,12 @@ export type WorkloadGuest = (VM | Container) & {
* reported no guest filesystems, so the rows follow that agent's freshness.
*/
disksFromAgent?: boolean;
+ /**
+ * Producer of the selected interface list. False means Proxmox, so a
+ * silent linked agent cannot mark those platform details last known.
+ * Legacy callers without this field keep the agent freshness behaviour.
+ */
+ networkInterfacesFromAgent?: boolean;
updateStatus?: DockerContainerUpdateStatus;
// Server-evaluated capability refusals from the unified resource. The
// update button reads this to disable itself with the refusal reason