# Persistent Buildkit Cache for CI

Dedicated, long-lived buildkit daemon that persists its layer cache on a
single-replica Longhorn PVC so repeated CI image builds reuse cache instead of
re-building every time. This manifest set is **ported verbatim from
`armistace/wedding-photos`** — verified live.

## Why single-replica Longhorn (not the default SC)

The buildx **kubernetes driver's PVC option creates the volume with NO
`storageClassName`** — it falls back to the cluster default SC, which here is
`longhorn` at **3 replicas**. That would triple every cache byte across
disk-constrained nodes. So this uses a dedicated `buildkit-single-1r` SC
(`numberOfReplicas: 1`, `dataLocality: best-effort`): the cache is **1× on
disk** and only replicates if the hosting node actually dies.

## Components

| Path | Purpose |
|---|---|
| `ci/buildkit/01-storageclass.yaml` | `buildkit-single-1r` SC (1 replica, best-effort locality) |
| `ci/buildkit/02-statefulset.yaml` | `buildkit` StatefulSet, pod schedules off the control plane, listens `tcp://0.0.0.0:1234`, 10Gi cache PVC |
| `ci/buildkit/03-service.yaml` | ClusterIP `buildkit.gitea-runner.svc:1234` |
| `ci/buildkit/04-networkpolicy.yaml` | restrict buildkit to the gitea-runner namespace only |
| `.gitea/workflows/build_push.yml` | `setup-buildx-action` → `driver: remote`, `endpoint=tcp://buildkit.gitea-runner.svc:1234` |

> **Ops tooling is NOT in this repo.** The disk watchdog + revert/restore
> scripts live on the control machine (`~/.hermes/scripts/buildkit-cache-monitor.sh`,
> `buildkit-re-enable.sh`) and run from the `buildkit-disk-monitor` cron. They are
> homelab ops, not app code.

## Apply (one-time, per cluster — NOT per repo)

```bash
kubectl apply -f ci/buildkit/01-storageclass.yaml
kubectl apply -f ci/buildkit/02-statefulset.yaml
kubectl apply -f ci/buildkit/03-service.yaml
kubectl apply -f ci/buildkit/04-networkpolicy.yaml
kubectl -n gitea-runner rollout status statefulset/buildkit --timeout=180s
```

Buildkit is a **cluster-wide shared resource** — it should be installed once, not
once per repo. If your repo doesn't own the cluster, coordinate with whoever
does (it lives in the `gitea-runner` namespace and only needs applying once).