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
Route explicit Docker Hub image references to the manifest API
pulse-triage[bot]02ec15178b03
diff --git a/docs/release-control/v6/internal/subsystems/agent-lifecycle.md b/docs/release-control/v6/internal/subsystems/agent-lifecycle.mdindex 55ac477663..956763b9fe 100644--- a/docs/release-control/v6/internal/subsystems/agent-lifecycle.md+++ b/docs/release-control/v6/internal/subsystems/agent-lifecycle.md@@ -4502,6 +4502,28 @@ checks that used to work anonymously keep working, andkeeps detection anonymous-only without reading the store or executinghelpers.+### Docker Hub image aliases use the manifest API++Docker / Podman image metadata lookup treats bare, `docker.io`,+`index.docker.io`, `registry.docker.io` and `registry-1.docker.io` Hub+references equivalently: manifests use HTTPS `registry-1.docker.io`, token+negotiation retains the Hub service and repository-only pull scope, and a+single-component official repository gains `library/`. Explicit ports and+other registry hosts retain their own repository paths and authentication.+Equivalent Hub references share a platform-specific cache, not a cache across+different architectures. Stored Hub credentials retain the legacy index-key+lookup and never enter metadata reports; only the negotiated token is attached+to manifest requests. Digest-pinned images and every Hub spelling of the+Pulse-managed repository remain outside generic update detection.++Normalization must not weaken non-manifest refusal, turn registry failures into+update availability, change local RepoDigest/index/platform comparison, or run+an image update. `TestDockerHubReferenceRouting`,+`TestDockerHubAliasLookupContract`, `TestDockerHubAliasLookupFailures` and+`TestDockerHubAliasesPreserveManagedAndPinnedExclusions` pin these boundaries+with synthetic registry transport and credential files. They establish source+behaviour, not live Hub, installed-agent or reporter recovery.+### Governed action readiness remains outside agent lifecycle authorityThe canonical Actions lifecycle may ask an executor-owneddiff --git a/internal/dockeragent/docker_hub_reference_test.go b/internal/dockeragent/docker_hub_reference_test.gonew file mode 100644index 0000000000..b4412696ba--- /dev/null+++ b/internal/dockeragent/docker_hub_reference_test.go@@ -0,0 +1,210 @@+package dockeragent++import (+ "context"+ "crypto/sha256"+ "encoding/base64"+ "fmt"+ "net/http"+ "strings"+ "testing"++ "github.com/rs/zerolog"+)++func TestDockerHubReferenceRouting(t *testing.T) {+ for _, host := range []string{"docker.io", "index.docker.io", "registry-1.docker.io", "registry.docker.io"} {+ for _, repo := range []string{"nginx", "library/nginx", "team/app"} {+ ref := host + "/" + repo + ":stable"+ t.Run(ref, func(t *testing.T) {+ wantRepo := repo+ if !strings.Contains(repo, "/") {+ wantRepo = "library/" + repo+ }+ registry, repository, tag := parseImageReference(ref)+ if registry != "registry-1.docker.io" || repository != wantRepo || tag != "stable" {+ t.Fatalf("parseImageReference(%q) = %q, %q, %q", ref, registry, repository, tag)+ }+ })+ }+ }+ for _, tt := range []struct{ ref, registry, repository, tag string }{+ {"nginx", "registry-1.docker.io", "library/nginx", "latest"},+ {"team/app:v2", "registry-1.docker.io", "team/app", "v2"},+ {"docker.io:5000/nginx:stable", "docker.io:5000", "nginx", "stable"},+ {"index.docker.io:5000/app", "index.docker.io:5000", "app", "latest"},+ {"docker.io.example/app:v2", "docker.io.example", "app", "v2"},+ {"registry.example:5000/team/app:v2", "registry.example:5000", "team/app", "v2"},+ {"localhost:5000/app:v2", "localhost:5000", "app", "v2"},+ {"[::1]:5000/app:v2", "[::1]:5000", "app", "v2"},+ {"ghcr.io/team/app:v2", "ghcr.io", "team/app", "v2"},+ {"docker.io/nginx@sha256:" + strings.Repeat("a", 64), "", "", ""},+ } {+ t.Run(tt.ref, func(t *testing.T) {+ registry, repository, tag := parseImageReference(tt.ref)+ if registry != tt.registry || repository != tt.repository || tag != tt.tag {+ t.Fatalf("parseImageReference(%q) = %q, %q, %q", tt.ref, registry, repository, tag)+ }+ })+ }+}++// Drive the real token, manifest fallback, platform comparison and cache paths.+// Only the HTTP transport and host credential files are synthetic; no Docker+// daemon, live registry, credential helper or container mutation is involved.+func TestDockerHubAliasLookupContract(t *testing.T) {+ index := `{"schemaVersion":2,"manifests":[{"digest":"sha256:amd64","platform":{"architecture":"amd64","os":"linux"}},{"digest":"sha256:armv7","platform":{"architecture":"arm","os":"linux","variant":"v7"}}]}`+ indexDigest := fmt.Sprintf("sha256:%x", sha256.Sum256([]byte(index)))+ for _, host := range []string{"", "docker.io/", "index.docker.io/", "registry-1.docker.io/", "registry.docker.io/"} {+ for _, repo := range []string{"nginx", "team/app"} {+ for _, credentialed := range []bool{false, true} {+ ref := host + repo + ":stable"+ t.Run(fmt.Sprintf("%s/credentialed=%t", ref, credentialed), func(t *testing.T) {+ checker := NewRegistryChecker(zerolog.Nop())+ if credentialed {+ auth := base64.StdEncoding.EncodeToString([]byte("synthetic-user:synthetic-secret"))+ checker.credentials = newTestCredentialStore(map[string]string{+ "/synthetic/docker/config.json": fmt.Sprintf(`{"auths":{"https://index.docker.io/v1/":{"auth":%q}}}`, auth),+ }, map[string]string{"DOCKER_CONFIG": "/synthetic/docker"})+ }+ wantRepo := repo+ if repo == "nginx" {+ wantRepo = "library/nginx"+ }+ var requests []string+ checker.httpClient = &http.Client{Transport: roundTripFunc(func(req *http.Request) (*http.Response, error) {+ requests = append(requests, req.Method+" "+req.URL.Host+req.URL.Path)+ if req.URL.Scheme != "https" {+ t.Error("registry lookup lost HTTPS")+ }+ if req.URL.Host == "auth.docker.io" {+ if req.Method != http.MethodGet || req.URL.Path != "/token" || req.URL.Query().Get("service") != "registry.docker.io" || req.URL.Query().Get("scope") != "repository:"+wantRepo+":pull" {+ t.Error("token request lost the canonical Hub pull scope")+ }+ user, secret, ok := req.BasicAuth()+ if credentialed && (!ok || user != "synthetic-user" || secret != "synthetic-secret") {+ t.Error("legacy Hub credential key was not resolved")+ } else if !credentialed && req.Header.Get("Authorization") != "" {+ t.Error("anonymous lookup attached credentials")+ }+ return newStringResponse(200, nil, `{"token":"synthetic-hub-token"}`), nil+ }+ if req.URL.Host != "registry-1.docker.io" || req.URL.Path != "/v2/"+wantRepo+"/manifests/stable" {+ t.Error("manifest lookup left the canonical Hub route")+ return newStringResponse(200, nil, `<html>not a registry</html>`), nil+ }+ if req.Header.Get("Authorization") != "Bearer synthetic-hub-token" || !strings.Contains(req.Header.Get("Accept"), "application/vnd.oci.image.index.v1+json") {+ t.Error("manifest request lost its token or multi-platform Accept header")+ }+ headers := map[string]string{"Content-Type": "application/vnd.oci.image.index.v1+json"}+ if req.Method == http.MethodHead {+ return newStringResponse(200, headers, ""), nil+ }+ return newStringResponse(200, headers, index), nil+ })}+ local := "sha256:other,sha256:amd64"+ got := checker.CheckImageUpdate(context.Background(), ref, local, "amd64", "linux", "")+ if got == nil || got.Error != "" || got.Image != ref || got.CurrentDigest != "sha256:other" || got.LatestDigest != indexDigest || got.UpdateAvailable {+ t.Fatalf("same-platform lookup = %+v", got)+ }+ if len(requests) != 3 {+ t.Fatalf("requests = %v, want token, HEAD and GET", requests)+ }+ for _, cachedRef := range []string{wantRepo + ":stable", "docker.io/" + wantRepo + ":stable", "index.docker.io/" + wantRepo + ":stable"} {+ got = checker.CheckImageUpdate(context.Background(), cachedRef, "sha256:old", "amd64", "linux", "")+ if got == nil || got.Error != "" || !got.UpdateAvailable || got.LatestDigest != indexDigest {+ t.Fatalf("changed-image cached lookup = %+v", got)+ }+ }+ if len(requests) != 3 {+ t.Error("equivalent Hub aliases repeated a cached registry lookup")+ }+ got = checker.CheckImageUpdate(context.Background(), ref, "sha256:armv7", "arm", "linux", "v7")+ if got == nil || got.Error != "" || got.UpdateAvailable || got.LatestDigest != indexDigest || len(requests) != 6 {+ t.Fatalf("ARMv7 lookup did not keep its separate platform cache: %+v", got)+ }+ })+ }+ }+ }+}++func TestDockerHubAliasLookupFailures(t *testing.T) {+ for _, tt := range []struct {+ name string+ tokenStatus int+ headStatus int+ body string+ wantError string+ }{+ {"HTML", 200, 200, `<html>login</html>`, "non-manifest response"},+ {"JSON error", 200, 200, `{"errors":[{"code":"UNAVAILABLE"}]}`, "non-manifest response"},+ {"token refused", 401, 200, "", "token request failed: 401"},+ {"unauthorized", 200, 401, "", "authentication required"},+ {"not found", 200, 404, "", "image not found"},+ {"rate limited", 200, 429, "", "rate limited"},+ {"server error", 200, 500, "", "registry error: 500"},+ } {+ t.Run(tt.name, func(t *testing.T) {+ checker := NewRegistryChecker(zerolog.Nop())+ calls := 0+ checker.httpClient = &http.Client{Transport: roundTripFunc(func(req *http.Request) (*http.Response, error) {+ calls+++ if req.URL.Host == "auth.docker.io" {+ return newStringResponse(tt.tokenStatus, nil, `{"token":"synthetic"}`), nil+ }+ if req.URL.Host != "registry-1.docker.io" {+ t.Error("failure lookup left the canonical Hub route")+ }+ if req.Method == http.MethodHead {+ return newStringResponse(tt.headStatus, nil, ""), nil+ }+ return newStringResponse(200, nil, tt.body), nil+ })}+ for _, ref := range []string{"docker.io/nginx:stable", "index.docker.io/library/nginx:stable"} {+ got := checker.CheckImageUpdate(context.Background(), ref, "sha256:old", "amd64", "linux", "")+ if got == nil || !strings.Contains(got.Error, tt.wantError) || got.LatestDigest != "" || got.UpdateAvailable {+ t.Fatalf("failure invented an update: %+v", got)+ }+ if ref == "docker.io/nginx:stable" {+ continue+ }+ wantCalls := 2+ if tt.tokenStatus != 200 {+ wantCalls = 1+ } else if tt.headStatus == 200 {+ wantCalls = 3+ }+ if calls != wantCalls {+ t.Fatalf("failure cache issued %d calls, want %d", calls, wantCalls)+ }+ }+ })+ }+}++func TestDockerHubAliasesPreserveManagedAndPinnedExclusions(t *testing.T) {+ checker := NewRegistryChecker(zerolog.Nop())+ checker.httpClient = &http.Client{Transport: roundTripFunc(func(*http.Request) (*http.Response, error) {+ t.Fatal("excluded image attempted a registry request")+ return nil, nil+ })}+ for _, host := range []string{"", "docker.io/", "index.docker.io/", "registry-1.docker.io/", "registry.docker.io/"} {+ for _, suffix := range []string{":latest", "@sha256:" + strings.Repeat("a", 64)} {+ ref := host + "rcourtman/pulse" + suffix+ if got := checker.CheckImageUpdate(context.Background(), ref, "sha256:old", "", "", ""); got != nil {+ t.Errorf("managed alias %q returned %+v", ref, got)+ }+ }+ ref := host + "nginx@sha256:" + strings.Repeat("a", 64)+ got := checker.CheckImageUpdate(context.Background(), ref, "sha256:old", "", "", "")+ if got == nil || got.Error != "digest-pinned image" || got.UpdateAvailable || got.LatestDigest != "" {+ t.Errorf("pinned alias returned %+v", got)+ }+ }+ for _, ref := range []string{"docker.io/rcourtman/pulse-extra:latest", "docker.io/another/pulse:latest", "docker.io:5000/rcourtman/pulse:latest", "docker.io.example/rcourtman/pulse:latest"} {+ if isPulseManagedImageReference(ref) {+ t.Errorf("non-managed reference %q was excluded", ref)+ }+ }+}diff --git a/internal/dockeragent/registry.go b/internal/dockeragent/registry.goindex c7c78c078f..297465105c 100644--- a/internal/dockeragent/registry.go+++ b/internal/dockeragent/registry.go@@ -130,9 +130,11 @@ type ImageUpdateResult struct {func isPulseManagedImageReference(image string) bool {normalized := strings.ToLower(strings.TrimSpace(image))+ if host, rest, explicit := strings.Cut(normalized, "/"); explicit && isDockerHubRegistry(host) {+ normalized = rest+ }for _, repository := range []string{"rcourtman/pulse",- "docker.io/rcourtman/pulse","license.pulserelay.pro/pulse-pro","registry.pulserelay.pro/pulse/pulse-pro",} {@@ -145,6 +147,17 @@ func isPulseManagedImageReference(image string) bool {return false}+// Hub reference and credential aliases name the same registry, but manifests+// and pull tokens must use the v2 API rather than Docker Hub's web/index hosts.+// A port or a lookalike domain is a distinct registry and must not be rewritten.+func isDockerHubRegistry(host string) bool {+ switch strings.ToLower(host) {+ case "docker.io", "index.docker.io", "registry.docker.io", "registry-1.docker.io":+ return true+ }+ return false+}+// NewRegistryChecker creates a new registry checker for the Docker / Podman module.func NewRegistryChecker(logger zerolog.Logger) *RegistryChecker {return newRegistryCheckerWithConfig(logger, true)@@ -951,6 +964,15 @@ func parseImageReference(image string) (registry, repository, tag string) {repository = image}+ if isDockerHubRegistry(registry) {+ registry = "registry-1.docker.io"+ // Explicit official-image references need the same library namespace+ // as their short form; never add it to a custom registry's repository.+ if !strings.Contains(repository, "/") {+ repository = "library/" + repository+ }+ }+return registry, repository, tag}