Purge and BAN the cache¶

This guide shows how to send cache-invalidation requests to a running VinylCache cluster.

Find the proxy endpoint¶

The operator exposes an invalidation proxy on port 8090 of the operator Service:

kubectl get svc -n cloud-vinyl-system cloud-vinyl
# NAME           TYPE        CLUSTER-IP    EXTERNAL-IP   PORT(S)
# cloud-vinyl    ClusterIP   10.0.0.1      <none>        8080/TCP,8090/TCP

For in-cluster requests use http://cloud-vinyl.cloud-vinyl-system.svc:8090.

PURGE a URL¶

curl -X PURGE http://cloud-vinyl.cloud-vinyl-system.svc:8090/path/to/resource

Response:

{"status":"ok","total":3,"succeeded":3,"results":[...]}

status is one of:

ok — all pods purged successfully.
partial — some pods failed (cache is partially stale).
failed — all pods failed.

BAN by expression¶

Two routes are available, with different semantics. Pick based on where your client sits and how much control you want over the validation step.

Route 1 — via the operator invalidation proxy (recommended for most callers)¶

The proxy accepts BAN as either a JSON POST or the native BAN HTTP method, validates the expression, and forwards to varnishadm ban on every pod via the agent:

# JSON form:
curl -X POST http://cloud-vinyl.cloud-vinyl-system.svc:8090/ban \
  -H "Content-Type: application/json" \
  -d '{"expression": "obj.http.X-Cache-Tag ~ \"product-42\""}'

# Native BAN HTTP method (equivalent):
curl -X BAN http://cloud-vinyl.cloud-vinyl-system.svc:8090/ \
  -H "X-Ban-Expression: obj.http.X-Cache-Tag ~ \"product-42\""

The proxy enforces: only obj.http.* expressions on the left-hand side; wildcard-only expressions (. / .*) are rejected. This validation is a defence-in-depth layer on top of Varnish’s own ban-expression compiler.

Does not require any opt-in on the VinylCache spec.

Route 2 — directly to Varnish (BAN method on the traffic port)¶

Available from v0.4.2 onwards. Requires opt-in on the VinylCache:

spec:
  invalidation:
    ban:
      enabled: true
      allowedSources:
        - "10.0.0.0/8"   # CIDRs permitted to send BAN directly

Then send the BAN with the X-Vinyl-Ban header:

curl -X BAN http://my-cache-traffic.my-namespace.svc:8080/ \
  -H 'X-Vinyl-Ban: obj.http.x-url ~ "^/news/"'

Responses:

200 Banned — expression compiled and registered.
400 Missing X-Vinyl-Ban header — header absent.
400 Invalid ban expression: <compiler message> — std.ban() rejected the expression; the compiler error is returned verbatim for diagnosis.
403 Forbidden — client IP is not in vinyl_ban_allowed (the localhost + operator IP + ban.allowedSources).

Use obj.http.x-url / obj.http.x-host rather than req.* — only the former can be processed by the Varnish ban lurker, so req.* bans accumulate and degrade performance O(n*m). The operator emits these helper headers on every cached object when ban.enabled: true is set (or when xkey is enabled).

Security: any client inside vinyl_ban_allowed can invalidate the entire cache with an arbitrary expression. Scope ban.allowedSources tightly.

Purge by xkey (surrogate key)¶

Requires spec.invalidation.xkey to be enabled in the VinylCache.

curl -X POST http://cloud-vinyl.cloud-vinyl-system.svc:8090/purge/xkey \
  -H "Content-Type: application/json" \
  -d '{"keys": ["product-42", "category-home"]}'

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