Database Schema
Relevant source files
The following files were used as context for generating this wiki page:
The Database Schema for Harbor Satellite's Ground Control component is designed to manage a fleet of edge registries, their configurations, and their organizational groupings. Ground Control utilizes a PostgreSQL database to maintain the state of the management plane, including user authentication, satellite registration, and artifact distribution policies.
The schema acts as the central source of truth for "desired state" in the ecosystem. It tracks which satellites belong to which groups, what configurations are applied to them, and when they last performed a heartbeat. This infrastructure enables the Cloud Side to orchestrate updates and verify the health of thousands of remote sites.
Sources: CLAUDE.md:12-14, CLAUDE.md:68-71
Core Entities and Relationships
The database is structured around four primary pillars: Satellites, Configs, Groups, and Users. Relationships between these entities are managed through join tables that facilitate many-to-many or one-to-many mappings.
Entity Relationship Overview
The following diagram illustrates the logical connections between the management entities in Ground Control.
Ground Control manages the orchestration between these entities to ensure that satellites receive the correct artifact lists and operational settings.
Sources: ground-control/internal/database/satellite_configs.sql.go:61-65, ground-control/internal/database/satellite_groups.sql.go:10-14, ground-control/internal/database/satellites.sql.go:13-17
Satellite Management
The satellites table is the primary registry for edge devices. It tracks identifying information and health status for every connected satellite.
Satellite Data Model
| Field | Type | Description |
|---|---|---|
| ID | int32 | Unique internal identifier for the satellite |
| Name | string | Unique name assigned during registration |
| CreatedAt | timestamp | When the satellite was first registered |
| UpdatedAt | timestamp | Last time the database record was modified |
| LastSeen | timestamp | Timestamp of the most recent heartbeat |
| HeartbeatInterval | string | The expected frequency of satellite check-ins |
Sources: ground-control/internal/database/satellites.sql.go:19-27, ground-control/internal/database/satellites.sql.go:133-146
Registration and Health Tracking
Satellites register with Ground Control using a token or SPIFFE ID. Once registered, the database tracks their last_seen status via periodic heartbeats. Administrative operations allow for listing all satellites or retrieving specific ones by name or ID for management tasks.
Sources: ground-control/internal/database/satellites.sql.go:37-64, CLAUDE.md:78-80
Configuration Management
The configs table stores JSON-based operational settings that define how satellites behave, including replication intervals and local registry settings.
Configuration Structure
Configurations are stored as json.RawMessage objects, allowing for flexible schema definitions within the database. A separate join table, satellite_configs, manages the assignment of these configurations to specific satellites.
Config Data Model
| Field | Type | Description |
|---|---|---|
| ConfigName | string | Unique name for the configuration template |
| RegistryUrl | string | The upstream Harbor registry URL |
| Config | jsonb | The raw JSON configuration object (app_config and zot_config) |
Sources: ground-control/internal/database/configs.sql.go:21-25, pkg/config/validate.go:142-150
Grouping and Membership
Groups are collections of container images that satellites are instructed to replicate. The satellite_groups table facilitates the assignment of satellites to these logical groups.
Group Operations
The schema supports adding satellites to groups, checking membership, and listing all satellites associated with a specific group name. This is critical for the groups/sync functionality where Harbor pushes artifact lists to Ground Control.
- AddSatelliteToGroup: Maps a satellite ID to a group ID.
- CheckSatelliteInGroup: Verifies if a satellite is authorized for a group's content.
- GetSatellitesByGroupName: Retrieves all satellites that need to be notified of group updates.
Sources: ground-control/internal/database/satellite_groups.sql.go:10-53, ground-control/internal/database/satellites.sql.go:101-118
User and Access Control
The users table manages administrative access to the Ground Control management plane. It supports role-based access with a specific exclusion for the system_admin role in general list operations.
User Data Model
| Field | Type | Description |
|---|---|---|
| Username | string | Unique identifier for the user |
| PasswordHash | string | Hashed credentials for authentication |
| Role | string | User permissions (e.g., 'admin', 'system_admin') |
| CreatedAt | timestamp | Account creation time |
Sources: ground-control/internal/database/users.sql.go:19-23, ground-control/internal/database/users.sql.go:82-88
Access Logic
The database includes logic to ensure system integrity, such as SystemAdminExists to prevent accidental lockout and filtering system_admin users from standard ListUsers queries to protect high-privileged accounts.
Sources: ground-control/internal/database/users.sql.go:76-130
Summary
The Harbor Satellite Database Schema provides a robust foundation for fleet management by decoupling satellite identity from operational configuration and artifact grouping. By utilizing JSON storage for configurations and explicit join tables for relationships, Ground Control can scale to manage diverse edge environments with varying replication needs and security requirements.