129 lines
6.1 KiB
Markdown
129 lines
6.1 KiB
Markdown
# SPIRE Architecture
|
|
|
|
> Source: https://spiffe.io/docs/latest/spire-about/spire-concepts/
|
|
> Note: https://raw.githubusercontent.com/spiffe/spire/main/doc/architecture.md was empty; this document
|
|
> is derived from the official SPIRE Concepts documentation on spiffe.io.
|
|
> Downloaded: 2026-06-07
|
|
|
|
## Overview
|
|
|
|
SPIRE is a production-ready implementation of the SPIFFE APIs that performs node and workload attestation in order to securely issue SVIDs to workloads, and verify the SVIDs of other workloads, based on a predefined set of conditions.
|
|
|
|
## SPIRE Architecture and Components
|
|
|
|
A SPIRE deployment is composed of a **SPIRE Server** and one or more **SPIRE Agents**.
|
|
|
|
- A server acts as a signing authority for identities issued to a set of workloads via agents.
|
|
- It also maintains a registry of workload identities and the conditions that must be verified in order for those identities to be issued.
|
|
- Agents expose the SPIFFE Workload API locally to workloads, and must be installed on each node on which a workload is running.
|
|
|
|
## The SPIRE Server
|
|
|
|
A SPIRE Server is responsible for managing and issuing all identities in its configured SPIFFE trust domain. It:
|
|
|
|
- Stores registration entries (which specify the selectors that determine the conditions under which a particular SPIFFE ID should be issued)
|
|
- Stores signing keys
|
|
- Uses node attestation to authenticate agents' identities automatically
|
|
- Creates SVIDs for workloads when requested by an authenticated agent
|
|
|
|
### Server Plugin Types
|
|
|
|
- **Node attestor plugins** - verify the identity of the node the agent is running on
|
|
- **Datastore plugins** - store, query, and update registration entries, attested nodes, and selectors (MySQL, SQLite 3, or PostgreSQL)
|
|
- **Key manager plugins** - control how the server stores private keys used to sign SVIDs
|
|
- **Upstream authority plugins** - use a different CA from a different PKI system
|
|
|
|
## The SPIRE Agent
|
|
|
|
A SPIRE Agent runs on every node on which an identified workload runs. The agent:
|
|
|
|
- Requests SVIDs from the server and caches them until a workload requests its SVID
|
|
- Exposes the SPIFFE Workload API to workloads on node
|
|
- Attests the identity of workloads that call it
|
|
- Provides the identified workloads with their SVIDs
|
|
|
|
### Agent Plugin Types
|
|
|
|
- **Node attestor plugins** - verify the identity of the node the agent is running on
|
|
- **Workload attestor plugins** - verify the identity of the workload process on the node
|
|
- **Key manager plugins** - generate and use private keys for X.509-SVIDs issued to workloads
|
|
|
|
## A Day in the Life of an SVID
|
|
|
|
1. The SPIRE Server starts up and generates a self-signed certificate (unless UpstreamAuthority is configured)
|
|
2. The server generates a trust bundle and stores it in the datastore
|
|
3. The server turns on its registration API
|
|
4. The SPIRE Agent starts up on the node
|
|
5. The agent performs **node attestation** to prove the identity of the node
|
|
6. The agent presents proof of identity to the server over a TLS connection
|
|
7. The server validates the proof (e.g., via AWS API for EC2 IID)
|
|
8. The server issues an SVID to the agent representing its own identity
|
|
9. The agent contacts the server to obtain authorized registration entries
|
|
10. The agent sends workload CSRs to the server; server signs and returns SVIDs
|
|
11. Agent caches SVIDs and starts listening on the Workload API socket
|
|
12. A workload calls the Workload API to request an SVID
|
|
13. The agent initiates workload attestation by calling workload attestors with the process ID
|
|
14. Attestors query the kernel and userspace for workload information
|
|
15. The agent compares discovered selectors against registration entries
|
|
16. The agent returns the correct SVID from its cache to the workload
|
|
|
|
## SPIRE Concepts
|
|
|
|
### Workload Registration
|
|
|
|
Workload registration tells SPIRE how to identify the workload and which SPIFFE ID to give it. A registration entry maps:
|
|
- A SPIFFE ID (the identity)
|
|
- A set of selectors (properties the workload must possess)
|
|
|
|
### Attestation
|
|
|
|
SPIRE performs attestation in two phases:
|
|
1. **Node attestation** - verifies the identity of the node
|
|
2. **Workload attestation** - verifies the workload on the node
|
|
|
|
### Node Attestation
|
|
|
|
Node attestors interrogate a node and its environment for pieces of information that only that node would possess. The result is that the agent receives a unique SPIFFE ID.
|
|
|
|
**Supported node attestors:**
|
|
- EC2 instances on AWS (AWS Instance Identity Document)
|
|
- VMs on Microsoft Azure (Azure Managed Service Identities)
|
|
- Google Compute Engine Instances on GCP (GCE Instance Identity Tokens)
|
|
- Kubernetes cluster nodes (Kubernetes Service Account tokens)
|
|
- Server-generated join tokens (pre-shared key, expires after use)
|
|
- Existing X.509 certificates
|
|
|
|
#### Node Attestation Steps
|
|
|
|
1. The agent node attestor plugin queries the platform for proof of the node's identity
|
|
2. The agent passes this proof of identity to the server
|
|
3. The server node attestor validates proof independently or via a platform API
|
|
4. The node attestor creates a SPIFFE ID for the agent and passes it back with selectors
|
|
5. The server sends back an SVID for the agent node
|
|
|
|
### Workload Attestation
|
|
|
|
Workload attestation answers "Who is this process?" by interrogating locally available authorities:
|
|
|
|
- OS kernel (uid, gid, filesystem path)
|
|
- Kubernetes kubelet (Service Account, namespace)
|
|
- Docker
|
|
|
|
#### Workload Attestation Steps
|
|
|
|
1. A workload calls the Workload API (Unix Domain Socket on Unix systems)
|
|
2. The agent interrogates the kernel to identify the process ID of the caller
|
|
3. Agent invokes workload attestor plugins with the process ID
|
|
4. Attestors query platform-specific components (e.g., kubelet) for workload info
|
|
5. Attestors return discovered information to the agent as selectors
|
|
6. The agent compares selectors to registration entries and returns the correct SVID
|
|
|
|
### Authorized Registration Entries
|
|
|
|
The server only sends authorized registration entries to the agent by:
|
|
|
|
1. Querying for registration entries with the agent's SPIFFE ID as "parent SPIFFE ID"
|
|
2. Querying for node selectors associated with the specific agent
|
|
3. Querying for registration entries that declare any of those node selectors
|
|
4. Recursively querying for children of all obtained entries
|