Thanks to visit codestin.com
Credit goes to github.com

Skip to content

Conversation

Maximilian-Nesslauer
Copy link

Improve registry lookup feature with full image path support

This builds on @manfred-martin 's original implementation from PR #454 (which was closed without merging).
His work introduced the wud.registry.lookup.url label to help users bypass Docker registry caches when checking for updates.

Closes #451


Background

Since PR #454 was created, the codebase has moved forward a few versions. This PR merges the original feature branch with version 8.1.1 to bring it up to date with the latest stable release.

However, while testing the original URL-based approach with my Harbor registry setup, I discovered a fundamental issue for my usecase: it doesn't work with registries that use project prefixes or nested paths.

The Problem

The original implementation accepted registry URLs like https://registry-1.docker.io and tried to extract the image name from them. This breaks with registries like Harbor, where images look like:

harbor.example.com/dockerhub-proxy/traefik:v3.5.3

The dockerhub-proxy/ part is a Harbor project name, not part of the actual image name.
The URL-based approach would incorrectly include it as part of the image path, causing registry matching to fail. This same problem affects other registries that use hierarchical project structures.

My Solution and Changes

Instead of accepting registry URLs and trying to parse them, accept full image paths directly. While this requires typing the full image path (which may be slightly longer than just a URL), it's more explicit and generic, works with any registry structure, and lets users specify exactly what upstream image WUD should check for updates.

What Changed

  • Renamed label from wud.registry.lookup.url to wud.registry.lookup.image
  • Now accepts full image paths (e.g., library/traefik or ghcr.io/user/image)
  • Automatically defaults to Docker Hub for short-form images without a registry
  • Fixed registry normalization to use the lookup image instead of the original
  • Updated documentation
  • Added Prometheus metric support for the lookup image field
  • Removed tests specific to URL-based parsing (no longer needed with generic image path approach)

Example Usage

services:
  traefik:
    image: harbor.example.com/dockerhub-proxy/traefik:v3.5.3
    labels:
      - wud.watch=true
      - wud.registry.lookup.image=library/traefik

This allows WUD to check registries like Docker Hub for traefik updates while the container continues pulling from the Harbor proxy cache, solving the original issue where proxy registries don't have up-to-date tag information.

Testing

  • I did test with Harbor proxy cache projects (Docker Hub, GHCR, Codeberg)
  • All 428 unit tests passing
  • Live deployment on my homelab

Breaking Changes

This changes the label name from wud.registry.lookup.url to wud.registry.lookup.image. However, since PR #454 was never merged into a release, this shouldn't affect any users that are not using the feature/#451_customizable_registry_url branch.

fmartinou and others added 2 commits October 10, 2025 23:07
This builds on Manfred Martin's <[email protected]> original implementation from PR getwud#454 (which
was closed without merging). His work introduced the `wud.registry.lookup.url`
label to help users bypass Docker registry caches when checking for updates.

This commit merges the original feature branch with version 8.1.1 to bring it up to
date with the latest stable release, ensuring compatibility with recent changes.

However, while testing the original URL-based approach with my Harbor registry
setup, I discovered a fundamental issue: it doesn't work with registries that
use project prefixes or nested paths.

The problem:
The original implementation accepted registry URLs like
"https://registry-1.docker.io" and tried to extract the image name from them.
This breaks with enterprise registries like Harbor, where images look like:
  harbor.example.com/dockerhub-proxy/traefik:v3.5.3

The "dockerhub-proxy/" part is a Harbor project name, not part of the actual
image name. The URL-based approach would incorrectly include it as part of
the image path, causing registry matching to fail. This same problem affects
other registries that use hierarchical project structures.

The solution:
Instead of accepting registry URLs and trying to parse them, accept full image
paths directly. While this requires typing the full image path (which may be
slightly longer than just a URL), it's more explicit and generic, works with any registry
structure, and lets users specify exactly what upstream image WUD should check
for updates.

What changed:
- Renamed label from `wud.registry.lookup.url` to `wud.registry.lookup.image`
- Now accepts full image paths (e.g., "library/traefik" or "ghcr.io/user/image")
- Automatically defaults to Docker Hub for short-form images without a registry
- Fixed registry normalization to use the lookup image instead of the original
- Updated documentation
- Added Prometheus metric support for the lookup image field
- Removed tests specific to URL-based parsing (no longer needed with generic image path approach)

Example usage:
  image: harbor.example.com/dockerhub-proxy/traefik:v3.5.3
  labels:
    - wud.watch=true
    - wud.registry.lookup.image=library/traefik

This allows WUD to check Docker Hub for traefik updates while the container
continues pulling from the Harbor proxy cache, solving the original issue where
proxy registries don't have up-to-date tag information.

Tested with:
- Harbor proxy cache (Docker Hub, GHCR, Codeberg)
- All 428 unit tests passing
- Live deployment on my homelab
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

[Feature Request] Replace parts of image path to bypass docker registry cache

2 participants