Configuration Reference
Relevant source files
The following files were used as context for generating this wiki page:
The Harbor Satellite configuration system manages the operational parameters for both the edge Satellite component and the cloud-side Ground Control management service. It facilitates artifact orchestration, local registry management, and state synchronization between edge locations and a central Harbor instance.
Configuration is handled through a multi-layered approach: environment variables and CLI flags provide initial bootstrap data, which is then used to fetch or maintain a JSON-based state and application configuration. This system supports hot-reloading, enabling satellites to update their operational state—such as replication intervals and registry credentials—without requiring a process restart.
Sources: CLAUDE.md:144-149, cmd/main.go:81-85
Configuration Management Architecture
The ConfigManager serves as the central authority for retrieving and updating configuration values in a thread-safe manner. It coordinates the initialization, validation, and persistence of the configuration to disk.
Initialization Flow
The satellite initializes its configuration by combining CLI flags, environment variables, and local JSON files. If specific flags are provided via the CLI, they take precedence over values found in the configuration file.
The diagram shows the lifecycle of configuration from startup to the execution of satellite processes.
Sources: cmd/main.go:48-85, pkg/config/validate.go:14-25
Validation and Defaults
The system enforces strict validation on configuration inputs, including URL formats, cron expressions for scheduling, and TLS file existence. If optional fields are missing, the system applies predefined defaults to ensure operational stability.
| Category | Parameter | Default Value | Description |
|---|---|---|---|
| Logging | log_level | info | Minimum level of log messages (debug, info, warn, etc.) |
| Schedules | state_replication_interval | @every 10s | Frequency of artifact state synchronization |
| Schedules | register_satellite_interval | @every 10s | Frequency of satellite heartbeat/registration |
| Registry | zot_config | (Internal JSON) | Default configuration for the embedded Zot OCI registry |
Sources: pkg/config/validate.go:103-125, pkg/config/validate.go:85-95
Core Configuration Modules
Application Configuration (app_config)
Defines how the satellite interacts with Ground Control and manages its local environment.
- Ground Control URL: The endpoint for the management service. Environment variables or CLI flags (
--ground-control-url) always take precedence over the config file. - Bring Your Own Registry (BYOR): If
bring_own_registryis true, the satellite skips starting the internal Zot registry and validates external registry credentials. - TLS Configuration: Manages
cert_file,key_file, andca_file. Both cert and key must be provided together if used.
Sources: pkg/config/validate.go:25-30, pkg/config/validate.go:141-155, pkg/config/getters.go:24-28
State Configuration (state_config)
Maintains the dynamic state of the satellite, primarily focusing on registry credentials and the specific state URL provided by Ground Control for artifact replication.
This class diagram illustrates the structural relationship between the primary configuration blocks.
Sources: pkg/config/getters.go:145-155, pkg/config/validate.go:15-20
Zot Registry Configuration (zot_config)
When the satellite uses its embedded registry, it requires a Zot-specific configuration. This includes storage paths and network binding information.
- Address/Port: Defaults to
0.0.0.0:8585in standard deployments. - Storage: Defines the
rootDirectoryfor OCI artifact storage.
Sources: pkg/config/validate.go:115-135, cmd/main.go:101-105
Advanced Security & Identity
SPIFFE/SPIRE Authentication
For production environments, the satellite supports SPIFFE-based identity. When enabled, traditional token-based authentication is bypassed in favor of mTLS using SVIDs.
- Endpoint Socket: Path to the SPIFFE Workload API (e.g.,
/run/spire/sockets/agent.sock). - Expected Server ID: The SPIFFE ID the satellite expects Ground Control to present.
Sources: cmd/main.go:61-75, pkg/config/getters.go:195-205
Runtime Configuration Hot-Reload
The satellite employs a HotReloadManager and a file watcher to detect changes to config.json. When a change is detected, the ConfigManager reloads the file, validates the new settings, and applies changes to running schedulers (like replication intervals) without a restart.
The sequence shows the internal flow of events during a configuration hot-reload operation.
Sources: cmd/main.go:147-175, pkg/config/manager_test.go:60-75
Conclusion
The Harbor Satellite configuration system is designed for resilience in edge environments, providing a robust validation engine and support for both simple token-based and complex zero-trust (SPIFFE) authentication. By centralizing management in the ConfigManager, the system ensures that components such as the artifact replicator and the container runtime configuration remain synchronized with the desired state provided by Ground Control.