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 cached Docker update evidence before repeating an action
pulse-triage[bot]4c40f0f0e951
diff --git a/docs/DOCKER.md b/docs/DOCKER.mdindex 245b0df58f..35f84e707b 100644--- a/docs/DOCKER.md+++ b/docs/DOCKER.md@@ -341,10 +341,43 @@ execution disabled when you only need monitoring.### How It Works-1. **Update Detection**: Pulse compares the local image digest with the latest digest from the container registry+1. **Update Detection**: The agent compares the running image's registry digests with a registry tag lookup for the host's platform; that lookup can be cached2. **Visual Indicator**: Containers with available updates show a blue upward arrow icon3. **Reviewed Update**: Review the target and approve the action, then verify the application yourself+### Reading an update indicator++An update arrow is an image comparison, not an installation result or an+application health check. Digests identify content; a difference alone does+not establish which image is newer.++**A recent check need not be a fresh registry lookup.** Successful registry+lookups are cached for up to six hours. A container's checked timestamp can+advance when the agent compares its current local image with a cached result.+The host's **Last checked** is the newest container-check time, not proof that+every container was checked. Reloading the page does not refresh the agent's+registry cache. A missing result or a check error is unknown, not evidence+that the image is up to date.++Keep three different identities separate:++- A tag such as `latest` is a mutable name. The same tag text can refer to+ different images before and after an update.+- The container's local **ImageID** identifies the image it actually uses,+ not a registry manifest. Do not compare it directly with `latestDigest`.+- A multi-platform tag's top-level index and its platform-specific manifest+ have different digests. Compare the same repository, tag, platform and+ manifest layer; different digest types do not by themselves prove an update.++**If an update indicator returns after recreation, do not repeat the update+just to clear it.** Reconcile the existing action receipt, your deployment+manager's recorded running image and the application's ordinary health first.+Use the [read-only workload state checks](#action-was-sent-or-its-outcome-is-unknown)+when an action's outcome is uncertain; they do not pull or recreate anything.+Do not restart or reinstall the agent, broaden a token, disable TLS verification+or delete images or volumes to test the indicator. Keep full inspections,+environments and registry credentials private.+### Updating a Container1. Open **Docker → Overview** (`/docker/overview`) and find the host and containerdiff --git a/frontend-modern/public/docs/DOCKER.md b/frontend-modern/public/docs/DOCKER.mdindex 245b0df58f..35f84e707b 100644--- a/frontend-modern/public/docs/DOCKER.md+++ b/frontend-modern/public/docs/DOCKER.md@@ -341,10 +341,43 @@ execution disabled when you only need monitoring.### How It Works-1. **Update Detection**: Pulse compares the local image digest with the latest digest from the container registry+1. **Update Detection**: The agent compares the running image's registry digests with a registry tag lookup for the host's platform; that lookup can be cached2. **Visual Indicator**: Containers with available updates show a blue upward arrow icon3. **Reviewed Update**: Review the target and approve the action, then verify the application yourself+### Reading an update indicator++An update arrow is an image comparison, not an installation result or an+application health check. Digests identify content; a difference alone does+not establish which image is newer.++**A recent check need not be a fresh registry lookup.** Successful registry+lookups are cached for up to six hours. A container's checked timestamp can+advance when the agent compares its current local image with a cached result.+The host's **Last checked** is the newest container-check time, not proof that+every container was checked. Reloading the page does not refresh the agent's+registry cache. A missing result or a check error is unknown, not evidence+that the image is up to date.++Keep three different identities separate:++- A tag such as `latest` is a mutable name. The same tag text can refer to+ different images before and after an update.+- The container's local **ImageID** identifies the image it actually uses,+ not a registry manifest. Do not compare it directly with `latestDigest`.+- A multi-platform tag's top-level index and its platform-specific manifest+ have different digests. Compare the same repository, tag, platform and+ manifest layer; different digest types do not by themselves prove an update.++**If an update indicator returns after recreation, do not repeat the update+just to clear it.** Reconcile the existing action receipt, your deployment+manager's recorded running image and the application's ordinary health first.+Use the [read-only workload state checks](#action-was-sent-or-its-outcome-is-unknown)+when an action's outcome is uncertain; they do not pull or recreate anything.+Do not restart or reinstall the agent, broaden a token, disable TLS verification+or delete images or volumes to test the indicator. Keep full inspections,+environments and registry credentials private.+### Updating a Container1. Open **Docker → Overview** (`/docker/overview`) and find the host and containerdiff --git a/frontend-modern/src/features/docs/__tests__/dockerUpdateGuide.test.ts b/frontend-modern/src/features/docs/__tests__/dockerUpdateGuide.test.tsindex 19a665f455..503cdbcd6e 100644--- a/frontend-modern/src/features/docs/__tests__/dockerUpdateGuide.test.ts+++ b/frontend-modern/src/features/docs/__tests__/dockerUpdateGuide.test.ts@@ -25,6 +25,87 @@ function section(article: HTMLElement, id: string): string {}describe('shipped monitored-container update guide', () => {+ it('distinguishes a cached comparison and its timestamp from fresh registry evidence', () => {+ const article = renderGuide();+ const text = section(article, 'reading-an-update-indicator');+ for (const phrase of [+ 'not an installation result or an application health check',+ 'a difference alone does not establish which image is newer',+ 'Successful registry lookups are cached for up to six hours',+ 'checked timestamp can advance',+ 'not proof that every container was checked',+ "Reloading the page does not refresh the agent's registry cache",+ 'unknown, not evidence that the image is up to date',+ ]) {+ expect(text).toContain(phrase);+ }+ expect(section(article, 'how-it-works')).toContain('that lookup can be cached');+ expect(section(article, 'how-it-works')).not.toContain('the latest digest');+ });++ it('keeps the documented cache and clock limits bound to their producers', () => {+ // Source consistency only: this does not execute a registry check or+ // reproduce the reporter's failed comparison after recreation.+ const registry = readFileSync(+ path.join(repoRoot, 'internal/dockeragent/registry.go'),+ 'utf8',+ );+ const collector = readFileSync(+ path.join(repoRoot, 'internal/dockeragent/collect.go'),+ 'utf8',+ );+ const adapter = readFileSync(+ path.join(repoRoot, 'internal/unifiedresources/adapters.go'),+ 'utf8',+ );+ expect(registry).toMatch(/defaultCacheTTL\s*=\s*6\s*\*\s*time.Hour/);+ const cacheHit = registry+ .split('if cached := r.getCached(cacheKey); cached != nil {')[1]+ .split('// Fetch latest digest from registry')[0];+ expect(cacheHit).toMatch(/LatestDigest:\s+cached.latestDigest/);+ expect(cacheHit).toMatch(/CheckedAt:\s+time.Now\(\)/);+ expect(collector).toMatch(/LastChecked:\s+result.CheckedAt/);+ expect(adapter).toContain('container.UpdateStatus.LastChecked.After(updatesLastCheckedAt)');+ });++ it('does not compare local image IDs with registry or other-platform manifest digests', () => {+ const text = section(renderGuide(), 'reading-an-update-indicator');+ for (const phrase of [+ 'The same tag text can refer to different images',+ 'not a registry manifest. Do not compare it directly with latestDigest',+ 'top-level index and its platform-specific manifest have different digests',+ 'same repository, tag, platform and manifest layer',+ ]) {+ expect(text).toContain(phrase);+ }+ });++ it('leads a returning indicator to existing read-only state checks, not a second update', () => {+ const article = renderGuide();+ const text = section(article, 'reading-an-update-indicator');+ for (const phrase of [+ 'do not repeat the update just to clear it',+ 'existing action receipt',+ "application's ordinary health first",+ 'they do not pull or recreate anything',+ 'Do not restart or reinstall the agent, broaden a token, disable TLS verification',+ 'delete images or volumes to test the indicator',+ 'Keep full inspections, environments and registry credentials private',+ ]) {+ expect(text).toContain(phrase);+ }+ const link = Array.from(article.querySelectorAll('a')).find(+ (anchor) => anchor.textContent === 'read-only workload state checks',+ );+ expect(link?.getAttribute('href')).toBe(+ '/docs/DOCKER#action-was-sent-or-its-outcome-is-unknown',+ );+ expect(link?.hasAttribute('data-doc-link')).toBe(true);+ expect(article.querySelector(link!.hash)?.textContent).toBe(+ 'Action was sent or its outcome is unknown',+ );+ });+it('separates a legacy monitoring credential from independent runner posture and operator intent', () => {const text = section(renderGuide(), 'command-agent-is-not-connected');for (const phrase of [