How to Use Garbage Collection to Free Up Space in Your Container Registry

When you delete an image manifest from the DigitalOcean Container Registry (DOCR), it may leave layer data that is no longer referenced by any manifest in your registry. These unused layers occupy space in your registry. You can check the amount of space being used in your registry in the control panel. Use garbage collection to clean up the unused image layers and free up storage in your registry.

Considerations

• Your registry is temporarily put into a read-only mode while garbage collection is running.
• After entering read-only mode, DOCR must wait for any previous authentication for write operations to expire before starting garbage collection. This can take up to 15 minutes, depending on when the last write operation started.

Run Garbage Collection

You can manually start garbage collection using the command line and the API.

Run the garbage-collection command to start garbage collection on your container registry:

doctl registry garbage-collection start [--include-untagged-manifests] [<your-registry-name>]

The command initiates garbage collection and warns you that the registry will be put into read-only mode. The garbage collection starts once you confirm to proceed. The command also provides the UUID of the garbage collection. We recommend including the --include-untagged-manifests option since this ensures that untagged manifests are also deleted, thereby maximizing the amount of space freed by the garbage collection.

To retrieve information about the currently-running garbage collection, run the following command:

doctl registry garbage-collection get-active [<your-registry-name>]

To cancel any currently-active garbage collections for your registry, run the following command:

doctl registry garbage-collection cancel [<your-registry-name>] <gc-uuid>

If you want to see all the garbage collections that you have run on a registry, run the following command:

doctl registry garbage-collection list [<your-registry-name>]