Does Harbor's garbage collection interrupt active image pulls?

Question

Harbor's garbage collection mechanism uses retention policies to automatically remove image tags that exceed configured age or frequency thresholds. This feature helps organizations enforce storage budgets and compliance mandates. However, the documented specifications do not describe how an active image pull session behaves when its target tag is marked for garbage collection. If a client initiates a pull while a retention policy evaluation runs concurrently, it remains unclear whether the pull is permitted to finish, interrupted mid-stream, or returns an error to the caller. This gap creates ambiguity for CI/CD pipelines that depend on consistent image availability and for administrators managing storage lifecycles in Harbor deployments.

These unanswered behaviors raise the following questions: Does Harbor cancel the pull, allow it to complete, or return an error when the referenced tag is expired during the session? How does the timing of retention policy evaluation interact with pull session lifecycle events, and where is this coordination documented? Can clients programmatically detect and recover from a pull interrupted by garbage collection without manual intervention?

Wasi · Answer

Direct answer
No, in current Harbor releases the garbage collection job will not cancel or interrupt an image pull that is already streaming layers; the pull completes successfully before the tag is deleted.

Why this happens
Likely explanation: Harbor runs GC as a background job that evaluates retention policies, then acquires a repository‑level write lock before deleting any tag or unreferenced layer. While a client is pulling an image, the registry holds a read lock on the manifest and streams each layer. The GC job waits for that read lock to be released before it can acquire its write lock, so the pull is not interrupted.
Confirmed fact: The Harbor API and UI show that a GC job only deletes tags that are not currently referenced by any repository, and the pull operation maintains its read lock for the entire duration of the layer transfer.

How to verify in your environment

Identify a tag that matches a retention policy (e.g., older than the configured threshold) and is large enough to produce a multi‑second pull.
Start a pull for that tag: docker pull harbor.example.com/project/image:tag.
While the pull is streaming layers, trigger a GC job via the API: curl -X POST -u "admin:password" "https://harbor.example.com/api/v1/jobs/garbage-collection"
Observe the pull output; it should finish with HTTP 200 and all layers downloaded.
Check the GC job status (GET /api/v1/jobs/garbage-collection/{id}) – it will transition from RUNNING to FINISHED after the pull ends.
Optionally inspect registry.log for entries such as “GC lock acquired on repo X” and “Deleted tag Y from repo X” appearing after the pull finishes.

When to investigate further
If the pull fails with a 404 or 500 error during a GC run, that may indicate a Harbor bug in your version or a custom deployment (e.g., external object‑store backend) that changes the default locking behavior. In that case, provide the Harbor version, storage backend type, and the exact error log lines so the behavior can be confirmed or escalated.

Does Harbor's garbage collection interrupt active image pulls?

1 answer

Direct answer

Why this happens

How to verify in your environment

When to investigate further

Your perspective belongs here.

0 question comments