Communication Protocols

Relevant source files

The following files were used as context for generating this wiki page:

• README.md
• QUICKSTART.md
• internal/state/reporting_process.go
• pkg/config/validate.go
• ground-control/internal/utils/helper.go
• deploy/quickstart/README.md
• ground-control/main.go

Harbor Satellite utilizes a multi-layered communication architecture to facilitate secure artifact distribution and state synchronization between the central management service (Ground Control) and distributed edge nodes (Satellites). These protocols handle identity verification, status reporting, and the orchestrated movement of OCI artifacts across potentially unreliable network environments.

Sources: README.md:5-15, QUICKSTART.md:5-10

Identity and Security Protocols

The project supports two primary communication security models: a simplified token-based approach and a robust zero-trust model utilizing the SPIFFE/SPIRE framework.

SPIFFE/SPIRE Zero-Trust Identity

The recommended production protocol utilizes SPIFFE (Secure Production Identity Framework for Everyone) to establish trust. In this mode, communication between Satellites and Ground Control is secured via Mutual TLS (mTLS) using X.509 SVIDs (SPIFFE Verifiable Identity Documents).

• mTLS Connection: All data exchange between components is encrypted and mutually authenticated.
• Automatic Rotation: Certificates are automatically rotated by the SPIRE agent, eliminating manual secret management.
• Attestation: Various methods are supported to bootstrap identity, including Join Tokens, X.509 Proof-of-Possession (PoP), and SSH PoP.

Sources: QUICKSTART.md:31-45, deploy/quickstart/README.md:25-35

Token-based ZTR

For development and testing, a simplified Zero-Touch Registration (ZTR) protocol is used. Ground Control generates a single-use token with a configurable TTL, which the Satellite uses to bootstrap its initial connection and pull its configuration.

Sources: QUICKSTART.md:23-28, pkg/config/validate.go:105-110

State Synchronization and Reporting

Communication is largely driven by the Satellite initiating requests to Ground Control to align its local state with the desired central configuration.

Status Reporting Protocol

Satellites periodically send heartbeat and status reports to Ground Control via the satellites/sync route. This protocol informs the central manager of the satellite's health and its current replication progress.

• Request Method: HTTP POST
• Payload Format: JSON
• Key Fields: satellite_name, heartbeat_interval, and timestamp.

Sources: internal/state/reporting_process.go:15-25, internal/state/reporting_process.go:75-85

Artifact Orchestration

Ground Control communicates desired state by creating "State Artifacts"—small OCI images containing JSON metadata that describe which repositories and tags a Satellite should replicate. These are pushed to a specific project in the Harbor registry (typically satellite/).

Protocol Aspect	Implementation Detail	Source File
State Registry	Harbor OCI Registry	ground-control/internal/utils/helper.go:85
Pathing	satellite/group-state/{group}/state:latest	ground-control/internal/utils/helper.go:79
Data Format	JSON (marshaled StateArtifact struct)	ground-control/internal/utils/helper.go:94
Transfer Tool	Crane (Go container registry library)	ground-control/internal/utils/helper.go:120

Sources: ground-control/internal/utils/helper.go:79-130

Internal Service Communication

Ground Control Startup and Health

Ground Control exposes several endpoints for internal health monitoring and administrative management. The server can start in multiple modes depending on the environment configuration:

1. Standard HTTP: Used for development or internal networks.
2. TLS: standard encrypted communication using local certificate/key files.
3. SPIFFE mTLS: Integrated with SPIRE to provide zero-trust ingress.

Sources: ground-control/main.go:39-55

Registry Mirroring Protocols

Satellites can configure local container runtimes (Docker, containerd, CRI-O) to use the internal OCI registry (Zot) as a mirror. This involves modifying host-level configuration files (e.g., host.toml for containerd) to redirect pull requests.

Sources: internal/container_runtime/host.go:55-80, README.md:148-155

Conclusion

The communication protocols in Harbor Satellite are designed to prioritize security and resilience. By leveraging SPIFFE for identity and OCI-native mechanisms for state distribution, the system ensures that edge registries remain synchronized with Ground Control even over intermittent connections while maintaining a strict zero-trust security posture.

Sources: README.md:15-20, deploy/quickstart/README.md:5-10