Introduction to Harbor Satellite
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 capabilities of the Harbor container registry to edge computing environments. It enables decentralized registries to operate at edge locations, acting as both a primary registry for local workloads and a fallback for a central Harbor instance. This architecture ensures consistent availability and integrity of container images even in environments with intermittent or unavailable network connectivity (air-gapped sites).
Sources: README.md:3-8, CLAUDE.md:6-10
The system addresses critical challenges in edge computing, such as bandwidth limitations, remote fleet orchestration, and the need for predictable behavior in challenging connectivity situations. By running as a lightweight, single-process service in unattended mode, Harbor Satellite optimizes resource utilization while providing transparent deployment across thousands of sites.
Sources: README.md:13-22, README.md:39-44
System Architecture
Harbor Satellite is structured into two primary modules: a cloud-side management service and an edge-side distribution component.
Core Components
| Component | Location | Description |
|---|---|---|
| Ground Control | Cloud Side | Manages devices, onboarding, site grouping, and desired state orchestration. |
| Satellite | Edge Side | A lightweight registry (Zot) and synchronizer that manages local artifact storage and runtime configuration. |
| Harbor | Cloud Side | The central source of truth cluster equipped with a satellite extension for fleet integration. |
Sources: CLAUDE.md:7-10, README.md:47-58
Architectural Overview Diagram
The following diagram illustrates the relationship between the central Harbor instance, Ground Control, and the Satellite instances deployed at edge locations.
Sources: README.md:104-120, CLAUDE.md:43-58
Key Operational Concepts
State Replication and Syncing
The Satellite maintains its state through a periodic synchronization process. It fetches the "desired state" from Ground Control, which includes a list of artifacts (repository, tag, digest) and registry credentials. The Satellite then uses tools to pull these artifacts from the upstream Harbor registry and store them in the local OCI-compliant registry (typically Zot).
Sources: CLAUDE.md:68-71, CLAUDE.md:88-91
Registration and Heartbeats
Satellites must register with Ground Control to receive configurations. This is done via a heartbeat mechanism (defaulting to every 10 seconds) where the satellite identifies itself using a token or cryptographic identity.
Sources: CLAUDE.md:73-74, deploy/no-spiffe/quickstart.md:103-113
Runtime Configuration (Mirroring)
To ensure edge devices pull from the local Satellite rather than attempting to reach the cloud, the Satellite can modify container runtime configurations (Docker, containerd, CRI-O, or Podman). It configures the local registry as a mirror, allowing for transparent redirection of pull requests.
Sources: README.md:162-171, CLAUDE.md:76-77, deploy/no-spiffe/quickstart.md:154-170
Authentication Methods
Harbor Satellite supports two primary methods for authenticating edge satellites with the cloud-side Ground Control.
1. Token-based Zero-Touch Registration (ZTR)
This is a simpler approach best suited for development and testing. An administrator creates a satellite record in Ground Control, which generates a one-time token. The Satellite uses this token to bootstrap its initial connection.
Sources: QUICKSTART.md:15-19, deploy/no-spiffe/quickstart.md:12-15
2. SPIFFE/SPIRE (Zero-Trust Identity)
Recommended for production environments, this method uses the SPIFFE framework to provide cryptographic identities (X.509 SVIDs). It supports automatic certificate rotation and multiple attestation methods, including Join Tokens, X.509 Proof-of-Possession (PoP), and SSH PoP.
Sources: QUICKSTART.md:21-36, deploy/quickstart/README.md:7-14
Technical Implementation Details
Configuration Structure
The Satellite uses a JSON configuration file divided into three main sections:
- state_config: Handles registry credentials and state URLs.
- app_config: Contains Ground Control URLs, log levels, and replication intervals.
- zot_config: Defines settings for the embedded OCI registry, including storage paths and ports.
Sources: CLAUDE.md:79-84, deploy/no-spiffe/quickstart.md:81-101
State Artifact Generation
Ground Control manages state by creating OCI artifacts that contain metadata. These are pushed to Harbor and then fetched by Satellites. Key utility functions in ground-control/internal/utils/helper.go facilitate this:
CreateStateArtifact: Marshals metadata intoartifacts.jsonand pushes it as an OCI image.AssembleSatelliteState: Constructs the repository path for a satellite's state.CreateRobotAccForSatellite: Automatically provisions Harbor robot accounts with scoped permissions for the satellite.
Sources: ground-control/internal/utils/helper.go:100-115, ground-control/internal/utils/helper.go:174-176, ground-control/internal/utils/helper.go:56-60
Conclusion
Harbor Satellite extends the Harbor ecosystem to the edge by providing a resilient, lightweight, and centrally managed distribution layer. By decoupling artifact management from network availability and automating runtime configuration, it allows containerized workloads to operate reliably in highly isolated or bandwidth-constrained environments.
Sources: README.md:61-71, README.md:122-132