Private Container Registry Garbage Collection Settings

Each Private Container Registry offers a configurable Garbage Collection schedule to reclaim storage space from deleted images. Garbage Collection is turned off by default, giving you full control over when and how cleanup occurs. For more information, see the Garbage collection FAQ.

Understand the following key behaviors before configuring garbage collection:

Note:

• Read-only mode: During garbage collection, the Private Container Registry enters a read-only state. Workloads can still pull images, but you cannot push images while the process runs. Schedule garbage collection during low-traffic windows.

• Timing of storage recovery: Deleting an image or tag does not immediately free storage space. The Private Container Registry hides deleted items from view, but the underlying data remains on disk. The Private Container Registry reclaims storage only after garbage collection completes. The size of the Private Container Registry determines how long garbage collection takes.

• Billing impact: Your invoice reflects actual disk usage. Storage recovery and billing updates occur after garbage collection finishes.

How garbage collection works

Garbage collection reclaims storage by removing orphaned data that no images reference. Before you begin, familiarize yourself with the following key terms:

• Layer: A unit of container image data. Example: an operating system base image, application code. One layer can be shared by multiple images.

• Image manifest: A metadata record that lists all layers in an image. Deleting the manifest tells the Private Container Registry the image is no longer needed.

• Tag: A human-readable label that points to a manifest. Example: v1.0.0. One manifest can have multiple tags.

• Untagged image: An image without a tag, identified only by its digest (a unique hash). Example: SHA256. Modern container workloads often reference images by digest instead of tag.

The cleanup flow

1. You delete one or more image manifests, either by tag or digest.

2. Garbage collection scans for manifests marked as deleted and checks which layers are still referenced by active images.

3. Layers with no active references are permanently deleted from the disk.

4. Storage usage decreases and billing is updated.

Garbage collection duration: Completion time depends on the Private Container Registry size and the number of layers to scan.

How should I clean up my images?

Use the decision matrix to arrive at a solution:

Scenario	Action	Time to storage recovery
Delete an image by tag. Example: app:old-version	Delete using the DCD or API; run garbage collection	Storage is reclaimed after garbage collection completes
Delete an untagged image (digest-based)	Delete using the API or regctl, then wait for garbage collection to run	Storage is reclaimed after garbage collection completes
Immediate visibility removal needed	Delete immediately using the DCD; garbage collection runs later	Immediate visibility; delayed garbage collection

Configure garbage collection

To turn on the garbage collection and set a recurring schedule from the DCD:

API-based configuration: You can also configure garbage collection through the API for more granular control. Example: custom intervals, manual triggers. For more information, see API documentation.

1. In the DCD, go to Menu > Containers > Container Registry.

2. Select a Private Container Registry to configure garbage collection. You can also select the OPTIONS menu > Properties.

Select the Private Container Registry

3. In the Properties tab, click > in the Garbage Collection row to expand the configuration panel.

Select the Garbage Collection Schedule

4. Select a Day and Time (UTC) for garbage collection to run on a weekly basis. Choose a time when workload traffic is minimal. Read-only mode prevents pushes and pulls during cleanup.

5. Click Update Schedule to save your settings.

Edit the Garbage Collection Schedule

Result: Garbage collection now runs automatically at your chosen time each week.

Delete images

To free storage space, follow the sequence:

1

Delete the image manifest

Mark images for deletion using one of these methods mentioned in the following tabs:

From the DCD (by tag)

1. Navigate to your Private Container Registry.

2. Find the image and tag you want to delete.

3. Click the OPTIONS menu and select Delete.

4. Confirm the deletion.

The image is now hidden from the DCD, but the underlying data remains on disk.

Using API or `regctl` (by digest)

To delete untagged images by digest or automate the process, use the API or the regctl command-line tool.

Option A: Using `regctl` (recommended for simplicity)

regctl image delete <registry-url>/<repository>/<image-name>@<digest>

Replace the placeholders:

• <registry-url>: Your Private Container Registry URL. Example: registry.example.com

• <repository>: The repository path. Example: my-app

• <image-name>: The image name. Example: api-server

• <digest>: The image digest. Example: sha256:abc123...

Example:

regctl image delete registry.example.com/my-app/api-server@sha256:abc123def456

Option B: Using the Registry API directly

Docker CLI limitation: The standard Docker CLI (docker image rm) does not support deleting images from a remote Private Container Registry. Use regctl or the API instead.

1. Obtain an authentication token:

curl -u <username>:<password> \
  "https://<registry-url>/auth/token?scope=repository:<repository>/<image>:pull,delete&service=<registry-url>"

Replace placeholders and copy the token from the response.

2. Delete the manifest using the token:

curl -X DELETE \
  -H "Authorization: Bearer <token>" \
  -H "Accept: application/vnd.docker.distribution.manifest.v2+json" \
  "https://<registry-url>/v2/<repository>/<image>/manifests/<digest>"

Result: The server returns an HTTP 202 status when it accepts a manifest deletion request for background processing.

2

Run garbage collection

After deleting manifests, trigger garbage collection to reclaim storage:

1. Wait for your scheduled garbage collection time, or contact support to request an immediate run.

2. During execution, your Private Container Registry will be in read-only mode.

3. After completion, check your storage metrics in the DCD to confirm the reduction.

Result: Orphaned layers are deleted from disk and storage usage decreases.