Satellite Agent Core
Relevant source files
The following files were used as context for generating this wiki page:
Satellite Agent Core represents the edge-side orchestration logic of the Harbor Satellite system. It is designed as a lightweight, standalone service that runs in unattended mode at edge locations to act as a local artifact store and synchronizer. Its primary purpose is to ensure that containerized workloads have high availability of images close to the workload, even in environments with intermittent or no connectivity (air-gapped sites).
The core logic handles the lifecycle of the satellite, including initial Zero-Touch Registration (ZTR) with Ground Control, periodic state synchronization, and management of the local OCI-compliant registry (Zot). It also manages container runtime configurations to ensure that local pulls are prioritized over remote fetches.
Sources: README.md:14-22, CLAUDE.md:12-18
Architecture and Components
The Satellite Agent is structured as a single process divided into several internal modules that handle specific edge-computing concerns.
Core Internal Modules
| Module | Description |
|---|---|
internal/satellite | Core orchestration logic and main loop. |
internal/state | Manages replication, state fetching from Ground Control, and artifact handling. |
internal/registry | Manages the local OCI registry (integrated Zot registry). |
internal/scheduler | Cron-based job scheduling for periodic heartbeats and syncs. |
internal/container_runtime | CRI configuration management for Docker, containerd, CRI-O, and Podman. |
internal/hotreload | Mechanism to update configuration without restarting the process. |
Sources: CLAUDE.md:65-74, README.md:103-109
System Data Flow
The following diagram illustrates the high-level interaction between the Satellite Agent Core, Ground Control, and the local container runtime.
The Satellite Agent acts as a gateway on-site, orchestrating the movement of artifacts from upstream based on the desired state provided by Ground Control.
Sources: README.md:112-115, deploy/no-spiffe/quickstart.md:144-149
Lifecycle: Registration and Bootstrapping
The Satellite Agent uses a process called Zero-Touch Registration (ZTR) to bootstrap its identity and configuration. There are two primary methods for this:
1. Token-based ZTR
Used primarily for development and testing. An administrator pre-registers the satellite in Ground Control to receive a one-time token. The satellite uses this token during its first startup to authenticate and receive its permanent credentials (Robot Account secrets) and configuration.
2. SPIFFE/SPIRE Identity
Recommended for production. The satellite authenticates via mutual TLS (mTLS) using X.509 SVIDs issued by a SPIRE agent. This method eliminates the need for shared secrets or manual token management.
State Management and Synchronization
The "Desired State" is the core concept driving Satellite operations. Ground Control serves as the source of truth for which image groups and configurations a specific satellite should possess.
State Replication Process
- Fetch State: The satellite periodically calls Ground Control to fetch the
StateConfig. - Identify Artifacts: It reads the list of images, tags, and digests defined in its assigned Groups.
- Local Sync: The satellite uses tools (such as Skopeo or Crane) to pull missing artifacts from the upstream Harbor instance and push them into the local Zot registry.
- Heartbeat: The satellite reports its current status, including CPU/Memory usage and the digest of its current state, back to Ground Control.
Sources: CLAUDE.md:104-109, ground-control/internal/server/satellite_handlers.go:486-515
Configuration Structure
The satellite configuration is handled via a JSON file (default config.json) with three primary sections:
state_config: Contains the registry credentials (Robot Account) and the URL for the state artifact.app_config: Contains Ground Control URL, log levels, and replication intervals (e.g.,@every 00h00m30s).zot_config: Detailed configuration for the embedded OCI registry, including storage root and port mappings.
Sources: CLAUDE.md:83-88, deploy/no-spiffe/quickstart.md:94-110
Container Runtime Integration (Mirrors)
To ensure edge devices pull from the local satellite rather than traversing the WAN, the Satellite Agent Core can automatically configure local Container Runtime Interfaces (CRIs) as mirrors.
| CRI | Mirror Logic |
|---|---|
| Docker | Supports mirroring for docker.io. Requires service restart to apply daemon.json changes. |
| Containerd | Configures hosts.toml or mirrors section. |
| Podman / CRI-O | Updates registries.conf to add the local Zot URL as a high-priority mirror. |
Sources: deploy/no-spiffe/quickstart.md:144-162, README.md:164-175
Implementation Details
The Satellite Agent Core utilizes several key helper functions from the Ground Control side to manage state artifacts, which are themselves stored as OCI artifacts in a special satellite project in Harbor.
// Example of how state artifacts are assembled for the edge
func AssembleSatelliteState(satelliteName string) string {
return fmt.Sprintf("%s/satellite/satellite-state/%s/state:latest", os.Getenv("HARBOR_URL"), satelliteName)
}
Sources: ground-control/internal/utils/helper.go:174-176
Key API Handlers (Ground Control)
POST /satellites: Registers a new satellite and generates a ZTR token.POST /api/v2/ztr: The endpoint called by the Satellite Agent during bootstrapping.POST /sync: Receives heartbeats and resource metrics from the satellite.
Sources: ground-control/internal/server/satellite_handlers.go:41-47, ground-control/internal/server/satellite_handlers.go:486-492
Conclusion
Satellite Agent Core provides the essential bridge between central management and edge execution. By combining Zero-Touch Registration, OCI-based state distribution, and automated runtime configuration, it enables a "set and forget" deployment model for edge registries. This architecture ensures that even when disconnected from Ground Control, the edge location maintains a local, consistent, and available cache of required container images.