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

This lab gives each student a SPIFFE trust domain of their own. SPIFFE is a standard way to give a running program, a workload, an identity instead of a shared password, and SPIRE is the software that hands those identities out. The student’s Ubuntu VM runs a SPIRE server, a SPIRE agent and a one-node Kubernetes cluster, k3s, and the student works with the real spire-server, spire-agent and kubectl commands.

They register workloads, fetch short-lived certificates called SVIDs, watch a service refuse a caller with no identity at the TLS handshake, and give a Kubernetes pod an identity by its namespace and service account. Nothing is installed on the student’s computer and nothing is shared with other students.

What students learn

Why an identity that a workload proves while it runs is safer than a secret copied into a file. What a SPIFFE ID and a trust domain are, and how an X.509-SVID and a JWT-SVID carry one. How the agent proves its machine to the server (node attestation, here by x509pop) and finds out what a calling process is (workload attestation, by Unix user and by Kubernetes pod). How to register a workload with the right selectors, how two services use their SVIDs for mutual TLS with an allow-list of SPIFFE IDs, and how SVIDs rotate and trust domains federate. The module Workload identity with SPIFFE and SPIRE is worked in it.

What is in the machine

SPIRE version 1.15.5 and k3s version 1.35, installed by the lab’s setup from the projects’ public releases on GitHub, pinned by the checksums the releases publish; any other file is refused. The SPIRE server and agent run on the VM as system services, with the trust domain lab.test, and pods reach the agent through its socket, mounted into each pod. Two small services written for the lab in Python, billing and catalogue, each fetch their own SVID every 15 seconds and serve mutual TLS. Unix users stand for workloads.

A student’s VM reaches Ubuntu’s package archive, PyPI, npm and GitHub, and no image registry, so every pod runs busybox, the image that comes with k3s.

Run it in your browser

VM labs are set as a lab task in a module, and the sample is on the lab’s page. The machine asks for 2 CPUs, 2 GB of memory and 10 GB of disk.

  1. Add the lab. In a module you teach, add a task and choose the Ubuntu VM lab card. The page shows a short description of the machine instead of a compose file.
  2. Start from the sample. The page offers ready-made labs to start from. Choose Workload identity with SPIFFE and SPIRE. Using a sample replaces the text, and Undo brings yours back.
  3. Publish and start your own copy. Publish, then Start. The lab’s own setup script installs SPIRE and k3s from their public GitHub releases the first time the VM starts, about 300 MB, and writes the spirelab command, two small services, a Deployment to work on and the README. Everything is ready a few minutes later.
  4. Open the terminal. Open its terminal, run spirelab status until the server and the agent are healthy, and read README.md in the home folder: it says what to do in four parts and gives none of the answers.

Who can run it

k3s needs 2 GB, which a college account’s machine has. A free account’s machine has 1 GB, so the setup installs SPIRE without k3s and says so: everything but the part with pods works. A visitor with no account reaches Ubuntu’s archive alone, so SPIRE cannot be downloaded at all. Set the lab for a class in a college.

A basic lesson on this lab

Workload Identity Basics is a small lesson worked in this lab, which is an Ubuntu VM. It has a hook, an I can outcome, key words, a starter, a check after each idea, a common mistake and an exit check, and each step has a Run button that types its command into the machine’s terminal. A student asks how SPIRE stands, sees a workload nobody registered get nothing, registers it, fetches its SVID and reads the SPIFFE ID inside it with OpenSSL.

It uses a user of its own and leaves the lab’s own task to the student, so it hands out no answers.

How it is marked

The lab has a check. It runs on a copy of the saved machine after a fresh start, waits for SPIRE and k3s, and asks them, not the files. The user billing must get exactly the ID spiffe://lab.test/billing and the user orders exactly spiffe://lab.test/orders; the user visitor, and a user the check makes with a name nobody has seen, must get nothing. orders must be allowed to call billing over mutual TLS, and visitor must be refused at the handshake. The Deployment reports in the namespace payments must get its ID, a pod the check starts with a new name under the same service account must get the same ID, and a pod under the namespace’s default account must get nothing. The first line of what the check printed says why it did not pass.

  1. Hand it out. Assign the lab like any task, with a due date if you want one. Each student gets a VM of their own, kept between sessions, and SPIRE’s registrations are on its disk.
  2. Run the check. On a student’s row in the class list, press Run the check. It starts a copy of their saved machine that is not saved back, waits for SPIRE and the cluster, asks them and shows whether it passed, what it printed and when. The student is not told the result.
  3. Mark it. Read the first line of what the check printed: it says what is not right, such as a user who gets two identities, a caller billing does not allow, or an entry that also reaches a pod under another account. Send the work back with a reason if it needs more.

The definition on GitHub

The file is the whole lab definition, the same text the platform runs: size, setup script, the spirelab command, the SPIRE configuration, the two services, the Deployment to work on, README and check. Copy it and change the workloads or the allow-lists to make a longer lab.

Try this lab, and what it costs

A free personal account can work through the basic lessons in this lab, with enough free credit each month to follow most lessons and no card. For a class, a school or college has its first 365 days free for up to 50 students, then pays per student a year, with every lab included and staff free.

Questions people ask

Does the workload identity lab need a licence?
No. SPIRE and k3s are open source under the Apache 2.0 licence and are downloaded from the projects’ own releases when the student’s VM starts; nothing of them is distributed by us.
Why does SPIRE run on the VM and not in the cluster?
A student’s VM reaches no image registry, so SPIRE’s container images cannot be pulled. Running the server and agent as services on the node is also a real way to deploy them: the agent still attests pods by asking the kubelet, exactly as it would in a pod of its own.
Is federation part of the lab?
It is explained in the module and the trust bundle is shown in the format a federated server fetches, but the lab runs one trust domain, so no federation is set up.
Can students harm anything?
Only their own copy. Every identity in it belongs to the lab’s own trust domain, made when the lab first starts and trusted by nothing outside it, and the VM reaches Ubuntu’s archive, PyPI, npm and GitHub and nothing else.
Was the lab tested in a real student VM?
The setup with its real downloads, the lessons’ commands and the check, with several ways of getting it wrong, were run in a real Ubuntu 26.04 with SPIRE and k3s running, in a container standing in for the VM. A booted student VM, which starts the services from systemd, with the platform’s own network proxy, is worth one try before a class.