Cached objects normally expire on their own, on the lifetime their resource type gives them. A package is immutable and is kept for a hundred years, so waiting one out is not an option when an artifact has to go now: a version that was yanked upstream, an image rebuilt under a tag that was already fetched, or a cached authorization that outlived the access it recorded.
The Virtual Registry invalidates by tag. Every cached object is stored under a handful of tags, and a PURGE request naming a tag drops every object carrying it.
Send PURGE to /purgez with the tags in a Cache-Tags header, separated by commas:
curl -X PURGE -H 'Cache-Tags: registry_npmjs' http://127.0.0.1/purgez
Invalidated 1483 objects
The response names how many objects were dropped, which is 0 when nothing carried the tag. A request with no Cache-Tags header returns 400.
Only 127.0.0.1 and ::1 may purge. Anything else gets 403, so a purge has to be issued on the node itself, over loopback. This is not configurable.
A purge reaches one cache. In a cluster every node holds its own copy of what it has fetched, so invalidating everywhere means issuing the same request on every node.
| Tag | Objects carrying it |
|---|---|
everything |
Every cached object. |
registry_<name> |
Everything fetched through the virtual registry of that name, as named by name. |
type_<package type> |
Everything of one package type, for example type_npm or type_oci. |
resource_<resource type> |
Everything of one resource type: resource_manifest, resource_package or resource_other. |
auth |
Cached preflight authorizations, and nothing else. |
Naming several tags in one request invalidates the union of them, not the intersection: Cache-Tags: type_npm, type_pypi drops the npm objects and the PyPI objects. Narrowing to the npm objects of one registry takes a purge of registry_<name> and accepts that the other package types in that registry go with it.
Cached authorizations are the exception to the pattern. A preflight is stored under everything and auth alone, with no registry or package type of its own, so auth is the tag that clears them after an upstream permission change. It is worth clearing on its own rather than as part of a wider purge: dropping the authorizations without dropping the artifacts makes the next request to each artifact re-check access, at the cost of one preflight, and leaves the cached content in place.
When the Artifact Firewall reloads its rulesets, cached manifests were filtered against the rules that were loaded before, and are now wrong. The Supervisor points the firewall’s reload webhook at /purgez with Cache-Tags: resource_manifest, so every filtered manifest is dropped and re-fetched against the new rules, while cached packages stay where they are.
This is why webhook is not available to configure when the firewall runs behind the Virtual Registry: the setting is already in use.