Add delete cache API for container virtual registry (!213785) · Merge requests · GitLab.org / GitLab

What does this MR do and why?

This change adds endpoints to enable cache purging for container virtual registries. It allows users to clear cached data from virtual registries and their upstream sources through new API endpoints. When triggered, the system marks the given cached entries for deletion. The feature includes proper authorization checks to ensure only users with appropriate permissions (owners and maintainers) can purge caches, and includes comprehensive testing to verify the functionality works correctly.

In the next issue: Destroy cache entries that are marked for deletion (#581789), we do the actual destroy on the cache entries that were marked for deletion.

Route	Notes
DELETE /virtual_registries/container/upstreams/:id/cache	Clear cache on an upstream
DELETE /virtual_registries/container/registries/:id/cache	Clear cache on a registry

How to set up and validate locally

🍃 Prerequisites:

Enable the feature flag

Feature.enable(:container_virtual_registries)

Have a **personal access token **ready. Here is a guide: https://docs.gitlab.com/user/profile/personal_access_tokens/#create-a-personal-access-token
Have an upstream ID ready

VirtualRegistries::Container::Upstream.first.id

If you don't have an upstream in your local machine, you may create one with the following. Update the registry ID 1 in the URL as needed.

curl --location 'http://gdk.test:3000/api/v4/virtual_registries/container/registries/1/upstreams' \
--header 'PRIVATE-TOKEN: glpat-your-token-here' \
--form 'url="https://sample.com"' \
--form 'username="testuser"' \
--form 'password="testpass"' \
--form 'name="upstream1"'

Setup your GDK with an enterprise license (Premium). Follow these steps: https://gitlab.com/gitlab-org/customers-gitlab-com/-/blob/main/doc/setup/gitlab.md#adding-a-license-from-staging-customers-portal-to-your-gdk.
cURL in your terminal or you may also use Postman (or similar)

Reference script: Creating cache entries

You can create a cache entry for your upstream with the following. Feel free to repeat it if you'd like to have multiple cache entries, just update the upstream_etag and relative_path values.

temp_file = Tempfile.new(['cache_entry', '.txt'])
temp_file.write('test content for the cache entry')
temp_file.rewind

upstream.cache_entries.create(
  upstream_etag: 'atest',
  upstream_checked_at: Time.zone.now,
  content_type: 'text/plain',
  file_md5: 'd8e8fca2dc0f896fd7cb4cb0031ba249',
  file_sha1: '4e1243bd22c66e76c2ba9eddc1f91394e57f9f83',
  group: upstream.group,
  relative_path: 'library/alpine/manifests/latesta',
  size: 1.kilobyte,
  file: temp_file
)

temp_file.close
temp_file.unlink

Endpoint 1: `DELETE /virtual_registries/container/upstreams/:id/cache`

With this endpoint, we set all the cache entries of an upstream for deletion. Before you run the cURL command below, you can inspect the current status of the upstreams:

upstream.cache_entries.pluck(:status)
# => ["default", "default", "default"]

And then you can call the endpoint with:

curl --location --request DELETE 'http://gdk.test:3000//api/v4/virtual_registries/container/upstreams/1/cache' \
--header 'PRIVATE-TOKEN: glpat-your-token-here'

The above cURL command will return a 204 No Content when successful. And the status of the upstream cache entries should now be set to pending_destruction:

upstream.reload.cache_entries.pluck(:status)
=> ["pending_destruction", "pending_destruction", "pending_destruction"]

Endpoint 2: `DELETE /virtual_registries/container/registries/:id/cache`

With this endpoint, we set all the cache entries of a registry (i.e. from all upstreams of the registry) for deletion. Before you run the cURL command below, you can inspect the current status of the upstreams:

registry = VirtualRegistries::Container::Registry.find(1)
registry.reload.upstreams.map(&:cache_entries).flatten.pluck(:status)
# => ["default", "default", "default", "default"]

And then you can call the endpoint with:

curl --location --request DELETE 'http://gdk.test:3000//api/v4/virtual_registries/container/registries/1/cache' \
--header 'PRIVATE-TOKEN: glpat-your-token-here'

The above cURL command will return a 204 No Content when successful. And the status of the upstream cache entries should now be set to pending_destruction:

registry.reload.upstreams.map(&:cache_entries).flatten.pluck(:status)
=> ["pending_destruction", "pending_destruction", "pending_destruction", "pending_destruction"]

MR acceptance checklist

Evaluate this MR against the MR acceptance checklist. It helps you analyze changes to reduce risks in quality, performance, reliability, security, and maintainability.

Related to #578680 (closed)

Add delete cache API for container virtual registry