Ground Control Overview
Relevant source files
The following files were used as context for generating this wiki page:
Ground Control is the cloud-side management component of the Harbor Satellite solution. It serves as the central control plane responsible for managing a fleet of edge registries, orchestrating artifact distribution, and maintaining the desired state for satellite instances. Ground Control bridges the gap between a central Harbor registry and decentralized edge locations, enabling consistent artifact availability even in environments with intermittent connectivity.
Sources: README.md:37-41, CLAUDE.md:12-14
Core Responsibilities
Ground Control provides four primary services to the Harbor Satellite ecosystem:
- Satellite Management: Handling the onboarding, grouping, and heartbeat monitoring of edge sites.
- State Management: Defining the "desired state" (which artifacts should exist where) and verifying that satellites comply with this state.
- Configuration Delivery: Providing satellites with their operational parameters, including replication intervals and local registry settings.
- Harbor Integration: Communicating with the central Harbor API to manage projects, robot accounts, and replication policies.
Sources: README.md:47-51, CLAUDE.md:55-58
System Architecture
The Ground Control service is a Go-based application that interacts with a PostgreSQL database for persistence and a Harbor instance for artifact source-of-truth.
The diagram shows Ground Control's central position between the Harbor registry and the edge Satellites.
Sources: README.md:131-137, CLAUDE.md:65-68, deploy/quickstart/spiffe/sshpop/external/gc/docker-compose.yml:68-112
Component Stack
| Component | Technology | Role |
|---|---|---|
| Server | Go (net/http) | Provides REST API for satellites and admins |
| Database | PostgreSQL | Stores satellite metadata, group definitions, and configs |
| Identity | SPIFFE/SPIRE | (Optional) Provides mTLS and cryptographic identity |
| Migrations | Custom Migrator | Handles SQL schema updates automatically on startup |
| Health Check | Harbor Health | Verifies Harbor connectivity before starting |
Sources: ground-control/main.go:21-31, CLAUDE.md:65-72, deploy/quickstart/spiffe/sshpop/external/gc/docker-compose.yml:5-25
Authentication and Onboarding
Ground Control supports two distinct methods for authenticating satellites:
1. Token-Based Zero-Touch Registration (ZTR)
A simple approach used for development and testing. An administrator manually registers a satellite via the Ground Control API and receives a one-time token. The satellite uses this token to bootstrap its initial connection and receive its permanent identity.
Sources: QUICKSTART.md:20-24, deploy/no-spiffe/quickstart.md:136-146
2. SPIFFE/SPIRE (Production)
Recommended for production fleets, this method uses the SPIFFE framework to provide satellites with cryptographic identities (SVIDs). Authentication is handled via mutual TLS (mTLS) using certificates rotated automatically by SPIRE. Ground Control can utilize several attestation methods:
- Join Token: One-time tokens generated by SPIRE server.
- X.509 PoP: Pre-provisioned certificates.
- SSH PoP: SSH host certificates.
Sources: QUICKSTART.md:26-40, deploy/quickstart/spiffe/join-token/README.md:3-6
The registration flow for a new satellite instance.
Sources: deploy/quickstart/spiffe/join-token/README.md:92-108, deploy/no-spiffe/quickstart.md:136-150
Key Management Concepts
Groups
Groups are collections of container images that satellites are instructed to replicate. A group definition includes the source registry (Harbor) and a list of specific artifact metadata (repository, tag, digest).
Sources: CLAUDE.md:74-75, deploy/no-spiffe/quickstart.md:104-120
Configs
Configuration objects define how satellites behave. These are stored in Ground Control and delivered to satellites via API. Key fields include:
state_replication_interval: Frequency of artifact synchronization.register_satellite_interval: Heartbeat/registration frequency.local_registry: Configuration for the embedded Zot registry on the satellite.
Sources: CLAUDE.md:77-78, deploy/no-spiffe/quickstart.md:122-134
Startup Logic
When the Ground Control process starts, it performs a sequence of initialization steps before accepting traffic:
- Harbor Health Check: Verifies that the upstream Harbor instance is reachable and healthy.
- Database Migrations: Executes SQL migrations to ensure the PostgreSQL schema is up to date.
- Cleanup Job: Starts a background routine to clean up expired tokens or stale state.
- Listener Setup: Depending on configuration, starts either a standard HTTP server, a TLS server, or a SPIFFE-enabled mTLS server.
Sources: ground-control/main.go:21-50
API Endpoints Summary
| Endpoint | Method | Description |
|---|---|---|
/health | GET | Basic health check for the service |
/login | POST | Authenticate admin users to Ground Control |
/api/satellites | POST | Register a new satellite and get a token |
/api/configs | POST | Create or update a satellite configuration profile |
/api/groups/sync | POST | Define a group of artifacts for replication |
/api/groups/satellite | POST | Associate a specific group with a satellite |
Sources: deploy/no-spiffe/quickstart.md:104-140, deploy/quickstart/spiffe/join-token/README.md:139-160, CLAUDE.md:65-68
Conclusion
Ground Control acts as the brain of the Harbor Satellite architecture. By centralizing the management of edge registries into a single control plane, it allows operators to manage thousands of remote sites as a unified fleet. Its support for both simple token-based onboarding and robust SPIFFE-based zero-trust identity makes it adaptable for both simple testbeds and complex, secure production environments.