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.
Go aialertsdashboarddockerdocker-monitoringgohomelabinfrastructure-monitoringkubernetesmonitoringmspproxmoxproxmox-backup-serverproxmox-mail-gatewayproxmox-veself-hostedtruenastypescriptvspherewebhooks
Explain read-only checks for uncertain workload updates
pulse-triage[bot]837d193960f4
diff --git a/docs/DOCKER.md b/docs/DOCKER.mdindex e35f9f2cf1..a08442f8c2 100644--- a/docs/DOCKER.md+++ b/docs/DOCKER.md@@ -293,6 +293,52 @@ or volumes to clear a warning. Recover through the application's and deploymentmanager's procedures using a verified matching data backup where required;returning to the old image alone does not undo a data migration.+### Check a failed or pending workload update++A failed banner or missing receipt does not tell you whether the update ran.+Use your normal Docker administration shell **on the host running the affected+container**, not a shell inside Pulse or on an unrelated Proxmox host. Use the+same Docker context as that workload; do not change socket permissions or enable+agent commands just to inspect it.++List container names, including stopped containers, without dumping their+configuration:++```bash+docker ps -a --format '{{.Names}}'+```++Replace `affected-container` with the original workload name (not `pulse` unless+Pulse itself was the target), then read only its state and image identity:++```bash+container='affected-container'+docker inspect --type container --format 'State={{.State.Status}} ImageRef={{.Config.Image}} ImageID={{.Image}} Started={{.State.StartedAt}}' "$container"+```++`State` says whether the container is running, stopped or restarting. `ImageRef`+is its configured image reference; a tag such as `latest` can stay unchanged+after an update. `ImageID` identifies the actual local image used by this+container: compare it with your privately recorded pre-update image or the+intended image in your deployment manager. It is not a registry manifest digest,+so do not compare it directly with Pulse's latest-registry digest. `Started` is+only a start time, not proof of an image update or application readiness. If the+old identity was not recorded, these readings alone cannot establish whether+the image changed.++If inspection fails or the original name is missing, retain that error and the+name listing locally; the workload may have been renamed during the attempt.+Do not start, rename, delete or update anything to make the check succeed.+Check the application's ordinary UI or health endpoint separately; a running+container is not proof that its application or data is healthy.++In Pulse, reopen that container's **Review action** and use **Check for receipt**+when available. This re-reads the existing action; it does not send another+container update. If the receipt is still missing, leave the update alone until+the actual workload state and recovery path are reconciled. For help, share only+the relevant state, receipt status and a redacted error, not the full inspection,+other container names, environments or registry credentials.+### Requirements- **Unified agent** running on the Docker host with Docker monitoring enableddiff --git a/frontend-modern/public/docs/DOCKER.md b/frontend-modern/public/docs/DOCKER.mdindex e35f9f2cf1..a08442f8c2 100644--- a/frontend-modern/public/docs/DOCKER.md+++ b/frontend-modern/public/docs/DOCKER.md@@ -293,6 +293,52 @@ or volumes to clear a warning. Recover through the application's and deploymentmanager's procedures using a verified matching data backup where required;returning to the old image alone does not undo a data migration.+### Check a failed or pending workload update++A failed banner or missing receipt does not tell you whether the update ran.+Use your normal Docker administration shell **on the host running the affected+container**, not a shell inside Pulse or on an unrelated Proxmox host. Use the+same Docker context as that workload; do not change socket permissions or enable+agent commands just to inspect it.++List container names, including stopped containers, without dumping their+configuration:++```bash+docker ps -a --format '{{.Names}}'+```++Replace `affected-container` with the original workload name (not `pulse` unless+Pulse itself was the target), then read only its state and image identity:++```bash+container='affected-container'+docker inspect --type container --format 'State={{.State.Status}} ImageRef={{.Config.Image}} ImageID={{.Image}} Started={{.State.StartedAt}}' "$container"+```++`State` says whether the container is running, stopped or restarting. `ImageRef`+is its configured image reference; a tag such as `latest` can stay unchanged+after an update. `ImageID` identifies the actual local image used by this+container: compare it with your privately recorded pre-update image or the+intended image in your deployment manager. It is not a registry manifest digest,+so do not compare it directly with Pulse's latest-registry digest. `Started` is+only a start time, not proof of an image update or application readiness. If the+old identity was not recorded, these readings alone cannot establish whether+the image changed.++If inspection fails or the original name is missing, retain that error and the+name listing locally; the workload may have been renamed during the attempt.+Do not start, rename, delete or update anything to make the check succeed.+Check the application's ordinary UI or health endpoint separately; a running+container is not proof that its application or data is healthy.++In Pulse, reopen that container's **Review action** and use **Check for receipt**+when available. This re-reads the existing action; it does not send another+container update. If the receipt is still missing, leave the update alone until+the actual workload state and recovery path are reconciled. For help, share only+the relevant state, receipt status and a redacted error, not the full inspection,+other container names, environments or registry credentials.+### Requirements- **Unified agent** running on the Docker host with Docker monitoring enableddiff --git a/scripts/tests/test_update_recovery_docs.py b/scripts/tests/test_update_recovery_docs.pyindex 0e1df0c8d1..c7660bd559 100644--- a/scripts/tests/test_update_recovery_docs.py+++ b/scripts/tests/test_update_recovery_docs.py@@ -40,7 +40,17 @@ if name == 'systemctl':assert args == ['show', 'pulse', '--property=FragmentPath', '--property=DropInPaths']print('FragmentPath=/etc/systemd/system/pulse.service\nDropInPaths=/etc/systemd/system/pulse.service.d/local.conf')elif name == 'docker':- if args == ['inspect', 'pulse', '--format', '{{.Config.Image}} {{.Image}}']:+ if args == ['ps', '-a', '--format', '{{.Names}}']:+ print('example-app\nexample-app_pulse_backup_123')+ elif args == ['inspect', '--type', 'container', '--format',+ 'State={{.State.Status}} ImageRef={{.Config.Image}} ImageID={{.Image}} Started={{.State.StartedAt}}',+ 'example-app']:+ if os.environ.get('INSPECT_EXIT'):+ print('No such container: example-app', file=sys.stderr)+ sys.exit(int(os.environ['INSPECT_EXIT']))+ print('State=' + os.environ['CONTAINER_STATE'] ++ ' ImageRef=private.example/app:latest ImageID=sha256:current Started=2026-10-06T12:00:00Z')+ elif args == ['inspect', 'pulse', '--format', '{{.Config.Image}} {{.Image}}']:print('private.example/pulse:old sha256:previous')elif args == ['compose', 'pull', 'pulse']:sys.exit(int(os.environ.get('PULL_EXIT', '0')))@@ -64,6 +74,7 @@ class UpdateRecoveryDocsTest(unittest.TestCase):calls_path = root / "calls.jsonl"env = dict(os.environ, PATH=f"{root}:{os.environ['PATH']}",CALLS=str(calls_path), SERVICE_STATE="active",+ CONTAINER_STATE="running",SYNTHETIC_CREDENTIAL="never-print-this-private-value")env.update(settings)result = subprocess.run(["bash", "-c", recipe], env=env,@@ -186,6 +197,54 @@ class UpdateRecoveryDocsTest(unittest.TestCase):self.assertIn("DOCKER.md#-updates", short)self.assertNotIn("docker pull", short)+ def workload_check_recipes(self):+ return re.findall(r"```bash\n(.*?)```", section(+ "DOCKER", "Check a failed or pending workload update", "###"), re.S)++ def test_workload_discovery_and_inspection_are_scoped_read_only(self):+ recipes = self.workload_check_recipes()+ self.assertEqual(len(recipes), 2)+ result, calls = self.exercise(recipes[0])+ self.assertEqual(result.returncode, 0, result.stderr)+ self.assertEqual(calls, [{"name": "docker", "args": ["ps", "-a", "--format", "{{.Names}}"]}])+ self.assertIn("example-app_pulse_backup_123", result.stdout)+ recipe = recipes[1].replace("container='affected-container'", "container='example-app'")+ for state in ("running", "exited", "restarting"):+ with self.subTest(state=state):+ result, calls = self.exercise(recipe, CONTAINER_STATE=state)+ self.assertEqual(result.returncode, 0, result.stderr)+ self.assertEqual(calls, [{"name": "docker", "args": [+ "inspect", "--type", "container", "--format",+ "State={{.State.Status}} ImageRef={{.Config.Image}} ImageID={{.Image}} Started={{.State.StartedAt}}",+ "example-app",+ ]}])+ self.assertIn(f"State={state}", result.stdout)+ self.assertIn("ImageID=sha256:current", result.stdout)+ self.assertNotIn("Environment", result.stdout)++ def test_missing_workload_preserves_the_error_without_recovery_mutation(self):+ recipe = self.workload_check_recipes()[1].replace(+ "container='affected-container'", "container='example-app'")+ result, calls = self.exercise(recipe, INSPECT_EXIT="1")+ self.assertEqual(result.returncode, 1)+ self.assertEqual(len(calls), 1)+ self.assertIn("No such container", result.stderr)++ def test_workload_identity_and_pending_receipt_help_preserve_uncertainty(self):+ text = " ".join(section("DOCKER", "Check a failed or pending workload update", "###").split())+ for phrase in ("on the host running the affected container", "same Docker context",+ "do not change socket permissions", "not `pulse` unless Pulse itself was the target",+ "tag such as `latest` can stay unchanged", "not a registry manifest digest",+ "cannot establish whether the image changed", "not proof of an image update",+ "Do not start, rename, delete or update anything", "not proof that its application or data is healthy",+ "does not send another container update", "not the full inspection"):+ self.assertIn(phrase, text)+ ui = (ROOT / "frontend-modern/src/features/actions/ActionReviewDialog.tsx").read_text()+ badge = (ROOT / "frontend-modern/src/components/shared/containerUpdateBadgeModel.ts").read_text()+ self.assertIn("Review action", badge)+ self.assertIn("Check for receipt", ui)+ self.assertIn("refreshReceipt()", ui)+if __name__ == "__main__":unittest.main()