Ground Control API Reference

Relevant source files

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

• ground-control/main.go
• ground-control/internal/utils/helper.go
• deploy/no-spiffe/quickstart.md
• deploy/quickstart/spiffe/join-token/README.md
• taskfiles/e2e.yml
• CLAUDE.md
• scripts/local-test.sh

Ground Control is the cloud-side management service of the Harbor Satellite project. It provides a centralized HTTP API for managing satellite registries, configuring artifact groups, and orchestrating state distribution across edge locations. Sources: CLAUDE.md, ground-control/main.go:23-30

The API facilitates three primary workflows: administrative management of the fleet (Groups, Configs, Satellites), Zero-Touch Registration (ZTR) for new devices, and state replication for edge synchronization. Sources: deploy/no-spiffe/quickstart.md, README.md

API Authentication and Security

Ground Control supports multiple authentication modes depending on the deployment environment. Administrators typically authenticate via a /login endpoint to obtain a Bearer token for management operations. Sources: deploy/no-spiffe/quickstart.md:162-168, taskfiles/e2e.yml:256-262

Satellites authenticate using one of two methods:

1. Token-based ZTR: A single-use token generated by an admin and passed to the satellite via CLI flags or environment variables. Sources: deploy/no-spiffe/quickstart.md:154-160, QUICKSTART.md
2. SPIFFE/SPIRE: Cryptographic identity using X.509 certificates and mTLS. When enabled, Ground Control starts an HTTPS server and validates satellite identities via the SPIFFE Workload API. Sources: ground-control/main.go:42-45, deploy/quickstart/spiffe/join-token/README.md

Satellite Management Endpoints

These endpoints manage the lifecycle of satellite registries within the fleet.

Satellite Registration

Method	Endpoint	Description
POST	/satellites	Registers a new satellite and returns a bootstrap token.
POST	/api/satellites/register	Registers a satellite using SPIFFE attestation methods.
GET	/api/satellites	Lists all registered satellites and their current status.

Sources: deploy/no-spiffe/quickstart.md:154-160, deploy/quickstart/spiffe/join-token/README.md:120-135, taskfiles/e2e.yml:264-272

Registration Logic

When a satellite is registered, Ground Control performs the following internal operations:

1. Creates a database record for the satellite.
2. Provisions a Robot Account in the upstream Harbor registry with scoped permissions.
3. Generates a state artifact in Harbor representing the satellite's assigned configuration.

Sources: ground-control/internal/utils/helper.go:61-70, deploy/quickstart/spiffe/join-token/README.md:118-120

Artifact Group Management

Groups define sets of container images and metadata that satellites must replicate.

Group Endpoints

Endpoint	Method	Description
/groups/sync	POST	Creates or updates a group and synchronizes its state to Harbor.
/api/groups/satellite	POST	Assigns a specific group to a satellite.

Sources: deploy/no-spiffe/quickstart.md:104-122, deploy/quickstart/spiffe/join-token/README.md:255-260, scripts/local-test.sh:111-125

Group Synchronization Flow

Ground Control serializes group definitions into a JSON file (artifacts.json), wraps it in an OCI image layer, and pushes it to a special satellite project in Harbor. Satellites then pull this "State Artifact" to determine which images to replicate locally. Sources: ground-control/internal/utils/helper.go:103-156, CLAUDE.md

Configuration Management

Configurations define how satellites operate, including log levels, replication intervals, and local registry (Zot) settings.

Configuration Endpoints

Endpoint	Method	Description
/configs	POST	Creates a named configuration object.
/api/configs/satellite	POST	Associates a configuration with a specific satellite.

Sources: deploy/no-spiffe/quickstart.md:126-152, deploy/quickstart/spiffe/join-token/README.md:225-230

Config Structure

The config object includes app_config and zot_config. Ground Control validates these fields (e.g., cron expressions for replication intervals) before persistence. Sources: pkg/config/validate.go:14-50, scripts/local-test.sh:137-160

{
  "config_name": "production-edge",
  "config": {
    "app_config": {
      "log_level": "info",
      "state_replication_interval": "@every 00h00m30s",
      "local_registry": { "url": "http://0.0.0.0:8585" }
    },
    "zot_config": {
      "storage": { "rootDirectory": "./zot-data" },
      "http": { "address": "0.0.0.0", "port": "8585" }
    }
  }
}

Example request payload for configuration creation. Sources: deploy/no-spiffe/quickstart.md:126-152, scripts/local-test.sh:137-160

System Health and Infrastructure

Ground Control provides standard observability endpoints and performs prerequisite checks on startup.

Endpoint	Method	Description
/health	GET	Returns 200 if the service and database are reachable.
/ping	GET	Simple connectivity check (often used for mTLS verification).

Sources: ground-control/main.go:23-26, deploy/quickstart/spiffe/join-token/README.md:108-110, scripts/local-test.sh:97-103

Startup Sequence

1. Harbor Health Check: Verifies connectivity to the upstream Harbor registry.
2. Database Migration: Automatically runs SQL migrations for the PostgreSQL backend.
3. Background Jobs: Starts the cleanup job for expired sessions or tokens.
4. Server Start: Launches the HTTP/HTTPS listener.

Sources: ground-control/main.go:23-40, CLAUDE.md

Summary

The Ground Control API acts as the orchestration hub for the Harbor Satellite ecosystem. By abstracting complex Harbor operations (robot account creation, OCI-based state distribution) into a simplified fleet management API, it enables administrators to manage thousands of edge registries through groups and configurations. It supports both high-security production environments via SPIFFE/mTLS and simplified testing via token-based registration. Sources: README.md, QUICKSTART.md, ground-control/main.go