P2P Image Preheating
Relevant source files
The following files were used as context for generating this wiki page:
P2P Image Preheating is a feature in Harbor designed to enhance image distribution efficiency by proactively pushing (or "preheating") container images and OCI artifacts into Peer-to-Peer (P2P) distribution networks. By synchronizing artifacts to P2P seed nodes before they are requested by edge nodes, the system significantly reduces the latency of large-scale deployments and lessens the load on the central registry. Sources: src/portal/src/i18n/lang/en-us-lang.json, api/v2.0/swagger.yaml
The system integrates with major P2P distribution engines like Dragonfly and Kraken. It operates based on user-defined policies that specify which artifacts should be preheated, which P2P provider instance should be used, and what events (such as image push or scheduled time) should trigger the process. Sources: src/pkg/p2p/preheat/provider/dragonfly.go, src/pkg/p2p/preheat/provider/kraken.go
System Architecture
The P2P Preheating system follows a controller-provider pattern. The Controller manages high-level logic, including policy execution, instance management, and job tracking, while specific Providers handle the API interactions with external P2P engines. Sources: src/controller/p2p/preheat/controller.go:30-50
The diagram above illustrates the flow from a preheat request through the internal managers to the specific P2P distribution adapters. Sources: src/controller/p2p/preheat/controller.go, src/pkg/p2p/preheat/provider/dragonfly.go
Preheat Providers
Harbor supports multiple P2P engines. Each provider must implement a standardized interface to handle artifact status checks and trigger preheat tasks. Sources: src/controller/p2p/preheat/controller.go:35-40
Supported Vendors
| Provider | Description | Key Configuration |
|---|---|---|
| Dragonfly | CNCF P2P distribution system. | Cluster IDs, Scope (Single/All Seed Peers). |
| Kraken | P2P Docker registry by Uber. | Endpoint URL, Auth credentials. |
Sources: src/pkg/p2p/preheat/provider/dragonfly.go, src/pkg/p2p/preheat/provider/kraken.go, src/portal/src/i18n/lang/en-us-lang.json
Dragonfly Provider Logic
The Dragonfly provider allows for granular control over the preheating scope. Users can target specific seed peers or all peers within defined cluster IDs. Sources: src/pkg/p2p/preheat/provider/dragonfly.go:40-60
Dragonfly preheating involves sending a request to the Dragonfly manager with the artifact's URL and the target cluster configuration. Sources: src/pkg/p2p/preheat/provider/dragonfly.go:100-150
Policy and Execution Management
Preheating is governed by PreheatPolicy. A policy binds a set of repository/tag filters to a P2P provider instance and defines a trigger. Sources: api/v2.0/swagger.yaml:definitions/PreheatPolicy
Policy Components
- Filters: Regular expressions or comma-separated lists for repositories and tags (e.g.,
library/*,v2.*). Sources: src/portal/src/i18n/lang/en-us-lang.json - Triggers:
- Manual: Triggered by user action.
- Scheduled: Based on a Cron expression.
- Event-based: Triggered when an artifact is pushed, labeled, or scanned. Sources: api/v2.0/swagger.yaml:paths//projects/{project_name}/preheat/policies
- Criteria: Security checks such as "only signed images" or "vulnerability severity below threshold" before preheating. Sources: src/portal/src/i18n/lang/en-us-lang.json
Execution Flow
When a policy is triggered, an Execution record is created, which tracks one or more Tasks (one task per artifact). Sources: src/controller/p2p/preheat/controller.go:180-200
The sequence shows how asynchronous jobs are submitted to the Harbor Job Service to handle communication with the P2P distribution engines. Sources: src/controller/p2p/preheat/controller.go, api/v2.0/swagger.yaml
API Endpoints
The preheat system exposes several REST API endpoints for management. Sources: api/v2.0/swagger.yaml:paths
| Method | Path | Description |
|---|---|---|
GET | /p2p/preheat/providers | List all available P2P provider types. |
POST | /p2p/preheat/instances | Create a new P2P instance (Dragonfly/Kraken connection). |
POST | /projects/{project_name}/preheat/policies | Define a preheat policy for a project. |
POST | /projects/{project_name}/preheat/policies/{name} | Manually trigger a policy. |
GET | /projects/{project_name}/preheat/policies/{name}/executions | List execution history. |
Sources: api/v2.0/swagger.yaml
Conclusion
P2P Image Preheating is a critical feature for high-concurrency environments where traditional registry pull mechanisms become bottlenecks. By leveraging external engines like Dragonfly and Kraken through a unified controller and policy framework, Harbor ensures that artifacts are distributed efficiently across the infrastructure, minimizing deployment time and maximizing registry availability. Sources: src/portal/src/i18n/lang/en-us-lang.json, src/controller/p2p/preheat/controller.go