Skip to main content

Module 4: SPIRE Architecture and Components

How SPIRE implements the SPIFFE specification in production

3.5 hours. 3 hands-on labs. Free course module.

Learning Objectives

  • Understand SPIRE Server and Agent architecture
  • Learn node attestation and workload attestation
  • Configure registration entries
  • Master the SPIRE plugin framework

Why This Matters

SPIRE is the runtime engine behind workload identity. Understanding its internals — Server/Agent separation, attestation flows, registration entries — is the difference between following a tutorial and operating SPIRE confidently in production. When something breaks at 2 AM, you need to know WHERE to look.

SPIRE ARCHITECTURESPIRE ServerCA / Registration API / DatastoreNode Attestation / SVID SigningSPIRE AgentNode 1 (DaemonSet)Workload API socketSPIRE AgentNode 2 (DaemonSet)Workload API socketSPIRE AgentNode 3 (DaemonSet)Workload API socketNode AttestationPod APod BPod CPod DWorkload Attestation
Architecture diagram for Module 4: SPIRE Architecture and Components.

Lesson Content

SPIRE (SPIFFE Runtime Environment) is the production implementation of the SPIFFE specification. It is a CNCF graduated project and the most widely deployed SPIFFE-compliant identity provider. This module takes you inside SPIRE’s architecture.

SPIRE Server

The SPIRE Server is the central control plane. It is responsible for managing registration entries (which workloads get which SPIFFE IDs), performing node attestation (verifying that SPIRE Agents are running on legitimate nodes), signing SVIDs (issuing X.509 certificates and JWTs), maintaining the trust bundle (the CA certificates that verify SVIDs), and storing state in a datastore (SQLite, PostgreSQL, or MySQL).

SPIRE Agent

The SPIRE Agent runs on every node (as a DaemonSet in Kubernetes). It is responsible for performing workload attestation (verifying which process is requesting an identity), exposing the SPIFFE Workload API (Unix domain socket), caching SVIDs for registered workloads, and rotating certificates before they expire.

Node Attestation

When a SPIRE Agent starts, it must prove to the SPIRE Server that it is running on a legitimate node. This is node attestation.

# Kubernetes node attestation:
# Agent presents: Kubernetes service account token
# Server verifies: token with the Kubernetes API server

# AWS node attestation:
# Agent presents: AWS instance identity document
# Server verifies: document with AWS STS

# Azure node attestation:
# Agent presents: Azure MSI token
# Server verifies: token with Azure AD

Workload Attestation

When a workload calls the Workload API, the SPIRE Agent must verify the workload’s identity. This is workload attestation.

# Kubernetes workload attestation:
# Agent inspects: pod namespace, service account, labels, node
# Matches against: registration entries

# Unix workload attestation:
# Agent inspects: PID, UID, GID, binary path
# Matches against: registration entries

Registration Entries

A registration entry maps a set of workload attributes (selectors) to a SPIFFE ID:

# Register a workload:
spire-server entry create \
  -spiffeID spiffe://example.org/ns/default/sa/api-server \
  -parentID spiffe://example.org/agent/node-1 \
  -selector k8s:ns:default \
  -selector k8s:sa:api-server

# This says: any pod in namespace "default" with service account
# "api-server" running on a node attested as "node-1" gets the
# SPIFFE ID spiffe://example.org/ns/default/sa/api-server

SPIRE Plugin Framework

SPIRE uses a plugin architecture for extensibility. Node attestors, workload attestors, key managers, upstream authorities, and datastores are all pluggable. This allows SPIRE to work across cloud providers, orchestrators, and deployment models.

Deployment Models

  • Single cluster: One SPIRE Server, Agents on every node
  • Nested SPIRE: A hierarchy of SPIRE Servers for multi-tier architectures
  • Federated SPIRE: Multiple independent SPIRE deployments that trust each other

Real-World Use Cases

  • Enterprise Kubernetes identity — attesting pods via service accounts
  • VM workload identity — attesting bare-metal servers via cloud instance documents
  • Hybrid cloud — mixed Kubernetes + VM environments sharing one trust domain
  • CI/CD pipeline attestation — build agents receiving ephemeral identities

Production Notes

  • Always use a shared database (PostgreSQL/MySQL) for SPIRE Server in production. SQLite does not support HA.
  • SPIRE Agent should run as a DaemonSet — one per node, not one per pod. It serves all workloads on the node via the Unix socket.
  • Use the k8s_psat node attestor for Kubernetes. It is more secure than join tokens because it leverages Kubernetes projected service account tokens.

Common Mistakes

  • Using SQLite datastore in production (use PostgreSQL for HA)
  • Not enabling debug logging during initial deployment — makes troubleshooting impossible
  • Creating overly broad registration selectors that match unintended workloads
  • Forgetting to create a registration entry before expecting a workload to get an SVID
  • Running SPIRE Agent as a sidecar instead of a DaemonSet (wastes resources, complicates management)

Security Risks to Watch

  • Compromised SPIRE Agent can issue SVIDs for any registered workload on that node
  • Registration entries with overly broad selectors can grant identity to unintended workloads
  • SPIRE Server datastore contains all registration entries — protect it like a CA

Think Like an Engineer

  • Why does SPIRE separate Server and Agent instead of running a single process?
  • What are the security implications of running SPIRE Agent with hostPID access?
  • How would you design registration entries for a microservice application with 50 services across 3 namespaces?

Production Story

A SaaS company deploying SPIRE for the first time used join token attestation in production. Every time a node was replaced by the auto-scaler, someone had to manually generate and deploy a new join token. After switching to k8s_psat attestation, new nodes joined automatically — zero manual intervention, zero downtime.

Key Terms

SPIRE Server
Central control plane that manages registrations and signs SVIDs
SPIRE Agent
Node-local process that exposes the Workload API
Node Attestation
Process of proving an Agent runs on a legitimate node
Workload Attestation
Process of matching a calling process to a registration entry
Registration Entry
Maps selectors (pod attributes) to a SPIFFE ID
Selector
Attribute used to identify workloads (e.g., k8s:ns:default)

Hands-On Labs

  1. Installing SPIRE from Binaries

    Install and run SPIRE Server and Agent on a local machine.

    • Download SPIRE release binaries
    • Configure SPIRE Server with SQLite datastore
    • Configure SPIRE Agent with join token attestor
    • Start the server and agent, verify they connect

    View lab files on GitHub

  2. Configuring Registration Entries

    Register workloads and assign SPIFFE IDs.

    • Create a registration entry for a demo workload
    • Verify the entry with spire-server entry show
    • Run the demo workload and confirm it receives an SVID
    • Inspect the SVID with openssl

    View lab files on GitHub

  3. Attesting Nodes and Workloads

    Observe the full attestation flow.

    • Enable debug logging on SPIRE Server and Agent
    • Restart the agent and observe node attestation logs
    • Run a workload and observe workload attestation logs
    • Intentionally fail attestation and observe the error

    View lab files on GitHub

Key Takeaways

  • SPIRE Server is the control plane — manages registrations and signs SVIDs
  • SPIRE Agent runs on every node — exposes the Workload API to local workloads
  • Node attestation proves the Agent is on a legitimate node
  • Workload attestation proves the calling process matches a registration entry
  • Registration entries map selectors to SPIFFE IDs
  • SPIRE is plugin-based — supports multiple clouds, orchestrators, and datastores