# 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
