Spegel Setup and Usage

Introduction

In Kubernetes clusters, when services are frequently released or scaled, nodes usually pull images directly from remote image registries. This not only increases the load on the image registry but also makes it susceptible to rate limits from public registries like DockerHub, resulting in slow or even failed image pulls. Spegel is designed to solve these problems by caching images locally on nodes, accelerating image distribution, and improving cluster deployment efficiency.

However, Spegel currently only supports Containerd. If you are using Docker, you can ignore the following content.

Principle

Spegel deploys a local image cache proxy on each Kubernetes node, intercepting and caching images pulled by the node. When a node needs to pull an image, it first tries to get it from the local Spegel cache; if not available locally, it pulls from the remote registry and caches it locally. This way, when the same image is pulled again by the same or another node, it can be fetched directly from the local cache, greatly improving pull speed and reducing dependency and bandwidth consumption on external registries.

Spegel relies on Containerd’s image pulling mechanism. By configuring Containerd’s Registry Mirror, image requests are redirected to the local Spegel service, achieving transparent acceleration and caching.

Modify containerd Configuration

Spegel relies on containerd’s local image layer cache, so you need to ensure that discard_unpacked_layers is set to false. Edit /etc/containerd/config.toml and find the following field to modify:

[plugins."io.containerd.grpc.v1.cri".containerd]
   discard_unpacked_layers = false

For detailed configuration methods for different K8s distributions, refer to the official documentation:

https://spegel.dev/docs/getting-started/

Below is the script I use on EKS:

grep "discard_unpacked_layers" /etc/containerd/config.toml && \
sudo cp /etc/containerd/config.toml /etc/containerd/config.toml.bak && \
sudo sed -i 's/^\(\s*\)discard_unpacked_layers\s*=\s*true/\1discard_unpacked_layers = false/' /etc/containerd/config.toml && \
grep "discard_unpacked_layers" /etc/containerd/config.toml && \
sudo systemctl restart containerd

If the above modification fails, the Spegel container will not start successfully during deployment.

Deployment

Spegel is very easy to deploy. It is recommended to use Helm or Kustomize for one-click installation. The following is an example using Kustomization, directly showing the kustomization.yaml configuration:

helmCharts:
  - name: spegel
    repo: oci://ghcr.io/spegel-org/helm-charts
    releaseName: spegel
    namespace: spegel
    valuesFile: values.yaml

The default values.yaml usually does not need any modification.

https://github.com/spegel-org/spegel/blob/main/charts/spegel/values.yaml

Then use argocd to deploy.

Testing

You can create a pod and observe Spegel’s logs. When the cache is not present on the node, you will see a message like:

"err":"mirror with image component sha256:5fcf7ef29eb9819794924a97aba79c77c8810292cad53a90cbda7be1bd892d33 could not be found"

Then:

"OCI event","key":"sha256:5fcf7ef29eb9819794924a97aba79c77c8810292cad53a90cbda7be1bd892d33","type":"CREATE"

When the cache is present on the node, you will see:

"status":200,"method":"GET","latency":"107.376902ms","ip":"x.x.x.x","handler":"blob"

Feel free to follow my blog at www.bboy.app

Have Fun

Bboysoul's Blog