Backend Registry Integration
Relevant source files
The following files were used as context for generating this wiki page:
Backend Registry Integration in Harbor Next facilitates the seamless connection and management of various container registries and OCI artifact providers. This system enables Harbor to act as a central hub for artifact lifecycle management, supporting operations such as artifact replication, proxy caching, and unified metadata retrieval across diverse backend types including Docker Hub, AWS ECR, Azure ACR, and Google GCR.
Sources: README.md:31-40, api/v2.0/swagger.yaml:1480-1510
Registry Architecture and Adapters
Harbor uses a pluggable adapter architecture to interact with different backend registry types. Each backend type requires a specific factory to create an adapter that implements standard interfaces for artifact management. This abstraction allows Harbor's core logic to perform operations like fetching artifacts or pushing content without needing to know the specific implementation details of the underlying registry API (e.g., Docker Distribution V2 vs. OCI).
Sources: src/controller/replication/flow/stage.go:30-55, README.md:73-80
Supported Registry Types
The system supports a wide range of permitted registry types, especially for features like proxy caching and replication.
| Registry Type | Description |
|---|---|
docker-hub | Official Docker Hub registry |
harbor | Other Harbor instances (for cascading replication) |
azure-acr | Azure Container Registry |
aws-ecr | Amazon Elastic Container Registry |
google-gcr | Google Container Registry |
quay | Red Hat Quay registry |
github-ghcr | GitHub Container Registry |
jfrog-artifactory | JFrog Artifactory OCI support |
Sources: src/pkg/chart/testdata/harbor-schema2/templates/core/core-cm.yaml:65-66, api/v2.0/swagger.yaml:2260-2270
Adapter Initialization Flow
The initialization process involves identifying the registry type from the policy and invoking the corresponding factory.
The flow ensures that both source and destination registries are properly authenticated and configured before any data transfer occurs.
Sources: src/controller/replication/flow/stage.go:34-52
Artifact Replication Flow
Replication is a core component of backend integration, allowing the synchronization of artifacts between local and remote registries. The flow is divided into stages: initialization, resource fetching, assembly, and preparation.
Sources: src/controller/replication/flow/stage.go:58-75
Resource Assembly and Namespace Transformation
During replication, Harbor must often transform the repository namespace to match the destination's structure. This is handled by a flattening logic that replaces or joins path components based on a replaceCount parameter.
| Replace Count | Source: a/b/c/img | Result with Namespace n |
|---|---|---|
-1 (Legacy) | a/b/c/img | n/img |
0 | a/b/c/img | n/a/b/c/img |
1 | a/b/c/img | n/b/c/img |
2 | a/b/c/img | n/c/img |
Sources: src/controller/replication/flow/stage.go:176-200, api/v2.0/swagger.yaml:2365-2375
Sequence of Replication Stages
The following sequence diagram illustrates how Harbor coordinates between adapters to move an artifact.
The PrepareForPush step is critical for ensuring the destination registry has the necessary repositories or namespaces created before the actual blob transfer begins.
Sources: src/controller/replication/flow/stage.go:58-135
Registry Management API
Harbor provides a comprehensive REST API for managing backend registry configurations. This includes CRUD operations on registry endpoints and health checks.
Key Registry Management Endpoints
| Method | Path | Description |
|---|---|---|
POST | /registries | Create a new backend registry configuration |
GET | /registries | List all configured backend registries |
POST | /registries/ping | Test connection to a registry endpoint |
GET | /registries/{id}/info | Get registry capabilities (filters, triggers) |
Sources: api/v2.0/swagger.yaml:1480-1550
Data Model: Registry Object
The registry object defines the connection details and credentials required for integration.
| Field | Type | Description |
|---|---|---|
url | string | The registry URL string |
type | string | Type (e.g., harbor, docker-hub, aws-ecr) |
credential | object | Contains type, access_key, and access_secret |
insecure | boolean | Whether to verify SSL certificates |
ca_certificate | string | Custom PEM-encoded CA for verification |
Sources: api/v2.0/swagger.yaml:2410-2440
Proxy Cache Integration
Backend integration also powers the Proxy Cache feature, allowing Harbor projects to act as a pull-through cache for external registries. When a project is configured for proxy caching, it references a backend registry ID and optimizes artifact retrieval by storing local copies of blobs and manifests.
Proxy Cache Configuration
Configuration is managed through project metadata and core environment variables.
- Registry ID: Linked to a specific configured backend registry.
- Upstream Connection Limit: Controlled by
max_upstream_connto prevent overloading the backend. - Bandwidth Limit: Managed via
proxy_speed_kbto throttle communication with the upstream registry.
Sources: api/v2.0/swagger.yaml:2310-2340, CHANGELOG.md:15-18, src/pkg/chart/testdata/harbor-schema2/templates/core/core-cm.yaml:65-66
Conclusion
Backend Registry Integration is a foundational pillar of Harbor Next, utilizing a sophisticated factory-adapter pattern to support diverse OCI providers. By centralizing authentication, namespace transformation, and capability discovery, it enables advanced features like multi-level replication and proxy caching, ensuring consistent artifact management regardless of where the physical data resides.
Sources: README.md:31-40, src/controller/replication/flow/stage.go:30-55