Satellite Management
Relevant source files
The following files were used as context for generating this wiki page:
Satellite Management is a core function of the Harbor Satellite "Ground Control" component, responsible for the lifecycle orchestration of edge registry instances. It encompasses satellite onboarding, cryptographic identity assignment, configuration distribution, and real-time health monitoring. Within the ecosystem, Ground Control acts as the central management plane, ensuring that remote satellites remain synchronized with the desired state defined in the central Harbor registry.
Sources: CLAUDE.md:1-25, README.md:58-75
Satellite Registration and Authentication
Harbor Satellite supports two primary flows for registering a new edge instance: Token-based Zero-Touch Registration (ZTR) and SPIFFE-based authentication.
Token-based Registration (Standard)
This flow is used primarily for development and simple deployments. An administrator creates a satellite entry in Ground Control, which returns a one-time use token with a 24-hour expiry. The satellite uses this token to bootstrap its initial connection and receive its permanent Harbor robot account credentials.
Sources: ground-control/internal/server/satellite_handlers.go:134-145, deploy/no-spiffe/quickstart.md:1-20
SPIFFE/SPIRE Authentication
For production environments, Ground Control leverages the SPIFFE framework to provide cryptographic identities. Satellites authenticate using mutual TLS (mTLS) with X.509 SVIDs. In this mode, registration can be automated via spiffeZtrHandler, which supports "auto-registration" where a satellite is dynamically created in the database upon its first valid mTLS connection.
Sources: ground-control/internal/server/satellite_handlers.go:281-310, deploy/quickstart/spiffe/join-token/README.md:10-30
Registration Flow
The following diagram illustrates the standard token-based registration sequence:
The registration process ensures that every satellite has a corresponding robot account in Harbor with access to the satellite project for state synchronization.
Sources: ground-control/internal/server/satellite_handlers.go:48-158, ground-control/internal/utils/helper.go:88-105
State and Configuration Management
Satellites do not store complex logic; they follow a "desired state" model. Ground Control manages this state through two primary mechanisms: Groups and Configs.
Configuration Objects
Configs define the operational parameters of a satellite, including log levels, replication intervals, and the configuration for the embedded Zot registry. When a config is created or updated, Ground Control pushes it as an OCI artifact to the central Harbor registry.
| Field | Description |
|---|---|
config_name | Unique identifier for the configuration set |
state_replication_interval | Frequency at which the satellite checks for new state |
heartbeat_interval | Frequency of satellite status reporting |
local_registry | Settings for the satellite's internal OCI registry (Zot) |
Sources: ground-control/internal/server/config_handlers.go:25-80, deploy/no-spiffe/quickstart.md:130-160
State Artifacts
Ground Control assembles a "State Artifact" for each satellite. This is a JSON file (stored as an OCI artifact in Harbor) that contains:
- The URL to the satellite's assigned configuration.
- A list of URLs pointing to the Group State artifacts.
- Registry credentials (Harbor Robot Account) for the satellite to pull these artifacts.
The function CreateOrUpdateSatStateArtifact is responsible for pushing this orchestration metadata to Harbor.
Sources: ground-control/internal/utils/helper.go:179-215, ground-control/internal/server/satellite_handlers.go:121-131
Monitoring and Health
Satellites report their status periodically via a heartbeat mechanism (the /sync endpoint). Ground Control tracks these reports to provide a fleet-wide view of satellite health and resource utilization.
Satellite Status Reporting
The status update includes telemetry and synchronization metadata:
- Activity: Current operation (e.g., replicating, idle).
- Resource Usage: CPU percentage, memory used (bytes), and storage used (bytes).
- Sync Metadata: Digests of the latest state and config processed, and the duration of the last sync.
Sources: ground-control/internal/server/satellite_handlers.go:34-45, ground-control/internal/server/satellite_handlers.go:465-515
Health States
Ground Control classifies satellites into three categories based on their heartbeat:
- Active: Satellites that have reported within their expected heartbeat interval.
- Stale: Satellites that have missed reports but remain in the database.
- Inactive/Unknown: Satellites that have never reported or were manually disconnected.
Sources: ground-control/internal/server/satellite_handlers.go:534-555
API Endpoints for Satellite Management
Ground Control provides a RESTful API for managing the satellite fleet.
| Method | Endpoint | Description |
|---|---|---|
| POST | /satellites | Register a new satellite and get a token |
| GET | /satellites | List all registered satellites |
| POST | /api/satellites/register | SPIFFE-based registration and SVID assignment |
| POST | /configs | Create a new configuration template |
| POST | /configs/satellite | Assign a configuration to a specific satellite |
| POST | /groups/satellite | Add a satellite to an artifact group |
| DELETE | /satellites/{satellite} | Unregister a satellite and cleanup Harbor resources |
Sources: ground-control/internal/server/satellite_handlers.go:48-158, ground-control/internal/server/config_handlers.go:240-275, deploy/no-spiffe/quickstart.md:162-175
Conclusion
Satellite Management in Harbor Satellite provides a robust, centralized framework for orchestrating edge registries. By abstracting complexity into OCI-based state artifacts and supporting both simple token-based and advanced SPIFFE-based authentication, Ground Control enables secure and scalable deployment of container artifacts across diverse and disconnected environments.
Sources: README.md:130-150, CLAUDE.md:75-90