System Architecture
Relevant source files
The following files were used as context for generating this wiki page:
Harbor Satellite is a registry fleet management and artifact distribution solution designed to extend the Harbor container registry to edge computing environments. It addresses challenges such as bandwidth limitations, intermittent connectivity, and the need for predictable artifact presence at remote sites. The system operates as a decentralized extension of a central Harbor instance, enabling edge locations to function independently or as a local cache for containerized workloads.
The architecture is split into two primary environments: the Cloud Side, which handles management and orchestration via Ground Control, and the Edge Side, where the Satellite component manages local artifact storage and synchronization. This separation allows for centralized control over thousands of sites while ensuring local resilience.
Sources: README.md:3-33, CLAUDE.md:7-14
Core Components
The system consists of three main architectural pillars that coordinate to distribute and manage artifacts.
1. Ground Control (Cloud Side)
Ground Control is the management service responsible for the fleet's administrative tasks. It handles device onboarding, site grouping, and state management. It serves as the bridge between the central Harbor registry and the remote satellites, providing them with the "desired state" of artifacts they must replicate.
Sources: README.md:104-108, CLAUDE.md:12-14
2. Satellite (Edge Side)
The Satellite is a lightweight, standalone service running at the edge. It is responsible for fetching artifact lists from Ground Control, identifying sources, and synchronizing artifacts from the upstream Harbor registry to the local storage. It also manages local container runtime configurations (CRI) to ensure nodes pull from the local registry first.
Sources: README.md:129-132, CLAUDE.md:9-11
3. Local OCI Registry (Edge Side)
An embedded, OCI-compliant registry (typically Zot) that stores artifacts locally. This registry acts as a primary source for local edge devices, providing high availability and consistent access to images even in air-gapped scenarios.
Sources: README.md:133-134, CLAUDE.md:78-79
The diagram shows the relationship between the central Cloud components and the Edge Site components.
Sources: README.md:136, CLAUDE.md:74-85, deploy/quickstart/README.md:21-32
Communication and Security
Harbor Satellite supports two distinct architectural patterns for authentication and secure communication between the edge and the cloud.
SPIFFE/SPIRE Architecture (Production)
For production environments, the system utilizes the SPIFFE framework with SPIRE as the runtime. This provides zero-trust, cryptographic identity through X.509 SVIDs and mutual TLS (mTLS). Satellites authenticate to Ground Control using certificates that are automatically rotated.
Sources: QUICKSTART.md:32-47, deploy/quickstart/spiffe/README.md:1-15
Token-based Architecture (Development/Testing)
A simpler method where an admin registers a satellite via Ground Control and receives a one-time use token. The satellite uses this token to bootstrap its initial connection and fetch configuration.
Sources: QUICKSTART.md:23-30, deploy/no-spiffe/quickstart.md:1-10
| Feature | Token-based ZTR | SPIFFE/SPIRE |
|---|---|---|
| Identity | One-time token | X.509 SVID (mTLS) |
| Rotation | Manual/None | Automatic |
| Infrastructure | Minimal | Requires SPIRE Server/Agents |
| Security Level | Moderate | Zero-Trust |
Sources: QUICKSTART.md:52-61, deploy/quickstart/README.md:8-17
Data Flow and Orchestration
The system follows a periodic synchronization cycle where the satellite reconciles its local state with the desired state defined in Ground Control.
State Replication Process
- Registration/Heartbeat: The Satellite periodically registers with Ground Control to indicate health and readiness.
- Fetch State: The Satellite fetches a "State Artifact" from Ground Control, which contains a JSON definition of the required groups and artifact metadata (repository, tag, digest).
- Replication: The Satellite uses tools like Crane or Skopeo to pull identified images from the remote Harbor registry and push them into the local Zot registry.
- Runtime Configuration: The Satellite modifies CRI settings (containerd, CRI-O, Podman, or Docker) to set the local registry as a mirror for upstream sources.
Sources: CLAUDE.md:81-91, ground-control/internal/utils/helper.go:106-146, pkg/config/validate.go:119-136
The sequence diagram illustrates the artifact reconciliation loop.
Sources: CLAUDE.md:81-112, deploy/no-spiffe/quickstart.md:104-126
Component Configuration
Satellite Configuration
The Satellite is configured via a JSON file containing three primary sections: state_config, app_config, and zot_config.
| Field | Type | Description |
|---|---|---|
ground_control_url | URL | The endpoint for Ground Control API. |
state_replication_interval | Cron | Frequency of artifact state synchronization. |
local_registry.url | URL | Address of the local OCI registry. |
storage.rootDirectory | Path | Filesystem path for Zot artifact storage. |
bring_own_registry | Boolean | Whether to use an external local registry instead of Zot. |
Sources: pkg/config/validate.go:13-116, CLAUDE.md:93-98
Ground Control Environment
Ground Control relies on environment variables for its connection to both the database and the upstream Harbor instance.
- Harbor Settings:
HARBOR_URL,HARBOR_USERNAME,HARBOR_PASSWORD. - Database Settings:
DB_HOST,DB_PORT,DB_DATABASE,DB_USERNAME,DB_PASSWORD.
Sources: CLAUDE.md:100-104, ground-control/internal/utils/helper.go:21-25
Deployment Architectures
The system supports multiple implementation architectures based on specific use cases:
- Remote to Local: The standard model where Satellite pulls from remote and pushes to a local OCI-compliant registry.
- Spegel Integration: Used in Kubernetes clusters where Satellite instructs Spegel instances to share images across nodes, reducing redundant remote pulls.
- Proxy Mode: The local registry runs in proxy mode, handling requests by forwarding them to the remote registry and caching results.
Sources: README.md:144-184
Summary
The Harbor Satellite architecture provides a robust framework for extending container registry capabilities to the edge. By utilizing a central management layer (Ground Control) and local execution units (Satellites), it ensures that edge workloads remain functional regardless of network stability. The support for both simple token-based and advanced SPIFFE-based security models allows it to scale from development environments to high-security production deployments.
Sources: README.md:59-71, QUICKSTART.md:52-61