Group Management
Relevant source files
The following files were used as context for generating this wiki page:
Group Management is a core architectural component of Harbor Satellite's Ground Control service. Groups serve as logical collections of container image metadata (artifacts) that Satellites use to determine which content to replicate from the central Harbor registry. They define the "desired state" for edge locations by specifying repositories, tags, and digests of artifacts required at the edge.
Within the system, Group Management facilitates the orchestration of artifact distribution by linking specific groups to one or more Satellites. This relationship dictates the permissions of the Satellite's robot account in Harbor and triggers the creation of state artifacts used by the Satellite's replication process.
Sources: CLAUDE.md:85-86, ground-control/internal/server/group_handlers.go:15-30
Group Lifecycle and Synchronization
The lifecycle of a group involves creation through a synchronization process with Harbor, listing, retrieval, and deletion. Group synchronization is the primary mechanism for importing artifact metadata into Ground Control.
Group Creation and Sync
When a group is synced via the /groups/sync endpoint, the system performs a multi-step transactional process:
- Database Persistence: Creates or updates the group entry in the PostgreSQL database with the provided group name and project list.
- Satellite Update: Identifies all Satellites currently associated with that group.
- Permission Management: Updates the Harbor robot accounts for each associated Satellite to ensure they have the necessary project permissions to pull the new artifacts.
- State Artifact Creation: Generates a OCI image containing the group's artifact metadata (JSON) and pushes it to the Harbor registry under the
satellite/group-state/path.
Sources: ground-control/internal/server/group_handlers.go:20-100, ground-control/internal/utils/helper.go:81-125
The diagram above illustrates the sequence of operations performed during a group synchronization event.
Sources: ground-control/internal/server/group_handlers.go:34-97
Data Model: Group
| Field | Type | Description |
|---|---|---|
id | int32 | Unique identifier for the group. |
group_name | string | Human-readable name used for identification and state artifact paths. |
registry_url | string | The source registry URL (Harbor). |
projects | []string | List of Harbor projects associated with this group's artifacts. |
created_at | time.Time | Timestamp when the group was created. |
updated_at | time.Time | Timestamp of the last update or sync. |
Sources: ground-control/internal/database/groups.sql.go:42-49, ground-control/sql/queries/groups.sql:1-10
Satellite-Group Relationships
The system manages a many-to-many relationship between Satellites and Groups through the satellite_groups association table.
Association Logic
When a Satellite is added to a group, Ground Control performs the following actions:
- Link Creation: Inserts a record into the
satellite_groupstable. - Permission Aggregation: Retrieves the full list of groups the Satellite belongs to and aggregates all projects required by those groups.
- Robot Account Sync: Updates the Satellite's Harbor robot account with permissions for the union of all projects.
- Satellite State Update: Updates the "Satellite State Artifact," which tracks the individual group state artifacts the Satellite must follow.
Sources: ground-control/internal/server/satellite_handlers.go:509-588, ground-control/internal/database/satellite_groups.sql.go:11-23
This ER diagram shows the relationship between Satellites and Groups via the join table.
Sources: ground-control/internal/database/satellite_groups.sql.go:37-45, ground-control/sql/queries/groups.sql:20-25
Removal and Deletion
Removing a Satellite from a group or deleting a group entirely requires recalculating permissions for all affected Satellites. If a group is deleted, Ground Control iterates through all associated Satellites, removes their access to the group's projects, and deletes the group's state artifact from the Harbor registry.
Sources: ground-control/internal/server/group_handlers.go:134-222
API Interface
Group Management is exposed through a set of RESTful endpoints.
| Method | Endpoint | Description |
|---|---|---|
POST | /groups/sync | Creates or updates a group and its state artifact. |
GET | /groups | Lists all existing groups. |
GET | /groups/{group} | Retrieves details for a specific group. |
DELETE | /groups/{group} | Deletes a group and updates affected Satellites. |
GET | /groups/{group}/satellites | Lists all Satellites associated with a group. |
POST | /groups/satellite | (Alias) Adds a satellite to a group. |
Sources: ground-control/internal/server/group_handlers.go:15-17, ground-control/internal/server/group_handlers.go:252-254, ground-control/internal/server/satellite_handlers.go:505-507
State Management Architecture
A unique aspect of Group Management in Harbor Satellite is the use of "State Artifacts." Instead of Satellites querying the database directly, Ground Control pushes the group configuration into Harbor as an OCI artifact.
State Artifact Generation
The CreateStateArtifact function marshals the group's artifact list into a JSON file named artifacts.json. This file is then packaged into an OCI image and pushed to a specific repository path.
- Path format:
satellite/group-state/{group_name} - Tag:
latestand a Unix timestamp.
Sources: ground-control/internal/utils/helper.go:76-115
Implementation Example (SQL)
The following query shows how groups are upserted during the sync process to maintain consistency.
-- name: CreateGroup :one
INSERT INTO groups (group_name, registry_url, projects, created_at, updated_at)
VALUES ($1, $2, $3, NOW(), NOW())
ON CONFLICT (group_name)
DO UPDATE SET
registry_url = EXCLUDED.registry_url,
projects = EXCLUDED.projects,
updated_at = NOW()
RETURNING *;
Sources: ground-control/sql/queries/groups.sql:1-10
Conclusion
Group Management acts as the bridge between Harbor's artifact storage and the Satellite's local registry. By abstracting image collections into Groups, Ground Control provides a scalable way to manage artifact distribution, automate robot account permissions, and deliver state updates to edge devices via OCI-native mechanisms.