Overview

Harbor Satellite extends Harbor to edge computing environments. For a full introduction, see the home page. This page covers deployment options, supported platforms, and how to choose the right setup for your environment.

Deployment Models

Harbor Satellite supports two authentication flows and two storage modes. Pick the combination that fits your environment.

Authentication: Token-based vs SPIFFE

• Token-based - Ground Control issues a single-use registration token (valid for 24 hours) when you register a satellite. Pass it to the satellite binary with --token. The satellite exchanges it once for Harbor robot credentials. Best for development, testing, and simple deployments where managing SPIFFE infrastructure is unnecessary.

• SPIFFE/SPIRE - Zero-trust identity using X.509 SVIDs. A SPIRE server issues cryptographic identities to satellites via SPIRE agents. Ground Control verifies identity over mTLS and automatically provisions Harbor robot account credentials. Best for production, multi-tenant, or security-sensitive environments.

Storage: Local OCI Layout vs BYO

• Local OCI layout (default) - Satellite copies OCI content into a persistent image layout using ORAS, stored at <config-dir>/oci (default ~/.config/satellite/oci, override with --registry-data-dir). No external registry is needed, but the layout is not a registry endpoint: container runtimes cannot pull from it.

• Bring Your Own (BYO) Registry - Point satellite at an existing registry with --byo-registry --registry-url <url>. Satellite replicates images to that registry instead of the local layout.

Choosing a Deployment Model

flowchart TD
    A[Start] --> B{Environment?}
    B -->|Dev / Test| C[Token-based auth]
    B -->|Production| D[SPIFFE/SPIRE auth]
    C --> E{Existing registry?}
    D --> E
    E -->|No| F[Local OCI layout]
    E -->|Yes| G[BYO Registry]
    F --> H[Ready to install]
    G --> H

Component Architecture

Harbor Satellite has cloud-side and edge-side components that communicate over HTTPS (token-based) or mTLS (SPIFFE).

graph LR
    subgraph Cloud
        Harbor[Harbor Registry]
        GC[Ground Control]
        PG[(PostgreSQL)]
        SpireServer[SPIRE Server]
        SpireAgentGC[SPIRE Agent]
    end

    subgraph Edge
        SpireAgentSat[SPIRE Agent]
        Satellite[Satellite]
        OCI[(OCI Image Layout)]
    end

    GC --> PG
    GC <--> Harbor
    SpireServer --- SpireAgentGC
    SpireAgentGC -.->|SVID| GC
    SpireServer --->|attestation| SpireAgentSat
    SpireAgentSat -.->|SVID| Satellite
    Satellite <-->|mTLS or HTTPS| GC
    Satellite -->|pull images| Harbor
    Satellite --> OCI

Supported Platforms

Built from the GoReleaser configuration:

Package formats: tar.gz, rpm, deb, apk, archlinux. Release archives are versioned: harbor-satellite_<version>_linux_amd64.tar.gz contains satellite, and groundcontrol_<version>_linux_amd64.tar.gz contains groundcontrol. Use groundcontrol serve to run the server, or groundcontrol <command> to administer it.

Container images (tags latest and release versions without a v prefix, for example 0.0.6), built for linux/amd64, arm64, ppc64le, riscv64 and s390x:

• Satellite: registry.goharbor.io/harbor-satellite/satellite
• Ground Control: registry.goharbor.io/harbor-satellite/ground-control

Supported Container Runtimes

Satellite can configure local container runtimes to use an external BYO registry as a mirror. The default local OCI layout is not addressable by a container runtime, so mirror configuration is skipped unless BYO mode provides a registry endpoint.

Usage:

satellite --byo-registry --registry-url registry.edge:5000 \
  --mirrors=containerd:docker.io,quay.io --mirrors=podman:docker.io ...

Without --byo-registry, Satellite prints warning: CRI registry fallback requires --byo-registry until a registry proxy is configured and leaves runtime configs untouched.

Docker only supports mirroring docker.io. Use --mirrors=docker:true to enable.

SPIFFE Attestation Methods

When using SPIFFE/SPIRE, the SPIRE agent at the edge must attest (prove its identity) to the SPIRE server. Three methods are supported:

flowchart LR
    subgraph join-token [Join Token]
        JT1[SPIRE Server generates token]
        JT2[Token sent to edge agent]
        JT3[Agent attests with token]
        JT4[Token invalidated after use]
        JT1 --> JT2 --> JT3 --> JT4
    end

    subgraph x509pop [X.509 PoP]
        X1[PKI issues certificate]
        X2[Certificate provisioned on edge]
        X3[Agent proves possession]
        X1 --> X2 --> X3
    end

    subgraph sshpop [SSH PoP]
        S1[SSH CA issues host cert]
        S2[Cert deployed on edge host]
        S3[Agent proves possession]
        S1 --> S2 --> S3
    end

Next Steps

• Installation - Install Ground Control and Satellite
• Architecture - Detailed flow of all components
• Quickstart - End-to-end SPIFFE deployment walkthrough