CodersSecret

Module 4 of 13

SPIRE Architecture and Components

How SPIRE implements the SPIFFE specification in production

3.5 hours3 labsFree
Watch as Slides Course overview Lab code

Start here

Learning objectives

  • Understand SPIRE Server and Agent architecture
  • Learn node attestation and workload attestation
  • Configure registration entries
  • Master the SPIRE plugin framework
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

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

Where this shows up

  • 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

Keep these close

  • 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

What usually breaks

  • 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

Threats 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

Questions to answer before shipping

  • 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?

Key terms

Vocabulary used in this module

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)

Labs

Hands-on labs

Installing SPIRE from Binaries

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

  1. Download SPIRE release binaries
  2. Configure SPIRE Server with SQLite datastore
  3. Configure SPIRE Agent with join token attestor
  4. Start the server and agent, verify they connect
View lab on GitHub

Configuring Registration Entries

Register workloads and assign SPIFFE IDs.

  1. Create a registration entry for a demo workload
  2. Verify the entry with spire-server entry show
  3. Run the demo workload and confirm it receives an SVID
  4. Inspect the SVID with openssl
View lab on GitHub

Attesting Nodes and Workloads

Observe the full attestation flow.

  1. Enable debug logging on SPIRE Server and Agent
  2. Restart the agent and observe node attestation logs
  3. Run a workload and observe workload attestation logs
  4. Intentionally fail attestation and observe the error
View lab on GitHub

Recap

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

Related resources

Keep learning across CodersSecret

Related guides

Read practical engineering walkthroughs that connect this lesson to real systems.

Cheatsheets

Keep command references and production checklists close while you practice.

Interactive labs

Practice infrastructure decisions through short, scenario-driven exercises.

Glossary terms

Build the vocabulary needed to explain architecture clearly in reviews.