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.

Keep Cloud migration within configuration-transfer limits

pulse-triage[bot]4662cafef681
diff --git a/docs/CLOUD.md b/docs/CLOUD.md
index 74b0cacbc5..613e3734b1 100644
--- a/docs/CLOUD.md
+++ b/docs/CLOUD.md
@@ -75,7 +75,9 @@ Relay is enabled by default on Cloud instances. Open **Settings → Pulse Mobile
- Your monitoring data runs in an **isolated container** — no shared databases.
- Data is stored encrypted at rest.
- Backups are automated and encrypted.
-- You can **export** your configuration at any time via **Settings → System → Recovery** and migrate to self-hosted if needed.
+- **Create Backup** in **Settings → System → Recovery** downloads an encrypted
+ configuration export, not a complete copy of the hosted installation. Check
+ the [migration scope](#migrating-tofrom-cloud) before relying on it for a move.
- See [Privacy](PRIVACY.md) for full details.
## Billing
@@ -88,21 +90,89 @@ Pulse Cloud billing is handled by Stripe. You can manage your subscription from
## Migrating To/From Cloud
+**Create Backup transfers only the included configuration, not the full
+installation.** Metrics and audit history, incidents and queued notifications,
+server-side agent inventory and enrolment state, profiles and assignments are
+not included. Neither are TrueNAS, vSphere and Machine Availability connections,
+local login credentials or deployment overrides. Contents depend on the
+exporting version; see the [configuration-transfer scope](MIGRATION.md#configuration-transfer)
+for the complete account. Imported API-token records do not reveal the original
+tokens or establish that every agent is admitted.
+
+Hosted automatic backups and this downloaded export are different things. If
+you need excluded state, retain the source and establish a recoverable,
+[consistent full-state backup](MIGRATION.md#full-state-recovery) before moving.
+Do not assume access to the hosted filesystem or that a hosted backup can be
+restored into your self-hosted installation. Do not mix encrypted files and keys
+from different installations. Keep exports, passphrases and credentials private.
+
+Import can activate monitoring and notification settings. Use an isolated trial
+where available; if the hosted destination cannot be isolated, arrange a
+single-active cutover before importing and retain independent monitoring during
+the pause. Browser administrator access does not grant hosted filesystem or
+service-control access. If a necessary hosting-side operation is unavailable,
+stop before importing rather than cancel the source or run two connected copies.
+
### Self-Hosted → Cloud
-1. **Export** from your self-hosted instance: **Settings → System → Recovery → Create Backup**.
-2. **Import** into your Cloud instance: **Settings → System → Recovery → Restore Configuration**.
-3. Update agent `--url` flags to point to your cloud URL.
+1. Keep the self-hosted source intact and preserve the separate full-state
+ backup if you need its history or excluded state.
+2. Set up destination-local administrator access on Cloud. Keep the trial
+ destination isolated from monitored systems, agents and notification
+ destinations so two instances do not send duplicate alerts or remote actions.
+3. **Export** from the source through **Settings → System → Recovery → Create
+ Backup**, using a strong, unique passphrase stored separately. If Cloud
+ already has useful configuration, export it first. **Restore Configuration**
+ replaces the included settings and API-token records; it does not merge them.
+4. Re-create the excluded connections and settings you need. Retarget existing
+ agents using the [address-change procedure](UNIFIED_AGENT.md#moving-pulse-to-a-new-address),
+ not by uninstalling or re-enrolling them. It preserves the saved identity and
+ credential; use the procedure supported by that host's platform.
+5. Complete the [cutover checks](#verify-the-move-before-retiring-the-source)
+ before retiring the self-hosted source.
### Cloud → Self-Hosted
-1. **Export** from Cloud: **Settings → System → Recovery → Create Backup**.
-2. Install Pulse on your own server (see [Install Guide](INSTALL.md)).
-3. **Import** the backup.
-4. Re-activate your license key (if switching to Pro self-hosted).
-5. Update agent `--url` flags.
-
-See [Migration Guide](MIGRATION.md) for detailed steps.
+1. Keep the Cloud instance available until validation is complete; do not
+ cancel it or discard the source merely because an export succeeded. Establish
+ recovery for any excluded state you need before proceeding.
+2. Install Pulse on your own server using the [Install Guide](INSTALL.md).
+ Set up destination-local administrator access and keep the trial isolated
+ from monitored systems, agents and notification destinations.
+3. **Export** from Cloud through **Settings → System → Recovery → Create
+ Backup**. Keep its passphrase separately and privately. Export any existing
+ destination configuration first, then use **Restore Configuration** there;
+ import replaces the included settings and API-token records, not a merge.
+4. Re-create excluded connections and settings, and verify your Pro licence
+ separately if using Pro self-hosted. Retarget existing agents with the
+ [address-change procedure](UNIFIED_AGENT.md#moving-pulse-to-a-new-address),
+ preserving their identity and private credential rather than creating a
+ replacement token just for the move.
+5. Complete the checks below before retiring the Cloud source.
+
+### Verify the move before retiring the source
+
+- Verify destination-local login, imported SSO mappings and the new callback
+ address. Imported settings do not override every deployment-managed value.
+- Keep HTTPS verification enabled for both the new installer download and the
+ agent connection. An old endpoint's custom CA or certificate pin is not
+ automatically trust for the new endpoint; follow the retargeting guide.
+- Check fresh ordinary reports and agent admission at the destination, not
+ just cached rows or a successful import. Re-create profiles and assignments
+ before enabling remote actions. Missing history after configuration-only
+ transfer does not prove collection failed.
+- Check every expected platform and your existing notification delivery
+ evidence without running two instances against the same destinations. Do
+ not induce alerts, replay a queue or run a workload action merely to test the
+ move; importing settings does not transfer queued notifications.
+- If an import reports a reload/apply failure, settings may already have been
+ written. Preserve both instances and inspect the error before repeating it.
+ If validation fails, stop the trial destination before returning traffic to
+ the intact source, check agent URLs and avoid two active writers.
+
+See the [Migration Guide](MIGRATION.md#cut-over-and-verify) for the complete
+cutover and recovery procedure. A successful configuration import is not proof
+of full recovery.
## FAQ
@@ -120,7 +190,9 @@ Your data is retained for 30 days after cancellation. You can export your config
### Can I switch between Cloud and self-hosted?
-Yes. Use the export/import workflow described above. Your monitoring configuration is fully portable.
+You can transfer the included configuration using the workflow above. It is
+not a full installation copy: history, some connections and agent enrolment
+state need separate handling. Verify the destination before retiring the source.
## See Also
diff --git a/frontend-modern/public/docs/CLOUD.md b/frontend-modern/public/docs/CLOUD.md
index 74b0cacbc5..613e3734b1 100644
--- a/frontend-modern/public/docs/CLOUD.md
+++ b/frontend-modern/public/docs/CLOUD.md
@@ -75,7 +75,9 @@ Relay is enabled by default on Cloud instances. Open **Settings → Pulse Mobile
- Your monitoring data runs in an **isolated container** — no shared databases.
- Data is stored encrypted at rest.
- Backups are automated and encrypted.
-- You can **export** your configuration at any time via **Settings → System → Recovery** and migrate to self-hosted if needed.
+- **Create Backup** in **Settings → System → Recovery** downloads an encrypted
+ configuration export, not a complete copy of the hosted installation. Check
+ the [migration scope](#migrating-tofrom-cloud) before relying on it for a move.
- See [Privacy](PRIVACY.md) for full details.
## Billing
@@ -88,21 +90,89 @@ Pulse Cloud billing is handled by Stripe. You can manage your subscription from
## Migrating To/From Cloud
+**Create Backup transfers only the included configuration, not the full
+installation.** Metrics and audit history, incidents and queued notifications,
+server-side agent inventory and enrolment state, profiles and assignments are
+not included. Neither are TrueNAS, vSphere and Machine Availability connections,
+local login credentials or deployment overrides. Contents depend on the
+exporting version; see the [configuration-transfer scope](MIGRATION.md#configuration-transfer)
+for the complete account. Imported API-token records do not reveal the original
+tokens or establish that every agent is admitted.
+
+Hosted automatic backups and this downloaded export are different things. If
+you need excluded state, retain the source and establish a recoverable,
+[consistent full-state backup](MIGRATION.md#full-state-recovery) before moving.
+Do not assume access to the hosted filesystem or that a hosted backup can be
+restored into your self-hosted installation. Do not mix encrypted files and keys
+from different installations. Keep exports, passphrases and credentials private.
+
+Import can activate monitoring and notification settings. Use an isolated trial
+where available; if the hosted destination cannot be isolated, arrange a
+single-active cutover before importing and retain independent monitoring during
+the pause. Browser administrator access does not grant hosted filesystem or
+service-control access. If a necessary hosting-side operation is unavailable,
+stop before importing rather than cancel the source or run two connected copies.
+
### Self-Hosted → Cloud
-1. **Export** from your self-hosted instance: **Settings → System → Recovery → Create Backup**.
-2. **Import** into your Cloud instance: **Settings → System → Recovery → Restore Configuration**.
-3. Update agent `--url` flags to point to your cloud URL.
+1. Keep the self-hosted source intact and preserve the separate full-state
+ backup if you need its history or excluded state.
+2. Set up destination-local administrator access on Cloud. Keep the trial
+ destination isolated from monitored systems, agents and notification
+ destinations so two instances do not send duplicate alerts or remote actions.
+3. **Export** from the source through **Settings → System → Recovery → Create
+ Backup**, using a strong, unique passphrase stored separately. If Cloud
+ already has useful configuration, export it first. **Restore Configuration**
+ replaces the included settings and API-token records; it does not merge them.
+4. Re-create the excluded connections and settings you need. Retarget existing
+ agents using the [address-change procedure](UNIFIED_AGENT.md#moving-pulse-to-a-new-address),
+ not by uninstalling or re-enrolling them. It preserves the saved identity and
+ credential; use the procedure supported by that host's platform.
+5. Complete the [cutover checks](#verify-the-move-before-retiring-the-source)
+ before retiring the self-hosted source.
### Cloud → Self-Hosted
-1. **Export** from Cloud: **Settings → System → Recovery → Create Backup**.
-2. Install Pulse on your own server (see [Install Guide](INSTALL.md)).
-3. **Import** the backup.
-4. Re-activate your license key (if switching to Pro self-hosted).
-5. Update agent `--url` flags.
-
-See [Migration Guide](MIGRATION.md) for detailed steps.
+1. Keep the Cloud instance available until validation is complete; do not
+ cancel it or discard the source merely because an export succeeded. Establish
+ recovery for any excluded state you need before proceeding.
+2. Install Pulse on your own server using the [Install Guide](INSTALL.md).
+ Set up destination-local administrator access and keep the trial isolated
+ from monitored systems, agents and notification destinations.
+3. **Export** from Cloud through **Settings → System → Recovery → Create
+ Backup**. Keep its passphrase separately and privately. Export any existing
+ destination configuration first, then use **Restore Configuration** there;
+ import replaces the included settings and API-token records, not a merge.
+4. Re-create excluded connections and settings, and verify your Pro licence
+ separately if using Pro self-hosted. Retarget existing agents with the
+ [address-change procedure](UNIFIED_AGENT.md#moving-pulse-to-a-new-address),
+ preserving their identity and private credential rather than creating a
+ replacement token just for the move.
+5. Complete the checks below before retiring the Cloud source.
+
+### Verify the move before retiring the source
+
+- Verify destination-local login, imported SSO mappings and the new callback
+ address. Imported settings do not override every deployment-managed value.
+- Keep HTTPS verification enabled for both the new installer download and the
+ agent connection. An old endpoint's custom CA or certificate pin is not
+ automatically trust for the new endpoint; follow the retargeting guide.
+- Check fresh ordinary reports and agent admission at the destination, not
+ just cached rows or a successful import. Re-create profiles and assignments
+ before enabling remote actions. Missing history after configuration-only
+ transfer does not prove collection failed.
+- Check every expected platform and your existing notification delivery
+ evidence without running two instances against the same destinations. Do
+ not induce alerts, replay a queue or run a workload action merely to test the
+ move; importing settings does not transfer queued notifications.
+- If an import reports a reload/apply failure, settings may already have been
+ written. Preserve both instances and inspect the error before repeating it.
+ If validation fails, stop the trial destination before returning traffic to
+ the intact source, check agent URLs and avoid two active writers.
+
+See the [Migration Guide](MIGRATION.md#cut-over-and-verify) for the complete
+cutover and recovery procedure. A successful configuration import is not proof
+of full recovery.
## FAQ
@@ -120,7 +190,9 @@ Your data is retained for 30 days after cancellation. You can export your config
### Can I switch between Cloud and self-hosted?
-Yes. Use the export/import workflow described above. Your monitoring configuration is fully portable.
+You can transfer the included configuration using the workflow above. It is
+not a full installation copy: history, some connections and agent enrolment
+state need separate handling. Verify the destination before retiring the source.
## See Also
diff --git a/frontend-modern/src/features/docs/__tests__/cloudMigrationGuide.test.ts b/frontend-modern/src/features/docs/__tests__/cloudMigrationGuide.test.ts
new file mode 100644
index 0000000000..713b29edbb
--- /dev/null
+++ b/frontend-modern/src/features/docs/__tests__/cloudMigrationGuide.test.ts
@@ -0,0 +1,61 @@
+import { readFileSync } from 'node:fs';
+import { resolve } from 'node:path';
+import { describe, expect, it } from 'vitest';
+import { renderDocMarkdown } from '../docMarkdown';
+
+const read = (file: string) => readFileSync(resolve(process.cwd(), '..', file), 'utf8');
+const article = (name: string) => {
+ const element = document.createElement('article');
+ element.innerHTML = renderDocMarkdown(read(`docs/${name}.md`), name);
+ return element;
+};
+const text = (element: Element) => element.textContent?.replace(/\s+/g, ' ') ?? '';
+
+describe('Cloud configuration-transfer help', () => {
+ it('ships the same scope warning before either migration direction', () => {
+ expect(read('frontend-modern/public/docs/CLOUD.md')).toBe(read('docs/CLOUD.md'));
+ const guide = article('CLOUD');
+ const migration = guide.querySelector('#migrating-tofrom-cloud');
+ const warning = migration?.nextElementSibling;
+ expect(warning?.querySelector('strong')).not.toBeNull();
+ expect(text(warning!)).toContain('not the full installation');
+ expect(text(warning!)).toContain('agent inventory and enrolment state');
+ expect(text(warning!)).toContain('TrueNAS, vSphere and Machine Availability');
+ expect(text(guide)).not.toContain('fully portable');
+ });
+
+ it('keeps both ordered moves and their single-active, identity and recovery checks readable', () => {
+ const guide = article('CLOUD');
+ for (const name of ['Self-Hosted → Cloud', 'Cloud → Self-Hosted']) {
+ const heading = [...guide.querySelectorAll('h3')].find((node) => text(node) === name);
+ expect(heading?.nextElementSibling?.tagName).toBe('OL');
+ expect(heading?.nextElementSibling?.querySelectorAll('li')).toHaveLength(5);
+ expect(text(heading!.nextElementSibling!)).toContain('destination-local administrator access');
+ expect(text(heading!.nextElementSibling!)).toContain('API-token records');
+ }
+ expect(text(guide)).toContain('single-active cutover before importing');
+ expect(text(guide)).toContain('stop before importing');
+ expect(text(guide)).toContain('rather than creating a replacement token');
+ expect(text(guide)).toContain('settings may already have been written');
+ expect(text(guide)).toContain('Do not induce alerts, replay a queue or run a workload action');
+ expect(text(guide)).toContain('not proof of full recovery');
+ expect(guide.querySelector('pre')).toBeNull();
+ });
+
+ it('routes every migration/retarget link to an existing guide and fragment', () => {
+ const guide = article('CLOUD');
+ for (const [name, fragment] of [
+ ['MIGRATION', 'configuration-transfer'],
+ ['MIGRATION', 'full-state-recovery'],
+ ['MIGRATION', 'cut-over-and-verify'],
+ ['UNIFIED_AGENT', 'moving-pulse-to-a-new-address'],
+ ]) {
+ const link = guide.querySelector(`a[href="/docs/${name}#${fragment}"]`);
+ expect(link).not.toBeNull();
+ expect(link?.hasAttribute('data-doc-link')).toBe(true);
+ expect(article(name).querySelector(`[id="${fragment}"]`)).not.toBeNull();
+ }
+ expect(guide.querySelector('a[href="#verify-the-move-before-retiring-the-source"]')).not.toBeNull();
+ expect(guide.querySelector('#verify-the-move-before-retiring-the-source')).not.toBeNull();
+ });
+});
diff --git a/scripts/tests/test_cloud_migration_docs.py b/scripts/tests/test_cloud_migration_docs.py
new file mode 100644
index 0000000000..6c54719541
--- /dev/null
+++ b/scripts/tests/test_cloud_migration_docs.py
@@ -0,0 +1,84 @@
+#!/usr/bin/env python3
+"""Keep the hosted migration entry point within the actual export/agent scope.
+
+These check instructions, not installed Cloud recovery or provider access.
+The real encrypted-archive control is TestConfigurationMigrationArchiveScope.
+"""
+
+from pathlib import Path
+import unittest
+
+
+ROOT = Path(__file__).resolve().parents[2]
+
+
+def guide():
+ return (ROOT / "docs/CLOUD.md").read_text(encoding="utf-8")
+
+
+def section(text, heading, level):
+ return " ".join(text.split(f"{level} {heading}\n", 1)[1].split(f"\n{level} ", 1)[0].split())
+
+
+class CloudMigrationDocsTest(unittest.TestCase):
+ def test_in_app_guide_matches_canonical(self):
+ self.assertEqual(guide(), (ROOT / "frontend-modern/public/docs/CLOUD.md").read_text())
+
+ def test_export_scope_is_not_a_portable_installation_promise(self):
+ text = section(guide(), "Migrating To/From Cloud", "##")
+ for boundary in (
+ "not the full installation", "Metrics and audit history",
+ "incidents and queued notifications", "agent inventory and enrolment state",
+ "profiles and assignments", "TrueNAS, vSphere and Machine Availability",
+ "local login credentials or deployment overrides", "exporting version",
+ "MIGRATION.md#configuration-transfer", "do not reveal the original tokens",
+ "Hosted automatic backups and this downloaded export are different things",
+ "Do not assume access to the hosted filesystem", "MIGRATION.md#full-state-recovery",
+ "Do not mix encrypted files and keys", "Keep exports, passphrases and credentials private",
+ ):
+ with self.subTest(boundary=boundary):
+ self.assertIn(boundary, text)
+ self.assertNotIn("fully portable", guide())
+ self.assertIn("not a complete copy of the hosted installation",
+ section(guide(), "Data & Privacy", "##"))
+
+ def test_both_directions_preserve_access_source_and_destination(self):
+ for heading in ("Self-Hosted → Cloud", "Cloud → Self-Hosted"):
+ text = section(guide(), heading, "###")
+ with self.subTest(direction=heading):
+ for boundary in ("destination-local administrator access", "notification destinations",
+ "API-token records", "not", "merge", "passphrase", "export",
+ "excluded connections and settings", "before retiring"):
+ self.assertIn(boundary, text)
+ hosted_exit = section(guide(), "Cloud → Self-Hosted", "###")
+ self.assertIn("do not cancel it or discard the source", hosted_exit)
+ self.assertIn("verify your Pro licence separately", hosted_exit)
+
+ def test_retargeting_preserves_identity_and_does_not_inherit_endpoint_trust(self):
+ text = section(guide(), "Migrating To/From Cloud", "##")
+ self.assertEqual(text.count("UNIFIED_AGENT.md#moving-pulse-to-a-new-address"), 2)
+ for boundary in ("saved identity and credential", "host's platform",
+ "rather than creating a replacement token", "HTTPS verification enabled",
+ "installer download", "agent connection", "certificate pin",
+ "not automatically trust for the new endpoint", "fresh ordinary reports",
+ "agent admission", "before enabling remote actions"):
+ with self.subTest(boundary=boundary):
+ self.assertIn(boundary, text)
+ self.assertNotIn("Update agent `--url` flags", text)
+ self.assertNotIn("```", text, "No generic credential, reinstall or hosted-filesystem recipe")
+
+ def test_import_errors_and_cutover_do_not_trigger_destructive_diagnostics(self):
+ text = section(guide(), "Migrating To/From Cloud", "##")
+ for boundary in ("Import can activate monitoring", "single-active cutover before importing",
+ "retain independent monitoring", "does not grant hosted filesystem",
+ "stop before importing", "reload/apply failure",
+ "settings may already have been written", "before repeating it",
+ "stop the trial destination", "intact source", "avoid two active writers",
+ "Do not induce alerts, replay a queue or run a workload action",
+ "not proof of full recovery", "Missing history", "does not prove collection failed"):
+ with self.subTest(boundary=boundary):
+ self.assertIn(boundary, text)
+
+
+if __name__ == "__main__":
+ unittest.main()