Spegel

Spegel, mirror in Swedish, is a stateless cluster local OCI registry mirror.

Note: Spegel is a project with an evolving API and no guaranteed support. Assistance is provided on a best-effort basis by the developers. We focus on the home lab and individual contributor use case.

---

This Fork

This fork originated from upstream Spegel at commit 95c6c77. It keeps Spegel's stateless, cluster-local OCI mirror and P2P distribution model, and extends it with workload-scoped image delivery. It is therefore not a drop-in description of the current upstream project: this fork adds APIs and a companion deployment that are maintained here.

What this fork adds

• A companion admission webhook that can rewrite selected new Pod image references to a node-loopback Spegel listener, so the pull is explicitly routed through the local Spegel instance.
• Cluster-scoped ImageRewriteRule, RegistryMirror, and OriginPolicy APIs for selecting workloads, mapping canonical registries to mirror endpoints, and controlling origin access.
• A policy controller that validates routes, publishes desired and active policy projections, and only permits rewriting after the projection has converged across the Spegel DaemonSet.
• A local-registry mode (localhost:<port>/spegel/v1/...) and the integrated spegel-stack Helm chart, including configurable webhook scheduling for multi-architecture clusters.
• P2P data-plane hardening: peers advertise reachable node addresses, and strict P2P-only validation can prove a cache hit plus a libp2p resolution without relying on origin fallback.

What the new project is

In short, this is Spegel with policy-controlled, per-workload local image routing. A matching Pod is rewritten to its node's loopback registry; Spegel then serves the image from local content, from a peer through P2P, or from an explicitly permitted mirror/origin route. This makes the image-delivery decision visible in the Pod specification while retaining Spegel's cluster-local cache and peer-to-peer distribution.

Features

Spegel is for you if you are looking to do any of the following.

• Locally cache images from external registries with no explicit configuration.
• Avoid cluster failure during external registry downtime.
• Improve image pull speed and pod startup time by pulling images from the local cache first.
• Avoid rate-limiting when pulling images from external registries (e.g. Docker Hub).
• Decrease egressing traffic outside of the clusters network.
• Increase image pull efficiency in edge node deployments.

Getting Started

Read the getting started guide to deploy Spegel. For a repository-versioned installation, deployment, validation, and removal workflow, see the installation, deployment, and use manual.

The webhook/ Go module is repository-internal: it is built and tested together with the root module through the checked-in go.work. It is not maintained as an independently versioned Go library; consume the released webhook image and spegel-stack Chart instead.

Acknowledgements

Spegel was initially developed at Xenit AB.