SPIRE Setup & Configuration
Relevant source files
The following files were used as context for generating this wiki page:
- deploy/quickstart/spiffe/README.md
- deploy/quickstart/spiffe/join-token/README.md
- deploy/quickstart/spiffe/sshpop/README.md
- deploy/quickstart/spiffe/x509pop/README.md
- ground-control/internal/spiffe/embedded_server.go
- deploy/quickstart/spiffe/join-token/external/gc/docker-compose.yml
- internal/spiffe/client.go
Harbor Satellite utilizes the SPIFFE (Secure Production Identity Framework for Everyone) standard, implemented via SPIRE (the SPIRE Runtime Environment), to establish zero-trust identity between Ground Control (GC) and Satellite instances. This framework enables cryptographic identity verification, automatic certificate rotation, and mutual TLS (mTLS) for all communications.
The integration supports multiple attestation methods, allowing agents to prove their identity to the SPIRE server through one-time tokens, pre-provisioned X.509 certificates, or SSH host certificates. This setup ensures that only authorized workloads can participate in the registry fleet management and artifact distribution process.
Sources: deploy/quickstart/spiffe/README.md:3-5, QUICKSTART.md:46-51
SPIFFE Architecture
The SPIRE architecture in Harbor Satellite consists of a central SPIRE Server acting as the trust root and SPIRE Agents residing alongside Ground Control and Satellite workloads. Agents communicate with the server to receive SVIDs (SPIFFE Verifiable Identity Documents) in X.509 format, which are then used by the workloads for mTLS.
The diagram above illustrates the relationship between the central authority and edge agents.
Sources: deploy/quickstart/spiffe/README.md:27-41, QUICKSTART.md:28-43
Deployment Modes
Harbor Satellite supports two primary deployment modes for the SPIRE infrastructure:
External SPIRE (Current)
In this mode, the SPIRE server and agents run as separate containers alongside Ground Control and Satellite components. This is the recommended approach for Phase 1 of the project.
Sources: deploy/quickstart/spiffe/README.md:15-18
Embedded SPIRE (Planned)
Planned for Phase 2, this mode embeds the SPIRE server and agent logic directly into the Ground Control and Satellite binaries, simplifying the deployment by removing the need for auxiliary containers.
Sources: deploy/quickstart/spiffe/README.md:20-23, ground-control/internal/spiffe/embedded_server.go:27-33
Attestation Methods
The system supports three primary methods for node attestation, summarized in the table below:
| Method | Description | Use Case |
|---|---|---|
| Join Token | One-time tokens generated by the SPIRE server. | Development, testing, and CI/CD environments. |
| X.509 PoP | Proof of Possession using pre-provisioned certificates signed by a trusted CA. | Production environments with existing PKI infrastructure. |
| SSH PoP | Proof of Possession using SSH host certificates signed by a trusted SSH CA. | Environments with existing SSH certificate infrastructure. |
Sources: deploy/quickstart/spiffe/README.md:7-13, QUICKSTART.md:53-61
Join Token Attestation Flow
The Join Token method is the simplest for bootstrapping. A token is generated on the server and provided to the agent configuration. Once used, the token is invalidated.
The sequence shows the one-time registration process for a new agent.
Sources: deploy/quickstart/spiffe/join-token/README.md:5-9, deploy/quickstart/spiffe/join-token/README.md:121-140
Configuration Parameters
SPIRE Agent Runtime Configuration
The agent requires a configuration file (e.g., agent.conf) to communicate with the SPIRE server.
agent {
data_dir = "/opt/spire/data/agent"
log_level = "INFO"
server_address = "spire-server"
server_port = "8081"
socket_path = "/run/spire/sockets/agent.sock"
trust_bundle_path = "/opt/spire/conf/agent/bootstrap.crt"
trust_domain = "harbor-satellite.local"
join_token = "YOUR_TOKEN_HERE"
}
plugins {
NodeAttestor "join_token" {}
KeyManager "disk" {
plugin_data { directory = "/opt/spire/data/agent" }
}
WorkloadAttestor "docker" {
plugin_data { docker_socket_path = "unix:///var/run/docker.sock" }
}
}
Sources: deploy/quickstart/spiffe/join-token/README.md:40-84, deploy/quickstart/spiffe/join-token/external/gc/docker-compose.yml:51-78
Environment Variables for Ground Control
When SPIFFE is enabled, Ground Control requires specific variables to locate the SPIRE agent and server.
| Variable | Description | Default Value |
|---|---|---|
SPIFFE_ENABLED | Enables SPIFFE identity verification. | true |
SPIFFE_ENDPOINT_SOCKET | Path to the SPIRE Agent Workload API socket. | unix:///run/spire/sockets/agent.sock |
SPIFFE_TRUST_DOMAIN | The SPIFFE trust domain for the fleet. | harbor-satellite.local |
SPIRE_SERVER_ADDRESS | Address of the SPIRE Server for registration. | spire-server |
SPIRE_SERVER_PORT | Port for the SPIRE Server API. | 8081 |
Sources: deploy/quickstart/spiffe/join-token/external/gc/docker-compose.yml:95-101
Satellite Registration and Workload Entries
Workloads must be registered in the SPIRE server to receive identities. Registration associates a SPIFFE ID with a set of selectors (e.g., Docker labels).
Automatic Registration via GC API
When a satellite is registered through the Ground Control API, the system automatically creates the necessary SPIRE workload entries.
- Endpoint:
POST /api/satellites/register - Payload:
{ "satellite_name": "edge-01", "selectors": ["docker:label:com.docker.compose.service:satellite"], "attestation_method": "join_token" } - Behavior: GC generates the join token, creates the SPIRE entry with the appropriate
parentIDandspiffeID, and returns the connection details to the satellite.
Sources: deploy/quickstart/spiffe/join-token/README.md:104-125, deploy/quickstart/spiffe/x509pop/README.md:105-115
Identity Formats
The system uses standardized SPIFFE ID formats to identify components:
- Ground Control:
spiffe://harbor-satellite.local/ground-control - Satellite:
spiffe://harbor-satellite.local/satellite/region/<region>/<name> - Agents (Join Token):
spiffe://harbor-satellite.local/agent/<name> - Agents (X.509/SSH):
spiffe://harbor-satellite.local/spire/agent/<method>/<fingerprint>
Sources: deploy/quickstart/spiffe/join-token/README.md:129-130, deploy/quickstart/spiffe/x509pop/README.md:73-75, deploy/quickstart/spiffe/sshpop/README.md:65-68
Summary
The SPIRE setup in Harbor Satellite provides a robust foundation for secure, unattended operations at the edge. By leveraging SPIFFE SVIDs, the system eliminates the need for long-lived shared secrets, instead relying on short-lived, automatically rotated X.509 certificates for all inter-component authentication and encryption. This architecture supports diverse environment requirements through flexible attestation methods while maintaining a unified identity model across the fleet.