Preventing Registry Storage Exhaustion with Harbor Project Quotas

Problem: One Project’s Storage Can Block the Whole Registry

In multi‑tenant Harbor setups, a single project can grow unchecked. Every pushed image, every layer, and every tagged manifest accumulates on the same backend storage. When that project fills the disk, subsequent pushes fail, other teams encounter 503 errors, and the registry effectively locks out everyone else.

Thesis: Project Quotas Put a Cap on per‑Project Usage

Harbor Project Quotas feature lets administrators assign a maximum storage size to each project. Once the limit is reached, the behavior depends on the quota type: a hard quota blocks new image pushes entirely, while a soft quota only emits a warning. This caps the blast radius of any one team and gives ops a lever to enforce resource allocation.

How the Quota Calculation Works

Storage is tallied at the project level. Every tag, layer, and associated blob for every image in that project counts toward the total. If a project has three images with two tags each, all associated manifest JSON files and image layers are summed. Understanding this scope is key before setting a number.

1. Navigate to the project in the Harbor UI.
2. Open the Configuration tab.
3. Enter a quota size in gigabytes (e.g., 10 GB).
4. Choose Hard or Soft mode.

Worked Example: Setting a Soft Quota via the UI

A common setup involves a project named team‑alpha and a desire to cap its storage at 15 GB as a soft limit. In the Harbor UI:

• Go to Projects → select team‑alpha.
• Click the Configuration tab.
• Locate the Quota field.
• Set the value to 15 and keep the toggle on Soft.
• Save the changes.

From this point forward, pushes that would push the project past 15 GB trigger a warning event (visible in the UI and logs) but do not abort the push. If the project later exceeds 15 GB, new pushes receive a 413 Request Entity Too Large‑style error, depending on the Harbor version and configuration.

Garbage Collection Interaction

Quotas do not automatically shrink when images are deleted. Harbor Garbage Collection process must run to reclaim space from untagged manifests and orphaned blobs. After deleting images, schedule or run the gc command (or use the UI’s GC button) and then verify the project’s reported storage size has decreased.

Trade‑offs and Limitations

1. Hard quotas can abort CI/CD pipelines. If a push crosses the limit during a build, the job fails with a quota‑related error. Teams should start with soft quotas and promote to hard only after a buffer is established.
2. Storage calculation has a slight delay. After a push, the quota metric may not reflect the new size immediately; a few minutes can pass before Harbor updates the internal counter.
3. Deleting images does not free quota space instantly. The freed bytes are only counted after Garbage Collection completes, so manual GC runs are required to recover space.

Actionable Next Steps

1. Identify the projects that have grown largest in your registry.
2. Set a soft quota on the most aggressive project, using the steps above.
3. Monitor push logs for quota warnings over the next few days.
4. Schedule regular Garbage Collection runs, especially after image deletion batches.
5. If the soft quota proves too permissive, promote it to hard and document the impact on CI/CD workflows.