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 registry modes. Pick the combination that fits your environment.

Authentication: Token-based vs SPIFFE

• Token-based - Ground Control issues a static token when you register a satellite. Pass it to the satellite binary with --token. 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.

Registry: Embedded Zot vs BYO

• Embedded Zot (default) - Satellite runs an embedded Zot OCI registry. No external registry needed. Images are stored locally and served to workloads.

• Bring Your Own (BYO) Registry - Point satellite at an existing registry with --byo-registry --registry-url <url>. Satellite replicates images to your registry instead of running its own.

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[Embedded Zot]
    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]
        Zot[Zot Registry]
    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 --> Zot

Supported Platforms

Built from the GoReleaser configuration:

Package formats: tar.gz, rpm, deb, apk, archlinux.

Container images:

• 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 its registry as a mirror. Workloads pull from the local registry first, falling back to the upstream registry.

Usage:

satellite --mirrors=containerd:docker.io,quay.io --mirrors=podman:docker.io

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