From 0db135d7ccbc05e6dca81acfd323907c5cdaed92 Mon Sep 17 00:00:00 2001 From: "pulse-triage[bot]" <249995291+pulse-triage[bot]@users.noreply.github.com> Date: Tue, 6 Oct 2026 00:49:01 +0100 Subject: [PATCH] Keep missing guest disk guidance out of unsafe setup assumptions Explain that the shared Proxmox unavailable status is not an installation diagnosis. Keep setup behind backup recovery and supported guest-OS checks in the existing shipped guide; pin the rendered safety/setup fragments and preserve every covered filesystem and prior-active restoration requirements. Contract-Neutral: Clarifies existing collection limits and backup-safe setup without changing collection, runtime UI, actions or permissions. Change-source: pulse-maintainer --- docs/VM_DISK_MONITORING.md | 23 ++++++++++++ .../public/docs/VM_DISK_MONITORING.md | 23 ++++++++++++ .../utils/__tests__/backupSafetyHelp.test.ts | 36 +++++++++++++++++++ 3 files changed, 82 insertions(+) diff --git a/docs/VM_DISK_MONITORING.md b/docs/VM_DISK_MONITORING.md index 14ba35ea07..f331ccba0c 100644 --- a/docs/VM_DISK_MONITORING.md +++ b/docs/VM_DISK_MONITORING.md @@ -146,6 +146,29 @@ custom monitoring role if the required read privileges are absent. ## 🔧 Troubleshooting +### A missing reading is not an installation diagnosis + +Pulse's **“agent not running”** disk explanation means Proxmox could not query +the guest agent. It can also cover a general guest-agent HTTP 500 response; it +does not establish whether an agent is absent or stopped. An unknown explanation +establishes neither. **Do not install, enable or restart an agent solely to clear +a disk dash.** + +Read [Backup safety](#backup-safety) before changing anything. During a backup, +freeze/thaw or an unresponsive-guest incident, defer setup and live probes and +use the guest/platform's established recovery procedure. A running VM, an absent +lock or an OK backup does not prove thaw. Keep the monitoring-outage precaution +until independent checks confirm thaw, fresh successful writes to **every +filesystem covered by the backup** and workload liveness. Restore only services +and timers that were previously active. + +When the guest is responsive and outside those conditions, review its existing +agent configuration and guest-local service through your normal console. Use +[Setup](#-setup) only if it actually needs configuration and the guest OS has a +supported QEMU Guest Agent. The Linux package name is not a Windows or Android +installation instruction. If no supported agent is available, use the guest's +own filesystem tools; missing Pulse usage is unknown, not zero. + | Observation | Useful next check | | --- | --- | | **Disk shows “-”** | Read its explanation and observation time. Check the owning host, current VM options, guest-local service and configured API token access. | diff --git a/frontend-modern/public/docs/VM_DISK_MONITORING.md b/frontend-modern/public/docs/VM_DISK_MONITORING.md index 14ba35ea07..f331ccba0c 100644 --- a/frontend-modern/public/docs/VM_DISK_MONITORING.md +++ b/frontend-modern/public/docs/VM_DISK_MONITORING.md @@ -146,6 +146,29 @@ custom monitoring role if the required read privileges are absent. ## 🔧 Troubleshooting +### A missing reading is not an installation diagnosis + +Pulse's **“agent not running”** disk explanation means Proxmox could not query +the guest agent. It can also cover a general guest-agent HTTP 500 response; it +does not establish whether an agent is absent or stopped. An unknown explanation +establishes neither. **Do not install, enable or restart an agent solely to clear +a disk dash.** + +Read [Backup safety](#backup-safety) before changing anything. During a backup, +freeze/thaw or an unresponsive-guest incident, defer setup and live probes and +use the guest/platform's established recovery procedure. A running VM, an absent +lock or an OK backup does not prove thaw. Keep the monitoring-outage precaution +until independent checks confirm thaw, fresh successful writes to **every +filesystem covered by the backup** and workload liveness. Restore only services +and timers that were previously active. + +When the guest is responsive and outside those conditions, review its existing +agent configuration and guest-local service through your normal console. Use +[Setup](#-setup) only if it actually needs configuration and the guest OS has a +supported QEMU Guest Agent. The Linux package name is not a Windows or Android +installation instruction. If no supported agent is available, use the guest's +own filesystem tools; missing Pulse usage is unknown, not zero. + | Observation | Useful next check | | --- | --- | | **Disk shows “-”** | Read its explanation and observation time. Check the owning host, current VM options, guest-local service and configured API token access. | diff --git a/frontend-modern/src/utils/__tests__/backupSafetyHelp.test.ts b/frontend-modern/src/utils/__tests__/backupSafetyHelp.test.ts index fa22a89310..4f31933bb1 100644 --- a/frontend-modern/src/utils/__tests__/backupSafetyHelp.test.ts +++ b/frontend-modern/src/utils/__tests__/backupSafetyHelp.test.ts @@ -19,6 +19,42 @@ function render(markdown: string, name: string): HTMLElement { } describe('manual backup safety help', () => { + it('makes missing-reading guidance observational, OS-specific and safe before setup', () => { + const rendered = render(guide, 'VM_DISK_MONITORING'); + const troubleshooting = rendered.querySelector( + '#a-missing-reading-is-not-an-installation-diagnosis', + ); + expect(troubleshooting?.textContent).toBe('A missing reading is not an installation diagnosis'); + const explanation = guide + .split('### A missing reading is not an installation diagnosis')[1] + .split('| Observation |')[0]; + const text = render(explanation, 'VM_DISK_MONITORING').textContent?.replace(/\s+/g, ' '); + expect(text).toContain('does not establish whether an agent is absent or stopped'); + expect(text).toContain( + 'Do not install, enable or restart an agent solely to clear a disk dash', + ); + expect(text).toContain('defer setup and live probes'); + expect(text).toContain('every filesystem covered by the backup'); + expect(text).toContain('workload liveness'); + expect(text).toContain('Restore only services and timers that were previously active'); + expect(text).toContain('not a Windows or Android installation instruction'); + expect(text).toContain('missing Pulse usage is unknown, not zero'); + expect(render(explanation, 'VM_DISK_MONITORING').querySelector('pre')).toBeNull(); + for (const fragment of ['backup-safety', '-setup']) { + const link = render(explanation, 'VM_DISK_MONITORING').querySelector( + `a[href="#${fragment}"]`, + ); + expect(link).not.toBeNull(); + expect(rendered.querySelector(`#${fragment}`)).not.toBeNull(); + } + // This broad status comes from the current collector, not a reproduced + // native failure or a new diagnosis of the guest's service state. + const classifier = read('internal/monitoring/guest_disk_stability.go'); + expect(classifier).toMatch( + /case strings.Contains\(errStr, "500"\):\s+return "agent-not-running"/, + ); + }); + it('ships the complete precaution and makes it reachable from troubleshooting', () => { expect(read('frontend-modern/public/docs/VM_DISK_MONITORING.md')).toBe(guide); const troubleshooting = read('docs/TROUBLESHOOTING.md');