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 missing backup placement without confusing repository identity

pulse-triage[bot]0ec511193e8c
diff --git a/docs/PBS.md b/docs/PBS.md
index 5a7f9b3951..91b177875d 100644
--- a/docs/PBS.md
+++ b/docs/PBS.md
@@ -597,6 +597,9 @@ from a PBS-backed storage target. If that explanation is unavailable, keep the
origin unknown rather than inferring it from a matching guest ID or name.
A source label is not a protection, verification, restore or thaw result.
+Keep the backup repository separate from
+[guest placement and Node filters](RECOVERY.md#backup-location-and-guest-placement),
+especially when a PBS backup has no reported PVE owner or node.
**PVE/PBS inventory loading or unavailable** notices mean counts are incomplete,
not that missing backups do not exist. Existing PBS and PVE observations can
refer to the same backup; compare their owning installation, storage,
diff --git a/docs/RECOVERY.md b/docs/RECOVERY.md
index 98ca99467a..a788b57934 100644
--- a/docs/RECOVERY.md
+++ b/docs/RECOVERY.md
@@ -161,6 +161,42 @@ VMIDs alone are not sufficient to identify a duplicate or the right restore.
Direct PBS observations and PBS-through-PVE observations can differ in detail.
See [PBS data sources](PBS.md#data-source-indicator).
+### Backup location and guest placement
+
+In **Coverage** and **By date**, expand the workload or backup row before
+deciding which installation owns it. Keep these identities separate:
+
+| Evidence | Meaning and limit |
+|---|---|
+| Workload type, **Target ID**, **PVE connection** and **Node** | The guest and its reported PVE scope and placement. A VMID is unique only within its owning installation; a missing connection or node stays **Not reported**. |
+| Artifact **Source** and **Location** | The inventory reader and backup repository, including a PBS datastore or namespace. A repository name is not a guest node, and its reader is not necessarily the guest's owning PVE connection. |
+| **Provider evidence → Scope** | The collection context for that evidence, not a substitute for missing workload ownership or placement. |
+
+**Node: Not reported** does not mean that a backup failed, a guest was deleted
+or its node is offline. An unmatched PBS backup may retain its repository and
+guest type/ID without a known PVE owner. Do not infer that owner or node from
+the datastore, namespace, connection label or a repeated VMID. Older versions
+may have shown one of those hints as a Node; that label alone is not native
+placement evidence.
+
+The **Node** filter offers reported placement, not every backup location.
+If an expected row is absent under a selected node, choose **All nodes** and
+compare its **Backup location** or search for its repository instead. A
+namespace missing from the Node options is not evidence that its backups are
+missing. Clearing a display filter neither refreshes collection nor repairs
+identity or protection posture. On a phone, expand the row to read its full
+source and location rather than relying on the shortened summary.
+
+Compare existing provider records with consistent private aliases for the
+installation, guest type/ID, repository and time. Keep unknown ownership
+unknown; do not rename nodes, move backups, widen permissions or recreate a
+connection to fill the label. Keep full identifiers and private paths out of
+public reports. If node errors or agent-backed Docker readings are also mixed,
+follow the [cross-installation identity checks](TROUBLESHOOTING.md#monitoring-is-mixed-between-proxmox-installations):
+one corrected backup label does not establish recovery in those other views.
+An unresponsive guest or uncertain thaw needs the separate
+[backup safety procedure](VM_DISK_MONITORING.md#backup-safety), not a filter change.
+
### Outcomes and verification
Recorded outcomes are `success`, `warning`, `failed`, `running` or `unknown`.
diff --git a/docs/TROUBLESHOOTING.md b/docs/TROUBLESHOOTING.md
index 93cd586bed..da08657d7a 100644
--- a/docs/TROUBLESHOOTING.md
+++ b/docs/TROUBLESHOOTING.md
@@ -828,7 +828,7 @@ than undoing the repair or repeating the addition.
| Affected reading | Safe comparison | What it does not prove |
| --- | --- | --- |
| Node errors | Compare the affected node and observation time with that installation's own Proxmox view. | A similar node name or a different Pulse label does not establish which installation owns the error. |
-| Guest backup status | Compare one affected guest with the matching native Proxmox/PBS record: owning installation, guest type/VMID, datastore, namespace and backup time. Follow the [PBS evidence checks](PBS.md#backups-are-visible-but-coverage-says-unprotected). | The same VMID or a visible backup from another installation does not establish protection for this guest. |
+| Guest backup status | Compare one affected guest with the matching native Proxmox/PBS record: owning installation, guest type/VMID, datastore, namespace and backup time. Follow the [PBS evidence checks](PBS.md#backups-are-visible-but-coverage-says-unprotected) and distinguish [backup location from guest placement](RECOVERY.md#backup-location-and-guest-placement). | The same VMID or a visible backup from another installation does not establish protection for this guest. |
| Agent-backed Docker monitoring | In **Settings → Infrastructure → Agent Doctor**, inspect the affected host's existing **Last seen** and **Identity evidence**, including **Connection** and **Hostname** where available. Compare with the known Docker host, not a similar guest name. | Recent agent contact or a Healthy badge does not prove that the correct host's containers are visible or correctly attributed. Missing evidence is unknown, not proof that the agent stopped. |
While attribution is uncertain, use each installation's own Proxmox/PBS
diff --git a/frontend-modern/public/docs/PBS.md b/frontend-modern/public/docs/PBS.md
index 5a7f9b3951..91b177875d 100644
--- a/frontend-modern/public/docs/PBS.md
+++ b/frontend-modern/public/docs/PBS.md
@@ -597,6 +597,9 @@ from a PBS-backed storage target. If that explanation is unavailable, keep the
origin unknown rather than inferring it from a matching guest ID or name.
A source label is not a protection, verification, restore or thaw result.
+Keep the backup repository separate from
+[guest placement and Node filters](RECOVERY.md#backup-location-and-guest-placement),
+especially when a PBS backup has no reported PVE owner or node.
**PVE/PBS inventory loading or unavailable** notices mean counts are incomplete,
not that missing backups do not exist. Existing PBS and PVE observations can
refer to the same backup; compare their owning installation, storage,
diff --git a/frontend-modern/public/docs/RECOVERY.md b/frontend-modern/public/docs/RECOVERY.md
index 98ca99467a..a788b57934 100644
--- a/frontend-modern/public/docs/RECOVERY.md
+++ b/frontend-modern/public/docs/RECOVERY.md
@@ -161,6 +161,42 @@ VMIDs alone are not sufficient to identify a duplicate or the right restore.
Direct PBS observations and PBS-through-PVE observations can differ in detail.
See [PBS data sources](PBS.md#data-source-indicator).
+### Backup location and guest placement
+
+In **Coverage** and **By date**, expand the workload or backup row before
+deciding which installation owns it. Keep these identities separate:
+
+| Evidence | Meaning and limit |
+|---|---|
+| Workload type, **Target ID**, **PVE connection** and **Node** | The guest and its reported PVE scope and placement. A VMID is unique only within its owning installation; a missing connection or node stays **Not reported**. |
+| Artifact **Source** and **Location** | The inventory reader and backup repository, including a PBS datastore or namespace. A repository name is not a guest node, and its reader is not necessarily the guest's owning PVE connection. |
+| **Provider evidence → Scope** | The collection context for that evidence, not a substitute for missing workload ownership or placement. |
+
+**Node: Not reported** does not mean that a backup failed, a guest was deleted
+or its node is offline. An unmatched PBS backup may retain its repository and
+guest type/ID without a known PVE owner. Do not infer that owner or node from
+the datastore, namespace, connection label or a repeated VMID. Older versions
+may have shown one of those hints as a Node; that label alone is not native
+placement evidence.
+
+The **Node** filter offers reported placement, not every backup location.
+If an expected row is absent under a selected node, choose **All nodes** and
+compare its **Backup location** or search for its repository instead. A
+namespace missing from the Node options is not evidence that its backups are
+missing. Clearing a display filter neither refreshes collection nor repairs
+identity or protection posture. On a phone, expand the row to read its full
+source and location rather than relying on the shortened summary.
+
+Compare existing provider records with consistent private aliases for the
+installation, guest type/ID, repository and time. Keep unknown ownership
+unknown; do not rename nodes, move backups, widen permissions or recreate a
+connection to fill the label. Keep full identifiers and private paths out of
+public reports. If node errors or agent-backed Docker readings are also mixed,
+follow the [cross-installation identity checks](TROUBLESHOOTING.md#monitoring-is-mixed-between-proxmox-installations):
+one corrected backup label does not establish recovery in those other views.
+An unresponsive guest or uncertain thaw needs the separate
+[backup safety procedure](VM_DISK_MONITORING.md#backup-safety), not a filter change.
+
### Outcomes and verification
Recorded outcomes are `success`, `warning`, `failed`, `running` or `unknown`.
diff --git a/frontend-modern/public/docs/TROUBLESHOOTING.md b/frontend-modern/public/docs/TROUBLESHOOTING.md
index 93cd586bed..da08657d7a 100644
--- a/frontend-modern/public/docs/TROUBLESHOOTING.md
+++ b/frontend-modern/public/docs/TROUBLESHOOTING.md
@@ -828,7 +828,7 @@ than undoing the repair or repeating the addition.
| Affected reading | Safe comparison | What it does not prove |
| --- | --- | --- |
| Node errors | Compare the affected node and observation time with that installation's own Proxmox view. | A similar node name or a different Pulse label does not establish which installation owns the error. |
-| Guest backup status | Compare one affected guest with the matching native Proxmox/PBS record: owning installation, guest type/VMID, datastore, namespace and backup time. Follow the [PBS evidence checks](PBS.md#backups-are-visible-but-coverage-says-unprotected). | The same VMID or a visible backup from another installation does not establish protection for this guest. |
+| Guest backup status | Compare one affected guest with the matching native Proxmox/PBS record: owning installation, guest type/VMID, datastore, namespace and backup time. Follow the [PBS evidence checks](PBS.md#backups-are-visible-but-coverage-says-unprotected) and distinguish [backup location from guest placement](RECOVERY.md#backup-location-and-guest-placement). | The same VMID or a visible backup from another installation does not establish protection for this guest. |
| Agent-backed Docker monitoring | In **Settings → Infrastructure → Agent Doctor**, inspect the affected host's existing **Last seen** and **Identity evidence**, including **Connection** and **Hostname** where available. Compare with the known Docker host, not a similar guest name. | Recent agent contact or a Healthy badge does not prove that the correct host's containers are visible or correctly attributed. Missing evidence is unknown, not proof that the agent stopped. |
While attribution is uncertain, use each installation's own Proxmox/PBS
diff --git a/frontend-modern/src/features/docs/__tests__/backupPlacementGuide.test.ts b/frontend-modern/src/features/docs/__tests__/backupPlacementGuide.test.ts
new file mode 100644
index 0000000000..78d0c8af11
--- /dev/null
+++ b/frontend-modern/src/features/docs/__tests__/backupPlacementGuide.test.ts
@@ -0,0 +1,106 @@
+import { readFileSync } from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { describe, expect, it } from 'vitest';
+import {
+ getBackupWorkloadNodeLabel,
+ getBackupWorkloadPVEConnection,
+} from '@/features/proxmox/proxmoxBackupsTableShared';
+import { type WorkloadReference } from '@/features/proxmox/proxmoxBackupRecoveryModel';
+import { createGuideFixture } from './guideFixture';
+
+const root = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '../../../../..');
+const read = (file: string) => readFileSync(path.join(root, file), 'utf8');
+const guide = createGuideFixture((name) =>
+ readFileSync(
+ path.join(
+ process.env.PULSE_BACKUP_PLACEMENT_GUIDE_INPUT_DIRECTORY ??
+ path.join(root, 'frontend-modern/public/docs'),
+ `${name}.md`,
+ ),
+ 'utf8',
+ ),
+);
+const fragment = '#backup-location-and-guest-placement';
+const section = () => {
+ const heading = guide('RECOVERY').querySelector(fragment);
+ expect(heading?.textContent).toBe('Backup location and guest placement');
+ const result = document.createElement('section');
+ for (let next = heading!.nextElementSibling; next; next = next.nextElementSibling) {
+ if (/^H[1-3]$/.test(next.tagName)) break;
+ result.appendChild(next.cloneNode(true));
+ }
+ return result;
+};
+const prose = () => section().textContent!.replace(/\s+/g, ' ');
+
+describe('backup placement guidance', () => {
+ it('keeps discovery links and shipped copies aligned', () => {
+ for (const name of ['PBS', 'TROUBLESHOOTING']) {
+ expect(guide(name).querySelector(`a[href="/docs/RECOVERY${fragment}"]`)).not.toBeNull();
+ }
+ for (const name of ['RECOVERY', 'PBS', 'TROUBLESHOOTING']) {
+ expect(read(`docs/${name}.md`)).toBe(read(`frontend-modern/public/docs/${name}.md`));
+ }
+ });
+
+ it('distinguishes reported guest placement from repository and reader scope', () => {
+ const rows = [...section().querySelectorAll('tbody tr')];
+ expect(rows).toHaveLength(3);
+ expect(rows[0].textContent).toContain('Target ID');
+ expect(rows[0].textContent).toContain('PVE connection');
+ expect(rows[1].textContent).toContain('A repository name is not a guest node');
+ expect(rows[2].textContent).toContain('not a substitute for missing workload ownership');
+ const unmatched: WorkloadReference = {
+ key: 'pbs:private-example:vm/100',
+ type: 'vm',
+ typeLabel: 'VM',
+ vmid: '100',
+ label: 'VM 100',
+ };
+ expect(rows[0].textContent).toContain(getBackupWorkloadNodeLabel(unmatched));
+ expect(rows[0].textContent).toContain(getBackupWorkloadPVEConnection(unmatched));
+ for (const distinction of [
+ 'does not mean that a backup failed, a guest was deleted or its node is offline',
+ 'without a known PVE owner',
+ 'Do not infer that owner or node from the datastore, namespace, connection label or a repeated VMID',
+ 'that label alone is not native placement evidence',
+ ]) {
+ expect(prose()).toContain(distinction);
+ }
+ });
+
+ it('finds unmatched evidence without treating a display filter as repair', () => {
+ for (const distinction of [
+ 'Node filter offers reported placement, not every backup location',
+ 'choose All nodes',
+ 'Backup location or search for its repository',
+ 'not evidence that its backups are missing',
+ 'neither refreshes collection nor repairs identity or protection posture',
+ 'On a phone, expand the row',
+ ]) {
+ expect(prose()).toContain(distinction);
+ }
+ });
+
+ it('keeps comparison private and partial recovery distinct from original symptoms', () => {
+ for (const boundary of [
+ 'Compare existing provider records',
+ 'Keep unknown ownership unknown',
+ 'do not rename nodes, move backups, widen permissions or recreate a connection',
+ 'Keep full identifiers and private paths out of public reports',
+ 'one corrected backup label does not establish recovery in those other views',
+ 'An unresponsive guest or uncertain thaw needs the separate backup safety procedure',
+ ]) {
+ expect(prose()).toContain(boundary);
+ }
+ expect(section().querySelector('pre')).toBeNull();
+ for (const [name, target] of [
+ ['TROUBLESHOOTING', '#monitoring-is-mixed-between-proxmox-installations'],
+ ['VM_DISK_MONITORING', '#backup-safety'],
+ ]) {
+ expect(section().querySelector(`a[href="/docs/${name}${target}"]`)).not.toBeNull();
+ expect(guide(name).querySelector(target)).not.toBeNull();
+ }
+ });
+});