# Dragonfly: P2P image and artifact distribution for Kubernetes clusters

> Dragonfly is a CNCF graduated project that turns registry pulls into peer-to-peer transfers inside a cluster, with an optional content-addressable filesystem for faster OCI container launch. It is worth adopting when many nodes pull the same large images at once, and unnecessary when they do not.

**dragonflyoss/dragonfly** — Delivers efficient, stable, and secure data distribution and acceleration powered by P2P technology, with an optional content‑addressable filesystem that accelerates OCI container launch.

- Repository: https://github.com/dragonflyoss/dragonfly
- Website: https://d7y.io
- Stars: 3,339 · Forks: 430
- Language: Go
- License: Apache-2.0
- Published: 2026-09-24 · Updated: 2026-09-24 · Language: en
- Canonical page: https://hysenlabs.com/projects/dragonflyoss-dragonfly

## The problem Dragonfly targets: repeated pulls of the same bytes

A Kubernetes cluster that scales out pulls the same container image from the same registry on every node. The registry becomes the choke point: bandwidth is consumed N times for N nodes, and pull latency grows with cluster size. Dragonfly addresses that by making peers serve each other. The README describes the project as delivering "efficient, stable, and secure data distribution and acceleration powered by P2P technology", and it lists the payloads it cares about: files, container images, OCI artifacts, AI/ML models, caches, logs and dependencies.

The audience is infrastructure teams running large clusters or fleets that share artifacts: platform engineers operating internal registries, ML teams shipping multi-gigabyte model files, and CI systems that fan the same image out to hundreds of runners. It is a cluster-level component, not a library you drop into an application. If your workloads pull small, distinct images, the peer layer adds moving parts without removing a bottleneck.

## How the P2P data path and the scheduler fit together

The repository layout shows the architecture directly. There are separate top-level directories for scheduler/, manager/, client, cmd/, api/, pkg/, internal/ and deploy/. The Go module path is d7y.io/dragonfly/v2, and the dependency list includes gRPC middleware, Prometheus client libraries, Casbin for authorization, GORM with MySQL and Redis adapters, and gin for HTTP services. That tells you the shape: a scheduler that coordinates peers, a manager that holds the control-plane state and API, and clients on nodes that participate in transfers.

The manager is the administrative surface. Its dependencies (Casbin, gorm-adapter, JWT via gin-jwt, MySQL driver, Redis cache) indicate it stores configuration and state in a database, exposes a REST API, and authenticates callers. The scheduler coordinates which peer serves which piece. The optional content-addressable filesystem mentioned in the README is the second mechanism: instead of pulling a whole image layer, the runtime fetches chunks on demand, which changes the launch profile of OCI containers. The README does not spell out the on-the-wire protocol in the excerpt available, so treat the scheduler-to-peer coordination as something to read up on in the full documentation at d7y.io before designing around it.

## Building Dragonfly from source and what the Makefile gives you

The README does not contain install commands. It points to the full documentation at d7y.io, and the repository carries a deploy/ directory plus an Artifact Hub listing referenced by the README badge. What the repository does document is how the project builds its own container images, through targets in the Makefile. The top-level target builds both control-plane images:

```bash
make docker-build
```

The Makefile defines that target as running docker-build-scheduler and docker-build-manager, each of which calls a script under hack/:

```bash
./hack/docker-build.sh scheduler
./hack/docker-build.sh manager
```

There is a matching pair for publishing, docker-push, which depends on the build targets and runs hack/docker-push.sh for each component. The Makefile also sets GIT_COMMIT and GIT_COMMIT_LONG from git rev-parse, so images built this way carry the commit they came from. For a cluster install rather than a local build, the README points at d7y.io; the README does not name a chart or a namespace, so get those from the documentation before running anything. The project publishes SBOMs with every release as GitHub release assets, which is worth pulling alongside whatever you deploy if your supply-chain process requires it.

## Where Dragonfly is the wrong tool

Dragonfly assumes a cluster with enough nodes pulling overlapping content to make peer transfer worthwhile. On a three-node development cluster, or a workload where every node pulls a different image, the scheduler has nothing to coordinate and you have added a control plane, a database and a cache tier for no gain.

The dependency footprint is the second constraint. The manager pulls in MySQL and Redis drivers, Casbin, GORM and a full HTTP stack. That is a real operational surface: a database to back up, a cache to size, an API to secure. Teams that want a single binary with no external state will find this heavier than they expect.

The README is also thin on failure behaviour. It does not document what happens when the scheduler is unavailable, whether transfers fall back to direct registry pulls, or how cache eviction is configured. Those gaps matter because a distribution layer sits on the critical path of every pod start. The project does publish a third-party security audit by Trail of Bits, with the report at docs/security/dragonfly-comprehensive-report-2023.pdf, and a SECURITY.md plus SECURITY-INSIGHTS.yml in the repository root. That is a good signal for a component in the data path, but it does not answer the availability questions.

## Dragonfly versus a plain registry pull-through cache

The obvious alternative is a registry pull-through cache: a local registry mirror that stores layers once and serves them to every node over HTTP. It is simpler, has no scheduler, and every container runtime already supports it through standard registry configuration. The difference in approach is where the bandwidth saving comes from. A pull-through cache saves the upstream registry link but still sends the full image from the cache to each node over the network. Dragonfly's P2P layer moves the transfer between nodes, so the saving applies to the intra-cluster link as well.

That distinction decides the choice. If your bottleneck is the link to an upstream registry, a mirror is enough and cheaper to run. If your bottleneck is the cluster network or the egress of the cache itself, peer distribution changes the arithmetic. Dragonfly also carries the content-addressable filesystem option, which a registry mirror does not offer; that path targets container launch time rather than raw transfer throughput, and it requires runtime-side integration that a mirror never needs.

## Maintenance, releases and licence

The repository is not archived, and the last push was on 2026-09-22. The most recent release listed is v2.5.2 on 2026-09-14, preceded by release candidates v2.5.2-rc.4 and v2.5.2-rc.3. That cadence, with release candidates before a patch release, suggests a project that stages changes rather than shipping straight to stable. Upgrade cost depends on which components you run: the manager holds state in a database, so schema changes between minor versions are the thing to watch in CHANGELOG.md before rolling forward, and node-level clients must be upgraded in step with the scheduler they talk to.

The licence is Apache-2.0. It permits commercial use and modification, and it includes an explicit patent grant, which matters for a component that sits in your delivery path. Apache-2.0 also requires that you preserve notices and state changes you make. If you fork the scheduler or ship a modified client, your distribution obligations change; that is a question for your own legal review, not something this article can settle. The project publishes SBOMs with releases, which reduces the work of tracking what ends up in your images.

## Conclusion

Adopt Dragonfly when a cluster repeatedly pulls the same large images, OCI artifacts or model files across many nodes and the registry is the bottleneck; skip it for small images, single-node setups or teams unwilling to run a scheduler and manager with their own storage. Before committing, verify how you will install it (the README points to d7y.io for documentation and the repository ships a deploy/ directory and an Artifact Hub listing), confirm the Apache-2.0 licence fits your distribution model, and check whether you need the Nydus content-addressable filesystem path or only plain P2P caching.

## FAQ

### What is Dragonfly used for in a Kubernetes cluster?

It distributes files, container images, OCI artifacts, AI/ML models, caches and logs using P2P technology, so nodes share transfers instead of each pulling the same content from the registry. The README also describes an optional content-addressable filesystem that accelerates OCI container launch.

### How do I build Dragonfly from source?

The Makefile defines a docker-build target that runs docker-build-scheduler and docker-build-manager, each calling hack/docker-build.sh for the corresponding component. A docker-push target publishes the images after building them.

### Is Dragonfly actively maintained?

The repository is not archived and the last push was on 2026-09-22. The most recent release listed is v2.5.2 from 2026-09-14, following release candidates v2.5.2-rc.4 and v2.5.2-rc.3.

### What licence does Dragonfly use?

The repository is licensed under Apache-2.0, which allows commercial use and modification and includes a patent grant. Redistributing a modified version brings notice and change-statement obligations.

## Sources

- [dragonflyoss/dragonfly on GitHub](https://github.com/dragonflyoss/dragonfly)
- [License: Apache-2.0](https://github.com/dragonflyoss/dragonfly/blob/main/LICENSE)
- [Project website](https://d7y.io)
- [README](https://github.com/dragonflyoss/dragonfly/blob/main/README.md)
- [Releases](https://github.com/dragonflyoss/dragonfly/releases)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/dragonflyoss-dragonfly