Deployment Methods
Relevant source files
The following files were used as context for generating this wiki page:
Harbor Satellite provides flexible deployment methods designed to extend the Harbor container registry to edge computing environments. These methods range from simple token-based authentication for development to complex, zero-trust architectures using SPIFFE/SPIRE for production-grade security.
The deployment architecture is primarily divided into two components: Ground Control, which resides on the cloud side for fleet management and state orchestration, and the Satellite, which runs at edge locations as a lightweight registry and synchronizer.
Sources: README.md:15-20, CLAUDE.md:8-13
Authentication & Registration Approaches
Harbor Satellite supports two primary authentication methods for onboarding satellites to the Ground Control management service.
Token-based Zero-Touch Registration (ZTR)
This method is optimized for development, testing, and small-scale deployments. It uses a one-time bootstrap token generated by the Ground Control API.
- Logic: An administrator registers a satellite via Ground Control to receive a token. The satellite then uses this token to fetch its initial configuration and register itself.
- Infrastructure: Requires only Ground Control and the Satellite.
- Security: Uses single-use tokens with a configurable Time-To-Live (TTL).
Sources: QUICKSTART.md:15-22, deploy/no-spiffe/quickstart.md:1-5
SPIFFE/SPIRE (Zero-Trust Identity)
Recommended for production and fleet-scale deployments, this method utilizes the SPIFFE framework and SPIRE runtime to provide cryptographic identity.
- Logic: Satellites authenticate using Mutual TLS (mTLS) with X.509 SVIDs (SPIFFE Verifiable Identity Documents) that are automatically rotated.
- Infrastructure: Requires a SPIRE Server (trust root), SPIRE Agents (one per node), Ground Control, and the Satellite.
- Attestation: Supports multiple methods to prove identity, including Join Tokens, X.509 Proof-of-Possession (PoP), and SSH PoP.
Sources: QUICKSTART.md:24-43, deploy/quickstart/README.md:5-15, deploy/quickstart/spiffe/README.md:3-12
Method Comparison Table
| Feature | Token-based ZTR | SPIFFE/SPIRE |
|---|---|---|
| Complexity | Low | Medium |
| Authentication | One-time token | mTLS with X.509 SVIDs |
| Rotation | N/A | Automatic |
| Use Case | Dev, Testing, CI/CD | Production, Fleet-scale |
| Infrastructure | Ground Control Only | GC + SPIRE Server + Agents |
Sources: QUICKSTART.md:46-55
Deployment Architectures
The project supports several architectural patterns depending on how artifacts are moved and served at the edge.
Architecture Flow Diagram
This diagram illustrates the relationship between the central Harbor instance, Ground Control, and the edge Satellite components.
The diagram shows the state synchronization between Satellite and Ground Control, and the artifact pull flow from central Harbor to the local OCI registry.
Sources: README.md:105-115, CLAUDE.md:77-85
Use Case #1: Remote to Local Registry
The Satellite pulls container images from a remote registry and pushes them to a local OCI-compliant registry (such as Zot). This is the standard "store-and-forward" model for edge devices.
Sources: README.md:120-130
Use Case #2: Kubernetes with Spegel
The Satellite sends instructions to Spegel instances running on Kubernetes nodes. Nodes pull images and share them locally via a peer-to-peer mechanism, reducing external bandwidth usage.
Sources: README.md:136-148
Use Case #3: Proxy Mode
The Satellite configures the local registry to run in proxy mode. Requests from edge devices are forwarded to the remote registry, ensuring availability even without a pre-compiled image list.
Sources: README.md:154-165
Implementation Methods
Container-based Deployment (Docker Compose)
The primary method for end-users to deploy Ground Control and Satellites is via Docker Compose.
- Ground Control Stack: Includes PostgreSQL (database) and the Ground Control API service.
- SPIFFE Stack: Adds SPIRE Server and SPIRE Agents to the core stack.
- Satellite Stack: Includes the Satellite binary and an embedded or standalone OCI registry (Zot).
Sources: deploy/no-spiffe/quickstart.md:35-42, deploy/quickstart/common/docker-compose.base.yml:5-30, deploy/quickstart/spiffe/sshpop/external/gc/docker-compose.yml:5-80
Dagger-based Orchestration
For developers and CI/CD environments, Dagger is used to build and run components consistently across platforms.
# Build satellite binary
dagger call build --source=. --component=satellite export --path=./bin
# Run Ground Control with Dagger
dagger call run-ground-control up
Sources: CLAUDE.md:18-25, deploy/no-spiffe/quickstart.md:47-58
Binary Execution
Components can be run directly as Go binaries, which is useful for debugging.
- Satellite Flag Example:
./satellite --token "<token>" --ground-control-url "http://gc:8080" --mirrors=containerd:docker.io - Ground Control Environment: Requires a
.envfile containing Harbor credentials and database connection strings.
Sources: CLAUDE.md:55-65, deploy/no-spiffe/quickstart.md:20-30
Container Runtime Configuration
A critical part of the deployment is configuring edge container runtimes to recognize the Satellite as a mirror.
Supported Runtime Mirroring
Satellites can manage CRI configurations for the following runtimes:
- Docker: Supports mirroring for
docker.iovia--mirrors=docker:true. - Containerd, Podman, CRI-O: Supports mirroring multiple upstream registries.
Sources: deploy/no-spiffe/quickstart.md:92-108, CLAUDE.md:106-114
Configuration Parameters
| Parameter | Type | Description | Default |
|---|---|---|---|
ground_control_url | string | URL for the Ground Control management service | N/A |
state_replication_interval | cron | Frequency of artifact state synchronization | @every 10s |
local_registry.url | string | Endpoint of the edge OCI registry | http://0.0.0.0:8585 |
use_unsecure | boolean | Allow non-HTTPS connections to GC | false |
Sources: deploy/no-spiffe/quickstart.md:68-85, CLAUDE.md:100-104
Summary
Harbor Satellite deployment methods are designed to accommodate varying security requirements and infrastructure constraints. By providing both simple token-based setups and sophisticated SPIFFE-integrated architectures, the system ensures that edge registries can be managed securely at scale, regardless of network reliability or environment complexity.