Dragonfly — P2P Container Image Distribution for Kubernetes

Introduction

Dragonfly is a CNCF incubating project originally created at Alibaba to solve the problem of distributing container images efficiently across thousands of nodes. When hundreds of nodes pull the same image simultaneously, the registry becomes a bottleneck. Dragonfly uses peer-to-peer distribution so nodes share image layers with each other, dramatically reducing bandwidth at the source.

What Dragonfly Does

• Distributes container images via P2P to avoid registry bandwidth bottlenecks
• Splits downloads into pieces that peers exchange concurrently
• Provides a transparent proxy layer that integrates with containerd and Docker
• Supports preheating images into the P2P network before rollout
• Handles generic file distribution beyond container images

Architecture Overview

Dragonfly consists of a Manager (control plane for cluster and scheduler configuration), Schedulers (which decide how to split tasks and select optimal peers), Seed Peers (super nodes that fetch from the source registry and serve as initial seeds), and Dfdaemons (agents running on every node that participate in P2P exchange). Dfdaemons register with the Scheduler and advertise available pieces, forming a mesh that distributes data without overloading the origin.

Self-Hosting & Configuration

• Deploy via Helm chart into a dedicated namespace
• Configure container runtime (containerd/CRI-O) to proxy through Dragonfly
• Set up Seed Peers on nodes with good network connectivity to the registry
• Tune piece size and concurrent download limits for your network
• Use the Manager console for cluster-wide configuration and monitoring

Key Features

• P2P distribution reduces registry egress by up to 90% in large clusters
• Transparent integration with containerd, CRI-O, and Docker
• Image preheating API for pre-distributing images before deployments
• Multi-cluster support with cross-cluster P2P scheduling
• Built-in console for real-time task monitoring and diagnostics

Comparison with Similar Tools

• Spegel — simpler in-cluster P2P registry mirror, less feature-rich but easier to set up
• Kraken — Uber's P2P image distribution, focused on Docker and less actively maintained
• Harbor — container registry with replication but no P2P distribution
• Stargz Snapshotter — lazy-loading container images, complementary rather than competing

FAQ

Q: Does Dragonfly require changes to my container images? A: No. Dragonfly works transparently as a pull-through proxy. Your images and Dockerfiles remain unchanged.

Q: How does Dragonfly handle private registries? A: Dragonfly supports registry authentication passthrough. Configure credentials in the Dfdaemon, and it authenticates on behalf of the node.

Q: What happens if the Dragonfly Scheduler goes down? A: Nodes fall back to pulling directly from the registry. The Scheduler is not in the critical path for image pulls.

Q: Can Dragonfly distribute non-container files? A: Yes. Dragonfly provides a generic file distribution API for distributing any large file via P2P.

Sources

• https://github.com/dragonflyoss/dragonfly
• https://d7y.io/docs/