How K3s Embedded Registry Enables Offline Image Sharing in Kubernetes Clusters

What Is an Embedded Container Image?

K3s integrates the open‑source Spegel project to provide an embedded OCI registry that allows nodes in a cluster to share container images directly over a peer‑to‑peer network. When a node already has an image, other nodes can pull it from that node without contacting an external registry.

Typical Scenarios

Offline or internal network : Nodes operate without public internet access and rely on internal image distribution.

Efficient image distribution : Reduces external bandwidth usage and speeds up image pulls.

Distributed environments : Nodes in different geographic locations can share images, lowering latency.

Example Scenario

Consider a three‑node K3s cluster (A, B, C). Node A already contains the image ksd.test.com/ksd/nginx:1.27, while nodes B and C lack the image and cannot reach the public internet.

Enable the embedded registry : Add embedded-registry: true to each node’s configuration file or start K3s with the --embedded-registry flag. All nodes will launch a local OCI registry and enable P2P sharing.

Configure the registry : Edit each node’s registries.yaml to define the mirror, e.g.:

mirrors:
  ksd.test.com:

Image pull : When nodes B and C request ksd.test.com/ksd/nginx:1.27, they first attempt to retrieve it from the local registry on node A via the P2P network. If node A holds the image, the pull succeeds without external network access.

Image sharing : This mechanism keeps images synchronized across nodes regardless of internet connectivity.

Step‑by‑Step Enabling Procedure

Configure K3s start parameters or config file

Start K3s with the --embedded-registry flag.

Or add embedded-registry: true to /etc/rancher/k3s/config.yaml.

Configure registries.yaml Ensure the file contains the required mirrors. Example configuration:

mirrors:
  ksd.test.com:

Network requirements All nodes must be able to reach each other’s internal TCP ports (default 5001 and 6443) so that the P2P image sharing can operate.

Security and Caveats

The feature assumes equal trust among cluster nodes. In environments with strict security policies, enable it only after evaluating trust boundaries and consider using image digests instead of tags to verify integrity.

Conclusion

K3s’s embedded container image capability reduces reliance on external registries, accelerates image distribution, and improves reliability for offline, bandwidth‑constrained, or geographically distributed Kubernetes clusters.