Enabling Secure Boot and TPM in k3OS: A Practical Guide for Edge Clusters

Why Secure Boot Matters on Edge Nodes

Edge deployments often run in environments where physical access is limited but tampering is still a risk. Without a hardware root of trust, a compromised node could load unsigned kernel modules or malicious init scripts, undermining the entire cluster. k3OS mitigates this by shipping a signed kernel, initramfs, and integrating with TPM 2.0 for node attestation.

Key Feature Summary

• UEFI Secure Boot automatically enabled when a TPM 2.0 device is detected.
• Public key for image verification injected into firmware during installation.
• TPM holds a machine‑specific attestation key for cluster‑level integrity checks.
• Standard k3s operation is unaffected; container runtime remains fully functional.

Enabling Secure Boot During Installation

1. Prepare the machine: Ensure the firmware is UEFI and a TPM 2.0 chip is present. Verify with tpm2_getcap properties-variable if the OS can see the device.
2. Run the k3OS installer:

   curl -L https://github.com/k3os/k3os/releases/download/v1.8.0/k3os-installer | sudo sh -s -- --tpm
   

   The --tpm flag tells the installer to enroll the k3OS public key into the UEFI key store and configure the TPM for attestation.
3. Set a Secure Boot password when prompted. Store it securely; losing it will prevent booting with Secure Boot enabled.

Verifying the Feature is Active

After the node reboots, run the following checks from a shell with sudo privileges.

# 1. Confirm Secure Boot state
mokutil --sb-state
# Expected output: SecureBoot enabled

# 2. Inspect firmware variable
cat /sys/firmware/efi/efivars/secureboot | head
# Look for a non‑empty payload

# 3. Verify TPM functionality
sudo tpm2_getrandom 16 | hexdump -C
# Should return 16 random bytes

# 4. List loaded kernel modules and check signatures
for m in /lib/modules/$(uname -r)/*.ko; do
    modinfo -F license $m | grep -q GPL || echo "Unsigned module: $m"
done
# No output means all modules are signed

Additionally, k3os status will log a message during boot if Secure Boot was detected, e.g., Secure Boot: enabled; TPM key store initialized.

Trade‑offs and Limitations

• Module Signing: Any kernel module that isn’t signed by the same key will fail to load. Devices that rely on third‑party modules (e.g., NVMe‑over‑TCP drivers) may need to be signed or disabled.
• Hardware Compatibility: Older boards without TPM 2.0 or UEFI firmware cannot boot k3OS with Secure Boot. The installer falls back to a non‑secure boot path, but the node will lack the hardware root of trust.
• Cluster Admission: Nodes that present attestation data must be accepted by the cluster’s admission controller. If the controller isn’t configured to verify the TPM attestation, the node may be rejected.
• Recovery: If the TPM key store is corrupted, the node may fail to boot. A full re‑enrollment via the installer is required.

Actionable Checklist

1. Confirm UEFI + TPM 2.0 support on target hardware.
2. Run the installer with --tpm and store the Secure Boot password.
3. After boot, run the verification commands above.
4. If you need unsigned modules, either sign them with the k3OS key or disable Secure Boot (not recommended for edge security).
5. Configure your cluster’s admission controller to accept TPM attestation data if you want to enforce node integrity checks.
6. Document the Secure Boot password and recovery steps for future maintenance.

By following these steps you can give each k3OS node in your edge cluster a tamper‑evident foundation, ensuring that only signed kernels and modules run and that the node can prove its integrity to a central controller.