Explanation

Operator Architecture

Type: Explanation (Understanding-oriented)

Why an Operator Instead of a Sidecar?

The previous approach (mittwald/kube-httpcache) deploys Varnish as a Helm chart per application — each deployment gets its own Varnish Deployment managed by Helm. This has limitations:

  • No centralized VCL management — each deployment manages its own VCL template via Helm values

  • No structured VCL generation — VCL is passed as a raw template string with Go template variables

  • Limited cache invalidation — no built-in PURGE/BAN proxy; requires manual configuration

  • No reconciliation — Helm doesn’t watch or heal Varnish state after initial deployment

Cloud-vinyl uses the Kubernetes operator pattern with a reconciliation loop:

  • VinylCache CRD — declarative desired state for Varnish clusters

  • Controller — watches VinylCache resources and reconciles actual state

  • Agent — runs alongside each Varnish pod, receives VCL updates and exposes metrics

  • Invalidation proxy — built into the operator, handles PURGE/BAN/xkey requests

Components

Operator (controller-manager)

The central controller runs in cloud-vinyl-system namespace. It:

  1. Watches VinylCache resources across all namespaces

  2. Creates/updates StatefulSets, Services, and NetworkPolicies

  3. Generates VCL from structured config (backends, directors, snippets)

  4. Pushes VCL to agents via HTTP

  5. Reports status conditions (Ready, VCLSynced, BackendsAvailable)

Vinyl Agent

A sidecar container in each Varnish pod that:

  1. Receives VCL configuration from the operator via HTTP

  2. Loads VCL into the running Varnish instance via admin CLI

  3. Exposes Prometheus metrics on port 9090

VCL Lifecycle

config.yaml → Operator generates VCL → Agent receives VCL → Varnish loads VCL
                                                              ↓
                                                        Status: VCLSynced

The operator generates VCL from:

  • Structured config: Backends, directors, and cache rules from the VinylCache spec

  • Snippet hooks: User-provided VCL fragments injected at specific subroutines

  • Full override: Complete VCL template when full control is needed

Cache Invalidation

The operator includes a built-in invalidation proxy that:

  1. Accepts PURGE, BAN, and xkey requests on port 8090

  2. Fans out invalidation to all Varnish pods in the cluster

  3. Returns aggregate response

This integrates with Plone’s plone.cachepurging via the xkey module for surrogate-key-based invalidation.

Deployment in kup6s

Cloud-vinyl follows the standard dp-infra operator pattern:

  1. Namespace (sync-wave 0) — cloud-vinyl-system

  2. HelmChart (sync-wave 1) — K3S HelmChart CRD deploys the cloud-vinyl Helm chart

The Helm chart installs:

  • Operator Deployment with RBAC

  • VinylCache CRD

  • Validating and mutating webhooks (TLS via cert-manager)

  • Optional ServiceMonitor and PrometheusRule

Security

  • All containers run as non-root (UID 65532)

  • Read-only root filesystems

  • No capabilities (drop ALL)

  • Admission webhooks block unsafe Varnish parameters (vcc_allow_inline_c, cc_command)

  • Agent authentication via Bearer token