# mittwald/kube-httpcache architecture

> Architecture diagram of the GitHub repository mittwald/kube-httpcache, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-09-17). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/mittwald/kube-httpcache
- Repository: https://github.com/mittwald/kube-httpcache

## Overview

##### Project type and purpose
- This is a Kubernetes “controller” / caching side-car component written in Go that watches Kubernetes Services and Endpoints, generates Varnish VCL on‐the‐fly, and reloads a Varnish cache cluster.
- It also embeds a “signaller” HTTP sub-service for broadcasting PURGE/BAN requests to all Varnish nodes.
- It ships with a Helm chart, Docker images, and standard Kubernetes manifests (RBAC, StatefulSet, Service, ConfigMap, Secret).

##### File structure
- Top-level packaging & CI:
- build/ci – GoReleaser configurations
- build/package/docker – Dockerfiles for building the image
- chart/ – Helm chart (Chart.yaml, templates/, values.yaml)
- deploy/kubernetes/ – standalone RBAC YAML
- Core application code (cmd/ & pkg/):
- cmd/kube-httpcache – entry point (main.go) and flags.go
- pkg/watcher – watches Kubernetes Endpoints & ConfigMap watches
- pkg/controller – orchestrates template rendering
- pkg/signaller – HTTP server for PURGE/BAN broadcasts
- Tests & assets:
- test/ – example YAMLs for end-to-end tests
- assets/varnish.repo – packaging resource
- GitHub workflows, CONTRIBUTING, LICENSE, SECURITY, README describe build/test/release and developer guidance.

1. Kubernetes API Server (control plane)
2. kube-httpcache Controller (Pod, single container binary)
- Watcher module
- Controller module (VCL template renderer)
- Signaller HTTP server
3. ConfigMap (VCL template) + Secret (Varnish admin secret)
4. Varnish Cache instances (StatefulSet)
5. Application Service & Pods (backend)
6. Ingress (or Ingress Controller)
7. Client (end user or external service making HTTP requests)
- Client → Ingress → Service “cache-service” → Varnish Pods (HTTP traffic)
- Controller Pod → (watches) Kubernetes API Server for:
- Frontend Service Endpoints
- Backend Service Endpoints
- ConfigMap changes
- Controller module → (renders) VCL template from ConfigMap + endpoint data → loads into Varnish via admin port
- Signaller HTTP server → receives PURGE/BAN requests → fetches current Varnish Pod IPs → issues HTTP PURGE/BAN to each pod
c. Architectural patterns & design principles:
- Operator-style pattern: separation of control plane (watchers + template rendering) vs. data plane (Varnish cache pods)
- Modular Go packages: watcher, controller, signaller
- StatefulSet for stable network identities (required for self-routed Varnish cluster)
- ConfigMap driven configuration for declarative VCL
- Helm chart for templated deployment
d. Key technologies/libraries:
- Go & client-go (Kubernetes API)
- Varnish Cache (vcl 4.0)
- Go templates for VCL
- Docker & GoReleaser for image builds
- Helm for deployment
- Kubernetes primitives: StatefulSet, Service, ConfigMap, Secret, RBAC, Ingress

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "Build & Deployment Artifacts"
        CI["CI Configs"]:::build
        Docker["Docker Build"]:::build
        Helm["Helm Chart"]:::build
        RBACManifest["RBAC Manifest"]:::build
        Assets["Varnish Packaging Resource"]:::build
        TestExamples["E2E Test Examples"]:::build
    end

    subgraph "Control Plane"
        ControllerPod["kube-httpcache Controller Pod"]:::control
        subgraph "Controller Components"
            Watcher["Watcher Module"]:::control
            Manager["Controller Module"]:::control
            Signaller["Signaller HTTP Sub-service"]:::control
        end
    end

    subgraph "Kubernetes Cluster"
        API["Kubernetes API Server"]:::infra
        ConfigMap["ConfigMap (VCL Template)"]:::config
        Secret["Secret (Admin Secret)"]:::config

        subgraph "Data Plane"
            subgraph "Cache Cluster"
                V1["Varnish Pod #1"]:::data
                V2["Varnish Pod #2"]:::data
            end
            ServiceCache["cache-service (Service)"]:::infra
            subgraph "App Backend"
                App1["App Pod #1"]:::data
                App2["App Pod #2"]:::data
            end
            Ingress["Ingress"]:::infra
        end
    end

    Client["Client"]:::external

    Client -->|"HTTP Request"| Ingress
    Ingress -->|"Route to cache-service"| ServiceCache
    ServiceCache --> V1
    ServiceCache --> V2

    ControllerPod -->|"Watch Endpoints/ConfigMap"| API
    API --> ConfigMap
    API --> ServiceCache
    API --> App1
    API --> App2

    Watcher -->|"Watch K8s Resources"| API
    Manager -->|"Render & Load VCL"| V1
    Manager -->|"Render & Load VCL"| V2

    Client -->|"PURGE/BAN Request"| Signaller
    Signaller -->|"PURGE/BAN Broadcast"| V1
    Signaller -->|"PURGE/BAN Broadcast"| V2

    click ControllerPod "https://github.com/mittwald/kube-httpcache/blob/master/cmd/kube-httpcache/main.go"
    click Watcher "https://github.com/mittwald/kube-httpcache/tree/master/pkg/watcher/"
    click Manager "https://github.com/mittwald/kube-httpcache/tree/master/pkg/controller/"
    click Signaller "https://github.com/mittwald/kube-httpcache/tree/master/pkg/signaller/"
    click Helm "https://github.com/mittwald/kube-httpcache/tree/master/chart/"
    click RBACManifest "https://github.com/mittwald/kube-httpcache/blob/master/deploy/kubernetes/rbac.yaml"
    click Docker "https://github.com/mittwald/kube-httpcache/tree/master/build/package/docker/"
    click CI "https://github.com/mittwald/kube-httpcache/tree/master/build/ci/"
    click Assets "https://github.com/mittwald/kube-httpcache/blob/master/assets/varnish.repo"
    click TestExamples "https://github.com/mittwald/kube-httpcache/tree/master/test/"

    classDef control fill:#D0E6FF,stroke:#0066CC,color:#000;
    classDef data fill:#DFFFE0,stroke:#339933,color:#000;
    classDef infra fill:#EEEEEE,stroke:#AAAAAA,color:#000;
    classDef config fill:#FFF2CC,stroke:#EECC00,color:#000;
    classDef build fill:#F2F2F2,stroke:#CCCCCC,color:#666;
    classDef external fill:#F9D5DC,stroke:#CC3366,color:#000;
```
