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 cached Docker update evidence before repeating an action

pulse-triage[bot]4c40f0f0e951
diff --git a/docs/DOCKER.md b/docs/DOCKER.md
index 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 cached
2. **Visual Indicator**: Containers with available updates show a blue upward arrow icon
3. **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 Container
1. Open **Docker → Overview** (`/docker/overview`) and find the host and container
diff --git a/frontend-modern/public/docs/DOCKER.md b/frontend-modern/public/docs/DOCKER.md
index 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 cached
2. **Visual Indicator**: Containers with available updates show a blue upward arrow icon
3. **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 Container
1. Open **Docker → Overview** (`/docker/overview`) and find the host and container
diff --git a/frontend-modern/src/features/docs/__tests__/dockerUpdateGuide.test.ts b/frontend-modern/src/features/docs/__tests__/dockerUpdateGuide.test.ts
index 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 [