Registry Storage Interface

Relevant source files

The following files were used as context for generating this wiki page:

• internal/registry/manager.go
• internal/registry/manager_test.go
• pkg/config/config.go
• pkg/config/validate.go
• cmd/main.go
• internal/state/state.go
• README.md

The Registry Storage Interface in Harbor Satellite defines how the system interacts with OCI-compliant registries to store and manage container artifacts at the edge. The system is designed to be flexible, supporting both an embedded, managed registry (Zot) and external, user-provided registries. This modularity ensures that Harbor Satellite can operate as a standalone distribution point or integrate into existing infrastructure.

Harbor Satellite acts as a gateway or proxy for containerized artifacts on-site, ensuring consistent and available container images even in environments with intermittent network connectivity. The interface manages the transition between fetching artifacts from an upstream Harbor instance and serving them locally to edge devices.

Sources: README.md:1-25, README.md:120-135

Architecture and Components

The registry interface is primarily managed through two paths: the default managed registry (Zot) and the "Bring Your Own Registry" (BYOR) mode. The ZotManager handles the lifecycle of the embedded registry, including configuration, verification, and execution.

Registry Management Logic

The system uses a ConfigManager to determine which registry mode is active based on the BringOwnRegistry flag in the application configuration.

The diagram shows the decision path for registry initialization. Sources: cmd/main.go:193-214, internal/registry/manager.go:32-55

Key Data Structures

The configuration of the registry interface is defined within the AppConfig and Config structures.

Structure	Field	Description
AppConfig	BringOwnRegistry	Boolean indicating if an external registry is used.
AppConfig	LocalRegistryCredentials	Credentials and URL for the local registry.
Config	ZotConfigRaw	Raw JSON message containing the embedded Zot registry configuration.
State	Registry	The URL of the registry used in the current state.

Sources: pkg/config/config.go:42-65, internal/state/state.go:21-24

Embedded Registry (Zot) Implementation

When Harbor Satellite manages its own storage, it utilizes Zot, an OCI-compliant registry. The ZotManager is responsible for translating the satellite's internal configuration into a format Zot understands.

Lifecycle Management

The ZotManager performs the following steps:

1. WriteTempZotConfig: Generates a temporary JSON configuration file (defaulting to /tmp/zot-hot.json).
2. VerifyRegistryConfig: Executes Zot's internal verification logic to ensure the configuration is valid.
3. LaunchZotRegistry: Initializes the Zot controller and starts the HTTP server.
4. Hot Reloading: A hotReloader is initialized to allow configuration updates without restarting the registry process.

Sources: internal/registry/manager.go:32-124, internal/registry/manager_test.go:25-50

Configuration Defaults

If no specific zot_config is provided, the system enforces defaults, including:

• Storage: A root directory for OCI blobs (often ./zot).
• HTTP: A listener address and port (defaulting to 0.0.0.0:8585).
• Log Level: Inherited from the application log settings.

Sources: pkg/config/validate.go:127-160, internal/registry/manager_test.go:11-16

Bring Your Own Registry (BYOR)

The Registry Storage Interface allows users to point Harbor Satellite to an existing registry. In this mode, the satellite skips launching Zot and instead uses the provided LocalRegistryCredentials.

Validation and Constraints

When BringOwnRegistry is enabled, the system enforces specific validation rules:

• A custom registry URL is strictly required.
• The zot_config field in the configuration is ignored and cleared to avoid redundancy.
• The system validates the URL format and issues warnings if credentials (username/password) are missing.

Sources: pkg/config/validate.go:53-62, pkg/config/validate.go:102-120

Runtime Configuration and Mirroring

The interface extends beyond storage to the container runtime (CRI) on the host. Harbor Satellite can configure containerd, CRI-O, Docker, or Podman to use the local registry as a mirror.

The sequence diagram illustrates the mirror and fallback logic. Sources: README.md:195-205, cmd/main.go:117-121

CRI Integration Details

• Containerd: Modifies hosts.toml in the certs.d directory to define local mirrors for upstream registries.
• CRI-O: Updates registries.conf (via a temporary .toml conversion for Viper compatibility) to add the local registry to the mirror list.
• Validation: The system checks for invalid path characters and ensures IP addresses are IPv4, as IPv6 is currently unsupported for registry addresses.

Sources: internal/container_runtime/containerd.go:23-40, internal/container_runtime/crio.go:21-45, internal/utils/utils.go:26-34

Conclusion

The Registry Storage Interface provides a robust abstraction layer that allows Harbor Satellite to serve as a reliable artifact distribution node at the edge. By supporting both a managed Zot instance and external OCI registries, while simultaneously integrating with host-level container runtimes via mirror configurations, it ensures that local workloads have high availability of container images regardless of upstream connectivity status.

Sources: README.md:9-15, cmd/main.go:193-214