State Management & Reporting
Relevant source files
The following files were used as context for generating this wiki page:
State Management and Reporting is the core mechanism by which Harbor Satellite maintains synchronization with Ground Control and Harbor. This system is responsible for fetching the "desired state" (the list of artifacts and configurations a satellite should have), reconciling that state against the local registry, and reporting health and performance metrics back to the central management service.
The process ensures that edge registries remain consistent with central policies even in intermittent connectivity environments. It encompasses state artifact retrieval, differential replication logic, and periodic status heartbeats that include resource utilization data like CPU, memory, and storage metrics.
Sources: README.md, internal/state/state_process.go:21-28, internal/state/reporting_process.go:19-25
State Synchronization Architecture
The synchronization process is orchestrated by the FetchAndReplicateStateProcess. It follows a hierarchical structure where a "Root State" defines which groups and configurations apply to a specific satellite.
State Hierarchy and Discovery
The satellite first fetches a SatelliteState (the root state). This object contains a list of individual group state URLs and a configuration URL. The satellite then iterates through these URLs to build a complete map of required artifacts.
The satellite extracts its identity from the state URL provided during initialization to ensure it pulls the correct manifest.
Sources: internal/state/state.go:30-33, internal/state/state_process.go:73-85, internal/state/report.go:94-110
Reconcilation Logic
The satellite uses a differential update strategy. It compares the Entities (combinations of repository, name, tag, and digest) currently stored in its local StateMap against the newly fetched state.
- Deletion: Any entity present in the old state but missing in the new state is scheduled for deletion.
- Replication: New entities or existing entities with changed digests are scheduled for replication.
- Unchanged: Entities with matching keys and digests are skipped to save bandwidth.
Sources: internal/state/state_process.go:124-170, internal/state/state_process_test.go:137-160
Status Reporting & Heartbeats
The StatusReportingProcess handles periodic check-ins with Ground Control. This process communicates through the satellites/sync endpoint and provides a snapshot of the satellite's current health and resource consumption.
Status Report Schema
The reporting system collects telemetric data via the StatusReportParams structure.
| Field | Type | Description |
|---|---|---|
name | string | The extracted name of the satellite. |
cpu_percent | float64 | Average CPU usage over the heartbeat interval. |
memory_used_bytes | uint64 | Current virtual memory usage in bytes. |
storage_used_bytes | uint64 | Disk usage at the root path. |
last_sync_duration_ms | int64 | Time taken for the last state replication. |
latest_state_digest | string | The digest of the most recently processed state. |
Sources: internal/state/report.go:19-31, internal/state/reporting_process.go:27
Data Collection Flow
Metrics are collected conditionally based on the MetricsConfig provided in the application configuration.
Remote Configuration Reconcilation
In addition to image artifacts, the satellite manages its own internal configuration via state updates. The reconcileRemoteConfig sub-process monitors the upstream configuration digest. If a change is detected:
- The new configuration is fetched and validated.
- The current configuration is backed up to
prev_config.json. - The new configuration is written to disk, triggering a hot-reload of internal components.
Sources: internal/state/state_process.go:250-305, pkg/config/validate.go:21-45
Security and Connectivity
State Management supports multiple authentication and transport modes:
- SPIFFE/SPIRE: If enabled, the reporting process uses a SPIFFE-attested HTTP client to communicate with Ground Control, facilitating zero-trust identity.
- Insecure Mode: Supports
use_unsecuresettings for local testing or internal networks where HTTP is preferred over HTTPS. - Token-based: Standard registration uses a secure token for initial onboarding and state retrieval.
Sources: internal/state/reporting_process.go:37-48, internal/state/reporting_process.go:94-110, cmd/main.go:55-70
Conclusion
State Management & Reporting acts as the "nervous system" of the Harbor Satellite. By combining hierarchical state discovery, differential artifact replication, and comprehensive resource reporting, the system allows Ground Control to manage thousands of edge registries effectively. This architecture ensures that satellites remain performant and compliant with central registry states while providing the visibility needed for remote fleet orchestration.