VinylCache Spec Reference

VinylCache is the central custom resource managed by cloud-vinyl.

API group: vinyl.bluedynamics.eu/v1alpha1 Kind: VinylCache Scope: Namespaced

Spec fields

Top-level

Field	Type	Required	Description
replicas	integer	yes	Number of Vinyl Cache pods in the StatefulSet.
backends	list	yes	One or more backend services.
director	object	no	Director configuration (defaults: type: shard).
cluster	object	no	Clustering / peer-routing configuration.
varnishParameters	object	no	Runtime parameters passed to varnishd via -p flags. See the varnishParameters section below.
esi	object	no	Edge Side Includes (ESI) processing. See the esi section below.
invalidation	object	no	Cache invalidation configuration.
debounce.duration	duration	no	Wait after last change before VCL push (default: 1s).
retry.maxAttempts	integer	no	Maximum VCL push retry attempts (default: 3).
retry.backoffBase	duration	no	Initial retry backoff (default: 5s).
retry.backoffMax	duration	no	Maximum retry backoff (default: 5m).
proxyProtocol.enabled	boolean	no	Enable PROXY protocol v2 on port 8081.
proxyProtocol.port	integer	no	PROXY protocol port (default: 8081 when enabled).
service.annotations	object	no	Annotations on the traffic Service.
pod.labels	object	no	Extra labels on Vinyl Cache pods.
pod.volumes	list	no	Additional pod volumes appended to operator-managed defaults. Reserved names rejected by webhook. See SSD-backed storage how-to.
pod.volumeMounts	list	no	Additional mounts on the varnish container. Each name must reference a spec.pod.volumes entry or a spec.volumeClaimTemplates claim name. Reserved mount paths rejected by webhook.
volumeClaimTemplates	list	no	StatefulSet-native per-replica PVC templates. Reference the claim name from spec.pod.volumeMounts.

backends

Each entry in spec.backends defines an upstream service:

Field	Type	Required	Description
name	string	yes	Unique backend identifier (used in VCL).
serviceRef.name	string	yes	Kubernetes Service name in the same namespace.
port	integer	no	Overrides the Service port; defaults to the Service’s first port.
connectTimeout	duration	no	Connection timeout (default: 1s).
firstByteTimeout	duration	no	Time-to-first-byte timeout (default: 60s).
betweenBytesTimeout	duration	no	Between-bytes timeout (default: 60s).
maxConnections	integer	no	Maximum concurrent connections to this backend.
healthCheck.url	string	no	Health probe URL (e.g. /healthz).
healthCheck.interval	duration	no	Health probe interval (default: 5s).
healthCheck.timeout	duration	no	Health probe timeout (default: 1s).
healthCheck.threshold	integer	no	Consecutive successes required to mark healthy.
healthCheck.window	integer	no	Rolling window for health evaluation.

backends[].director

Per-backend director override. If unset, the generator emits a shard director with default parameters, grouping all resolved per-pod backends for this serviceRef.

Field	Type	Required	Description
type	enum	no	One of shard, round_robin, random, hash, fallback. Defaults to shard.
shard.warmup	float	no	0.0–1.0; share of traffic sent to alternate backend to warm its cache. Default 0.1.
shard.rampup	duration	no	Ramp-up window after adding a backend. Default 30s.
shard.by	enum	no	URL (default and only supported value). Request-time selector passed to <backend>.backend(by=...).
shard.healthy	enum	no	CHOSEN (default) or ALL. Which backends must be healthy for the director to route.
hash.header	string	no	Header used as hash key for the hash director.

See the per-backend directors how-to for when to override each type.

director

Field	Type	Default	Description
type	string	shard	Director type. Currently only shard is supported.
shard.warmup	float	0.1	Fraction of requests sent to alternate backend to pre-populate its cache.
shard.rampup	duration	30s	Traffic throttle duration for newly healthy backends.
shard.by	string	URL	Shard key source. URL is the only supported value; HASH was removed (it hashed req.hash, which cluster routing in vcl_recv never populates — see #92).
shard.healthy	string	CHOSEN	Health evaluation strategy (CHOSEN, ALL).

Note on shard.by and shard.healthy:

• Cluster-peer director (when cluster.enabled: true): honored automatically — the operator emits <director>.backend(by=<by>, healthy=<healthy>) in vcl_recv.

• Per-backend directors: still request-time arguments. The CRD accepts the fields but you must use them in your own VCL snippet, e.g. set req.backend_hint = plone.backend(by=URL, healthy=CHOSEN);.

cluster

Field	Type	Default	Description
enabled	boolean	false	Enable cluster peer routing between pods.
peerRouting.type	string	shard	Director type for peer-to-peer routing.

varnishParameters

A map[string]string. Each entry becomes one -p flag on varnishd: the key must be a bare varnishd parameter name (lowercase letters, digits, and underscores, starting with a letter — the admission webhook rejects anything else, including padding whitespace or uppercase), and the value is passed through unchanged. For example:

varnishParameters:
  thread_pool_min: "100"
  thread_pool_max: "1000"
  feature: "+esi_disable_xml_check"

renders as -p feature=+esi_disable_xml_check -p thread_pool_max=1000 -p thread_pool_min=100 on the varnish container — note the args come out sorted by key (feature < thread_pool_max < thread_pool_min), not in the order they were written in YAML, so the pod template does not churn between reconciles for the same params.

Two parameters are blocked by the admission webhook regardless of value, because they allow arbitrary code execution at VCL-compile time: vcc_allow_inline_c and cc_command.

ESI (Edge Side Includes) processing is not controlled through this map — see the esi section below. varnishParameters’ feature key is still relevant alongside it, for the one real varnishd feature bit ESI sometimes needs (esi_disable_xml_check); see that section for when and why.

esi

Field	Type	Default	Description
enabled	boolean	false	Enable Edge Side Includes (ESI) processing.

esi:
  enabled: true

Setting esi.enabled: true makes the generated VCL set beresp.do_esi = true whenever a backend response carries Surrogate-Control: content="ESI/1.0". ESI is core varnishd functionality, not a VMOD, and — unlike most varnishd behaviour toggles — it is not controlled by any varnishParameters/-p feature=... flag either: real varnishd has no esi feature bit, so passing {"feature": "+esi"} (an earlier, now-removed convention) crashes varnishd outright with Unknown feature bit (+esi) rather than enabling anything. esi.enabled replaces that convention and carries no such risk — it never reaches varnishd’s argv at all.

If response bodies don’t reliably start with < (varnishd’s ESI implementation sniffs the body to decide whether to scan it for <esi:...> tags), also set the real varnishd feature token alongside it:

esi:
  enabled: true
varnishParameters:
  feature: "+esi_disable_xml_check"

invalidation

Field	Type	Default	Description
purge.soft	boolean	true	Use soft purge (stale-while-revalidate).
purge.allowedSources	list	[]	CIDRs permitted to send PURGE. 127.0.0.1 and the operator pod IP are always included.
xkey	object	nil	Xkey (surrogate key) configuration. When set, vmod_xkey is loaded.
xkey.softPurge	boolean	true	Use soft purge for xkey invalidation.
ban.enabled	boolean	false	When true, emit a vinyl_ban_allowed ACL and a BAN handler in vcl_recv that dispatches std.ban(req.http.X-Vinyl-Ban). Also emits ban-lurker-friendly x-url/x-host headers on stored objects.
ban.allowedSources	list	[]	CIDRs permitted to send BAN (in addition to 127.0.0.1 and the operator pod IP).
ban.rateLimitPerMinute	integer	0	Inert in v0.4.2 — field is accepted but not enforced; rate-limiting is tracked as follow-up work.

Note on BAN security: any client whose source IP is in vinyl_ban_allowed can invalidate the entire cache with an arbitrary ban expression. Scope ban.allowedSources tightly to trusted callers only. Ban expressions should prefer obj.http.x-url / obj.http.x-host over req.* fields — only the former can be processed by the ban lurker, so req.* bans accumulate without being compacted.

Clients send BAN requests like:

curl -X BAN -H 'X-Vinyl-Ban: obj.http.x-url ~ "^/news/"' http://varnish.svc/

Status fields

Field	Type	Description
phase	string	Pending, Ready, Degraded, or Error.
readyReplicas	string	<ready>/<total> replica count string.
vclHash	string	SHA-256 hash of the currently active VCL.
conditions	list	Standard Kubernetes conditions (Ready, VCLSynced).

Example

apiVersion: vinyl.bluedynamics.eu/v1alpha1
kind: VinylCache
metadata:
  name: my-cache
  namespace: production
spec:
  replicas: 3
  backends:
    - name: api
      serviceRef:
        name: api-service
      port: 8080
      probe:
        url: /healthz
        interval: 5s
        threshold: 3
  director:
    type: shard
    shard:
      warmup: 0.1
      rampup: 30s
  cluster:
    enabled: true
  invalidation:
    purge:
      soft: true
    xkey:
      softPurge: true
  debounce:
    duration: 1s
  retry:
    maxAttempts: 3
    backoffBase: 5s
    backoffMax: 5m