Customizing Adapters & Plugins
Relevant source files
The following files were used as context for generating this wiki page:
Adapters and plugins in Harbor Next provide a modular architecture for extending the registry's core capabilities, specifically in the areas of resource replication and artifact interrogation (scanning). These components act as bridges between Harbor's internal logic and external systems, such as third-party container registries (e.g., Huawei SWR, Docker Hub) or vulnerability scanners (e.g., Trivy).
By utilizing a factory pattern and standardized API interfaces, developers can implement custom adapters to support new registry types or integrate specialized security tools. This extensibility ensures that Harbor can operate within diverse cloud-native ecosystems while maintaining a consistent management interface for administrators.
Sources: src/controller/replication/flow/stage.go:27-56, src/pkg/reg/adapter/huawei/huawei_adapter.go:34-45, api/v2.0/swagger.yaml:1414-1450
Replication Adapter Architecture
Replication adapters are responsible for facilitating the movement of artifacts between Harbor and remote registries. The system uses a factory-based initialization process where the correct adapter is instantiated based on the registry type defined in a replication policy.
Initialization Flow
When a replication task begins, the system initializes both source and destination adapters. This process involves retrieving the registered factory for a specific registry type and calling its Create method with the registry configuration.
The diagram above illustrates the sequence of steps taken to instantiate an adapter during the replication process.
Sources: src/controller/replication/flow/stage.go:33-54
Adapter Capabilities
Adapters must implement specific interfaces to handle resource fetching and metadata conversion. Key responsibilities include:
- Resource Fetching: Retrieving artifacts from the source registry based on filters.
- Metadata Conversion: Mapping remote resource metadata to Harbor's internal
ResourceMetadatastructure. - Push Preparation: Preparing the destination registry (e.g., creating namespaces) before uploading artifacts.
Sources: src/controller/replication/flow/stage.go:59-112, src/pkg/reg/adapter/huawei/huawei_adapter.go:70-88
Implementation Example: Huawei SWR Adapter
The Huawei adapter serves as a reference implementation for a third-party registry plugin. It extends the native.Adapter and implements the ArtifactRegistry interface to support replication with Huawei Cloud's SoftWare Repository (SWR).
Component Structure
The adapter maintains an internal HTTP client configured with specific modifiers for authentication (Basic or Bearer) and secure transport (CA certificates).
| Component | Description |
|---|---|
factory | Implements adp.RegisterFactory to hook into the registry system. |
adapter | Contains the core logic for API interaction with Huawei SWR. |
Info() | Declares supported resource types (Images) and filters (Name, Tag). |
PrepareForPush() | Automates the creation of namespaces in the remote Huawei registry. |
Sources: src/pkg/reg/adapter/huawei/huawei_adapter.go:47-68, src/pkg/reg/adapter/huawei/huawei_adapter.go:121-164
Data Mapping logic
Adapters translate between Harbor's generic models and provider-specific API responses. For example, the Huawei adapter uses hwNamespaceList and hwNamespace structs to unmarshal Huawei-specific JSON data before converting it to Harbor's model.Namespace format.
Sources: src/pkg/reg/adapter/huawei/huawei_adapter.go:96-120, src/pkg/reg/adapter/huawei/huawei_adapter.go:195-224
Scanner Adapter Integration
Scanner adapters are integrated via the Interrogation Services API. Unlike replication adapters which are often compiled-in, scanner adapters are typically external services that Harbor communicates with via a standardized REST API defined in the Swagger specification.
Scanner Registration Model
A scanner is integrated by registering its endpoint and capabilities. The ScannerRegistration object defines how Harbor interacts with the plugin.
The class diagram shows the relationship between a scanner registration and its declared capabilities, such as vulnerability scanning or SBOM generation.
Sources: api/v2.0/swagger.yaml:3137-3218, api/v2.0/swagger.yaml:3257-3277
Configuration Options
Scanner registration allows for detailed customization of the interaction:
- Authentication: Supports
Basic,Bearer, and custom API keys (X-ScannerAdapter-API-Key). - Network: Options to skip certificate verification or use internal registry addresses for content pulling.
- Capabilities: Indicators for
support_vulnerabilityandsupport_sbom.
Sources: api/v2.0/swagger.yaml:3137-3218, src/portal/src/i18n/lang/en-us-lang.json:SCANNER
API Customization Principles
The project utilizes go-swagger with custom templates to ensure that the API layer remains decoupled from the underlying business logic (adapters/plugins). This is achieved through the use of interfaces in the generated restapi package.
Interface Implementation
Developers customizing the server logic implement interfaces like PetAPI or StoreAPI (as seen in the tools documentation). This separation allows for:
- Dependency Injection: Injecting database or external client dependencies into the adapter logic.
- Mocking: Facilitating unit testing by providing interface mocks.
- Middleware Integration: The generated handlers are standard
http.Handlerobjects, allowing the addition of custom logging or security wrappers.
Sources: tools/swagger/templates/README.md:12-45, tools/swagger/templates/README.md:103-125
Summary of Customization Components
The following table summarizes the key elements involved in customizing or adding new adapters.
| Feature | Location / Definition | Purpose |
|---|---|---|
| Registry Factories | src/pkg/reg/adapter | Registers new replication endpoints. |
| Scanner Registration | /api/v2.0/scanners | Configures external interrogation tools. |
| Adapter Pattern | model.AdapterPattern | Defines URL and credential regex for UI validation. |
| I18N Keys | en-us-lang.json | Provides localized strings for custom plugin settings. |
| Swagger Templates | tools/swagger/templates | Customizes the generation of API server interfaces. |
Sources: api/v2.0/swagger.yaml:1414-1520, src/pkg/reg/adapter/huawei/huawei_adapter.go:34-45, src/portal/src/i18n/lang/en-us-lang.json:TOOLTIP
Customizing adapters and plugins in Harbor Next is a structured process that relies on well-defined interfaces and a factory-led initialization flow. Whether adding support for a new cloud registry or integrating a cutting-edge security scanner, the architecture ensures that these extensions remain isolated from the core registry logic while being fully manageable through the standard API and UI.