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 successful PVE tests alongside rejected cluster polling

pulse-triage[bot]47783a410772
diff --git a/docs/TROUBLESHOOTING.md b/docs/TROUBLESHOOTING.md
index cdc2179be5..8610f2adf7 100644
--- a/docs/TROUBLESHOOTING.md
+++ b/docs/TROUBLESHOOTING.md
@@ -320,6 +320,22 @@ the affected node and existing failure reason. If **Unreachable — details**
is available, open it with touch or keyboard rather than relying on a hover.
A display-name edit does not reconcile certificate trust.
+#### Test Connection succeeds but cluster polling fails
+
+For a PVE cluster, **Test Connection** checks the primary endpoint with the
+selected TLS settings, not the saved per-member trust used by background
+polling. Changing or clearing the primary **SSL Fingerprint** does not by
+itself replace saved member pins, even for that same endpoint. A successful
+Test therefore does not establish that ordinary polling has recovered, or
+that every member now uses CA validation.
+
+Keep the successful Test result and the failing members' existing errors as
+separate evidence. If an independently verified primary-pin correction leaves
+polling unchanged, do not keep clearing pins, copy that pin to peers or restart
+Pulse to try to make the results agree. Preserve verification and saved trust;
+an API connection's TLS result also does not establish whether a Pulse agent
+is reporting successfully.
+
If the affected member pin or conflicting entry cannot be safely reconciled
through the existing controls, leave it intact and use [Getting Help](#-getting-help).
Share only the running Pulse version, PVE/PBS version, original time, redacted
diff --git a/frontend-modern/public/docs/TROUBLESHOOTING.md b/frontend-modern/public/docs/TROUBLESHOOTING.md
index cdc2179be5..8610f2adf7 100644
--- a/frontend-modern/public/docs/TROUBLESHOOTING.md
+++ b/frontend-modern/public/docs/TROUBLESHOOTING.md
@@ -320,6 +320,22 @@ the affected node and existing failure reason. If **Unreachable — details**
is available, open it with touch or keyboard rather than relying on a hover.
A display-name edit does not reconcile certificate trust.
+#### Test Connection succeeds but cluster polling fails
+
+For a PVE cluster, **Test Connection** checks the primary endpoint with the
+selected TLS settings, not the saved per-member trust used by background
+polling. Changing or clearing the primary **SSL Fingerprint** does not by
+itself replace saved member pins, even for that same endpoint. A successful
+Test therefore does not establish that ordinary polling has recovered, or
+that every member now uses CA validation.
+
+Keep the successful Test result and the failing members' existing errors as
+separate evidence. If an independently verified primary-pin correction leaves
+polling unchanged, do not keep clearing pins, copy that pin to peers or restart
+Pulse to try to make the results agree. Preserve verification and saved trust;
+an API connection's TLS result also does not establish whether a Pulse agent
+is reporting successfully.
+
If the affected member pin or conflicting entry cannot be safely reconciled
through the existing controls, leave it intact and use [Getting Help](#-getting-help).
Share only the running Pulse version, PVE/PBS version, original time, redacted
diff --git a/frontend-modern/src/features/docs/__tests__/proxmoxTlsGuide.test.ts b/frontend-modern/src/features/docs/__tests__/proxmoxTlsGuide.test.ts
new file mode 100644
index 0000000000..8c96e81c32
--- /dev/null
+++ b/frontend-modern/src/features/docs/__tests__/proxmoxTlsGuide.test.ts
@@ -0,0 +1,83 @@
+import { readFileSync } from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { describe, expect, it } from 'vitest';
+import { renderDocMarkdown, stripLeadingTitle } from '../docMarkdown';
+
+const repoRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '../../../../..');
+const source = readFileSync(path.join(repoRoot, 'docs/TROUBLESHOOTING.md'), 'utf8');
+const shipped = readFileSync(
+ path.join(repoRoot, 'frontend-modern/public/docs/TROUBLESHOOTING.md'),
+ 'utf8',
+);
+
+function testScopeSection(): { article: HTMLElement; section: HTMLElement } {
+ const article = document.createElement('article');
+ article.innerHTML = renderDocMarkdown(stripLeadingTitle(shipped), 'TROUBLESHOOTING');
+ const heading = article.querySelector('#test-connection-succeeds-but-cluster-polling-fails');
+ expect(heading?.tagName).toBe('H4');
+ const section = document.createElement('section');
+ for (let next = heading!.nextElementSibling; next; next = next.nextElementSibling) {
+ if (/^H[1-4]$/.test(next.tagName)) break;
+ section.appendChild(next.cloneNode(true));
+ }
+ return { article, section };
+}
+
+const prose = (element: HTMLElement): string =>
+ (element.textContent ?? '').replace(/\s+/g, ' ').trim();
+
+describe('Proxmox TLS troubleshooting guide', () => {
+ it('distinguishes the primary connection test from saved-member polling and agent reports', () => {
+ const { section } = testScopeSection();
+ const text = prose(section);
+ expect(text).toContain(
+ 'Test Connection checks the primary endpoint with the selected TLS settings',
+ );
+ expect(text).toContain('not the saved per-member trust used by background polling');
+ expect(text).toContain(
+ 'Changing or clearing the primary SSL Fingerprint does not by itself replace saved member pins, even for that same endpoint',
+ );
+ expect(text).toContain(
+ 'does not establish that ordinary polling has recovered, or that every member now uses CA validation',
+ );
+ expect(text).toContain(
+ "an API connection's TLS result also does not establish whether a Pulse agent is reporting successfully",
+ );
+ });
+
+ it('offers a safe help route instead of repeated trust edits or recovery experiments', () => {
+ const { article, section } = testScopeSection();
+ const text = prose(section);
+ expect(text).toContain("the failing members' existing errors as separate evidence");
+ expect(text).toContain('independently verified primary-pin correction');
+ expect(text).toContain('do not keep clearing pins, copy that pin to peers or restart Pulse');
+ expect(text).toContain('Preserve verification and saved trust');
+ expect(text).toContain('leave it intact and use Getting Help');
+ expect(text).toContain(
+ 'keep literal endpoints, fingerprints, credentials and full configuration private',
+ );
+ expect(text).toContain('Do not edit encrypted files, run Diagnostics, force rediscovery');
+ expect(section.querySelector('pre, code')).toBeNull();
+ const help = section.querySelector('a[href="#-getting-help"]');
+ expect(help?.hasAttribute('data-doc-link')).toBe(true);
+ expect(article.querySelector('#-getting-help')?.tagName).toBe('H2');
+ expect(
+ section.querySelector('a[href="/docs/VM_DISK_MONITORING#backup-safety"]'),
+ ).not.toBeNull();
+ });
+
+ it('ships the same explanation without displacing the existing trust and renewal guidance', () => {
+ expect(shipped).toBe(source);
+ const { article } = testScopeSection();
+ for (const id of [
+ 'proxmox-or-pbs-certificate-validation-failed',
+ 'certificate-renewal-and-saved-fingerprints',
+ 'cluster-members-and-conflicting-saved-trust',
+ ]) {
+ expect(article.querySelector(`[id="${id}"]`), id).not.toBeNull();
+ }
+ expect(prose(article)).toContain('Keep certificate verification enabled.');
+ expect(prose(article)).toContain("do not copy the primary's fingerprint to all members");
+ });
+});