Easier to read with cream paper, a tint, more contrast or larger text? Choose your colours and text, once, for every page.

Free lesson

SPIRE node and workload attestation

After this lesson: I can work out which registration entries match a workload from its selectors.

70 min lesson4 commandsWorkload identity lab: SPIFFE and SPIRE on k3s, with mTLS between services, on a private Ubuntu VM

Who vouches for the machine?

Attestation in SPIRE means proving what something is before it gets an identity. It happens twice: once for the machine, once for each program on it.

If an attacker could start a fake agent, every identity it handed out would be fake too. So the agent must prove its own machine before the server trusts anything it says.

By the end of this lesson

Note

I can work out which registration entries match a workload from its selectors.

Key words

WordWhat it meansExample
Node attestationthe agent proving its machine to the server
Workload attestationthe agent finding out what a calling process is
Selectorone fact about a node or workloadunix:user:basket
x509popnode attestation by holding a key a known CA certified
Join tokena one-use code that lets one agent attest
Parent IDthe agent an entry belongs to

The cells students fill in are left blank in this preview.

Node attestation: the agent proves its machine

Each SPIRE agent first proves the machine it runs on. In a cloud this can be the provider's signed instance document. In Kubernetes it can be a projected service account token.

This lab uses x509pop: at setup a small CA signed a certificate for the node. The agent proves it holds that certificate's key, and the server trusts the CA. The agent's ID is then built from the certificate's common name.

Read the node's certificate

Command
openssl x509 -in /etc/spire/node.pem -noout -subject -issuer

Shown here, not run. Press Start lab to type it into your own lab’s terminal.

See the agent as the server does

Command
sudo spire-server agent show -spiffeID spiffe://lab.test/spire/agent/x509pop/spire-lab

Shown here, not run. Press Start lab to type it into your own lab’s terminal.

What the server knows about the node

The certificate prints subject=CN=spire-lab and issuer=CN=lab node CA. The agent ID ends in /x509pop/spire-lab because of that common name.

The agent's record ends with three node selectors. x509pop:subject:cn:spire-lab is the same everywhere. The CA fingerprint and the serial number differ in every copy, because each lab made its own keys.

A join token works once

Where a machine has nothing to prove itself with, an operator can make a join token. One agent may use it once to attest, and then it is spent.

The next Run makes one for a spare node. It prints Token: and a random value, different every time. Nothing uses it here, so it simply expires. Unlike x509pop, a token cannot attest the same node again after a restart.

Make a one-use join token

Command
sudo spire-server token generate -spiffeID spiffe://lab.test/node/spare

Shown here, not run. Press Start lab to type it into your own lab’s terminal.

Workload attestation: the agent asks the kernel

A workload calls the agent over a Unix socket. The kernel tells the agent the caller's process ID, so the caller cannot lie about it. Plugins then turn that process into selectors.

The unix plugin gives the user, uid, group, gid and the program's path. The k8s plugin asks the kubelet which pod the process is in. An entry matches when every one of its selectors is among the workload's.

Worked example: does the entry match?

Entry selectorsWorkload hasMatch?
unix:user:basketunix:user:basket, unix:uid:1006, ...Yes
unix:user:basket, unix:uid:0unix:user:basket, unix:uid:1006, ...No: uid 0 is missing
unix:path:/usr/bin/python3.14any user running that programYes, for all of them
k8s:ns:demo, k8s:sa:printera pod in demo under printerYes

The cells students fill in are left blank in this preview.

Read basket's entry again

Command
sudo spire-server entry show -spiffeID spiffe://lab.test/basket

Shown here, not run. Press Start lab to type it into your own lab’s terminal.

A common mistake

Warning

Many people think more selectors make an entry match more workloads. It is the opposite: a workload must have every selector, so each one you add narrows the entry. One broad selector, such as a program's path, can give an ID to every user.

About this lab and its source: Workload identity lab: SPIFFE and SPIRE on k3s, with mTLS between services, on a private Ubuntu VM

Teaching a class? Set this module for your students with a teacher guide, marked assignments and a lab for every student.