Cache Invalidation#

cloud-vinyl supports three invalidation mechanisms, all broadcast to every pod in the cluster.

PURGE (object-level)#

A standard HTTP PURGE request removes a single cached object by URL. Varnish must have return(purge) in vcl_recv for the PURGE method (generated automatically).

Soft purge (default, spec.invalidation.purge.soft: true) marks objects as stale instead of removing them. Subsequent requests revalidate in the background (stale-while-revalidate). This prevents cache stampedes on busy endpoints.

Send a purge via the operator proxy:

PURGE http://<operator-svc>:8090/path/to/resource

BAN (expression-based)#

Bans invalidate sets of objects matching a VCL expression. Two routes are available — they differ in where the expression is validated and in how the ACL is enforced.

Via the operator invalidation proxy (default, always available)#

The proxy listens on port 8090 of the operator Service, validates the expression (only obj.http.* LHS; no wildcard-only), and forwards it to every pod via vinyl-agent POST /ban → varnishadm ban <expr>:

POST http://<operator-svc>:8090/ban
Content-Type: application/json

{"expression": "obj.http.X-Cache-Tag ~ \"product-42\""}

Equivalent as native BAN HTTP method with the X-Ban-Expression header:

BAN http://<operator-svc>:8090/
X-Ban-Expression: obj.http.X-Cache-Tag ~ "product-42"

No opt-in needed. Proxy-side ACL enforcement is currently advisory (see “ACLs” below).

Directly to Varnish (BAN method on the traffic port)#

From v0.4.2, VinylCache can expose a BAN handler directly in VCL, bypassing the operator proxy:

spec:
  invalidation:
    ban:
      enabled: true
      allowedSources:
        - "10.0.0.0/8"

The generator then emits a vinyl_ban_allowed ACL (localhost + operator pod IP + allowedSources) plus a vcl_recv BAN handler that calls std.ban(req.http.X-Vinyl-Ban):

BAN http://<cache-traffic-svc>:8080/
X-Vinyl-Ban: obj.http.x-url ~ "^/news/"

On malformed expressions the handler returns 400 Invalid ban expression: <std.ban_error()> rather than silently succeeding. When the header is missing, 400 Missing X-Vinyl-Ban header. Unauthorised source → 403 Forbidden.

Use obj.http.x-url / obj.http.x-host instead of req.* so the ban lurker can compact bans (req.* bans accumulate O(n*m)). The operator emits beresp.http.x-url / beresp.http.x-host on every cached object when ban.enabled: true is set (or xkey is enabled).

Xkey (surrogate-key)#

Xkey (also called surrogate keys or cache tags) allows grouping objects under arbitrary string keys. When the cached response includes an Xkey: key1 key2 header, all objects with that key can be purged with a single request.

POST http://<operator-svc>:8090/purge/xkey
Content-Type: application/json

{"keys": ["product-42", "category-home"]}

The operator issues one PURGE with X-Xkey-Purge: <key> per key to every pod.

Xkey requires the vmod_xkey Varnish module. Enable it in the spec:

spec:
  invalidation:
    xkey:
      softPurge: true  # default

ACLs#

There are two layers of access control, enforced at different points:

  • Proxy-side (spec.invalidation.purge.allowedSources, spec.invalidation.ban.allowedSources): the operator’s invalidation proxy checks the source CIDR before forwarding to pods. By default all sources are allowed — scope tightly in production.

  • Varnish-side (new in v0.4.2): the generated VCL contains vinyl_purge_allowed (always) and vinyl_ban_allowed (when ban.enabled: true). Both include 127.0.0.1 and the operator pod IP automatically; allowedSources CIDRs from the spec are appended. This is the ACL enforced in vcl_recv against the BAN/PURGE method coming directly to the traffic port.

In the common deployment — clients send PURGE/BAN to the proxy, the proxy forwards to Varnish — the operator’s pod IP is the only source Varnish ever sees, so the Varnish-side ACL is effectively a safety net. When direct-to-Varnish traffic is enabled, both layers apply.