Use Cases & Scenarios
Relevant source files
The following files were used as context for generating this wiki page:
Harbor Satellite is designed to extend the Harbor container registry to edge computing environments, providing a registry fleet management and artifact distribution solution. Its primary purpose is to address challenges such as bandwidth limitations, intermittent network connectivity (air-gapped environments), and remote fleet orchestration.
The system operates by placing a lightweight, standalone registry at edge locations that serves as both a primary registry for local workloads and a fallback for a central Harbor instance. This ensures that container images are consistently available and integrity-checked even when the connection to the central data center is lost.
Sources: README.md:3-10, CLAUDE.md:7-12
Core Use Cases
Harbor Satellite supports several architectural implementations based on specific network constraints and scale requirements.
Use Case #1: Remote-to-Local Replication
In this basic scenario, a stateless Satellite component pulls container images from a remote central Harbor registry and pushes them to a local OCI-compliant registry (such as Zot). Local edge devices then pull images directly from this local store.
- Scenario: IoT devices in a location with unreliable internet need up-to-date images. When connectivity is established, the Satellite syncs with Ground Control to identify and pull new artifacts. When offline, devices continue to pull from the local cache.
- Key Components: Satellite (Synchronizer), Zot (Local OCI Registry), Ground Control (Orchestrator).
Sources: README.md:104-122
The diagram above shows the flow of metadata from Ground Control and image data from Harbor to the local edge registry.
Sources: README.md:118
Use Case #2: Distributed Edge Nodes (Spegel Integration)
For larger scale environments where a single local registry cannot handle the demand, the Satellite instructs Spegel instances running on Kubernetes nodes. Nodes pull images and share them peer-to-peer across the cluster.
- Scenario: A massive fleet of IoT devices across multiple Kubernetes nodes. Instead of every node pulling from a remote source, the Satellite coordinates cross-node replication.
- Key Logic: Pull instructions are sent to Spegel, which manages local distribution.
Sources: README.md:124-138
Use Case #3: Transparent Proxy Mode
In this mode, the Satellite configures the local OCI registry to run in proxy mode. The registry handles pulling images on-demand from the remote registry rather than following a pre-defined sync list.
- Scenario: Situations where Ground Control cannot produce a deterministic list of images. The Satellite ensures availability by forwarding edge device requests to the remote registry and caching the results.
Sources: README.md:140-151
Deployment Scenarios & Environments
Harbor Satellite is built for specific technical environments where traditional registry access is restricted or inefficient.
| Environment | Scenario | Technical Benefit |
|---|---|---|
| Air-Gapped / Ships | No permanent internet connectivity. | Stateful local registry ensures 24/7 image availability. |
| High Security | Restricted ingress/egress data flow (Firewalls). | Satellite initiates outbound sync, avoiding complex inbound rules. |
| Global CDN | Global image distribution across multiple regions. | Localizes high-bandwidth traffic to the edge network. |
| Bandwidth Constrained | Remote locations with expensive or slow links. | Syncs only the "desired state" delta managed by Ground Control. |
Sources: README.md:20-33, README.md:83-88
Authentication & Onboarding Scenarios
The system provides different onboarding paths depending on the security requirements of the deployment.
Development and Quick Testing
For CI/CD or local development, Token-based Zero-Touch Registration (ZTR) is used. An admin registers a satellite via the Ground Control API and receives a one-time token.
Sources: QUICKSTART.md:17-23, deploy/no-spiffe/quickstart.md:1-10
Production Fleet Management
For production, SPIFFE/SPIRE is recommended. This provides cryptographic identity, mTLS, and automatic certificate rotation, which is critical for securing thousands of remote sites.
- Join Token Attestation: Simple one-time token used by a SPIRE agent to bootstrap identity.
- X.509 PoP: Agents authenticate using pre-provisioned certificates from an existing PKI.
- SSH PoP: Authenticates using SSH host certificates.
Sources: QUICKSTART.md:25-39, deploy/quickstart/spiffe/join-token/README.md:1-5, deploy/quickstart/spiffe/x509pop/README.md:1-5
Sequence diagram showing the Zero-Trust identity bootstrapping process.
Sources: deploy/quickstart/README.md:41, deploy/quickstart/spiffe/join-token/README.md:104-115
Runtime Configuration Scenarios
To ensure edge devices actually use the local registry, the Satellite manages container runtime (CRI) configurations.
- Registry Mirroring: Configures
containerd,CRI-O,Docker, orPodmanto treat the local Satellite as a mirror for upstream registries likedocker.ioorquay.io. - Fallback Logic: If the local Satellite registry is unavailable, the runtime is configured to fall back to the central Harbor instance.
- Direct Referencing: Using Kubernetes mutating webhooks to rewrite image paths to point to the local registry.
Sources: README.md:153-162, CLAUDE.md:103-112, deploy/no-spiffe/quickstart.md:143-155
Summary
Harbor Satellite transforms the Harbor registry from a centralized service into a distributed fleet of edge registries. Whether through manual token registration for small-scale testing or automated SPIFFE-based attestation for massive IoT fleets, it ensures that containerized workloads remain operational regardless of network stability. Its ability to act as a local cache, a peer-to-peer node, or a transparent proxy allows it to adapt to diverse edge architectures.