Install Edera with KVM (Early Access)

5 min read · Intermediate

The installer defaults to Xen as a hypervisor. This guide will walk through installing Edera for KVM.

Choose a backend

If you’re unsure, use Xen: it’s the default and the more established path. Use KVM if you want a lower barrier to entry, can’t modify the bootloader, or have workloads that can’t run on Xen.

System requirements

• Kernel version: Linux 5.10 or newer.
• Hardware virtualization: VT-x (Intel) or AMD-V enabled in firmware.
• /dev/kvm: must be present and accessible. Verify with ls -la /dev/kvm.

If /dev/kvm is missing, see Troubleshooting below.

Nested virtualization

If you’re running Edera inside a VM, the outer hypervisor must expose KVM to the guest. This is provider-specific – refer to your hypervisor’s documentation to enable nested virtualization. For AWS EC2, see Amazon EC2 nested virtualization. Most general-purpose EC2 instance types do not support nested KVM.

Prerequisites

• A Google Artifact Registry (GAR) key with access to the Edera installer image. Don’t have one? Talk to the team.
• Docker installed on your target node, with root or sudo access to run it.
• Docker authenticated to GAR (sudo docker login us-central1-docker.pkg.dev).

Step 1: Validate your system

Run the following command on the target host to confirm prerequisites are met:

docker run --pull always --pid host --privileged \
  ghcr.io/edera-dev/edera-check:stable preinstall

All Required checks should pass before proceeding. Note that edera-check does not include KVM-specific checks in this Early Access release.

Step 2: Run the installer

Run the following command on the target host (the node you want to install Edera on). The installer is a container that copies Edera components from the image to the host filesystem.

To install with KVM, set HYPERVISOR=kvm:

sudo docker run --privileged \
  --env 'TARGET_DIR=/host' \
  --env 'HYPERVISOR=kvm' \
  --volume '/:/host' \
  --volume "/root/.docker/config.json:/root/.docker/config.json" \
  --pid host \
  --net host \
  us-central1-docker.pkg.dev/edera-protect/staging/protect-installer:main

Unlike the Xen path, the KVM installer does not modify your bootloader and does not reboot the node. When the installer exits, the Protect daemon is already running.

Step 3: Verify installation

Confirm the Protect CLI is available and the daemon is running:

protect help
sudo systemctl status protect-daemon
sudo protect zone list

Kubernetes

Apply the Edera RuntimeClass:

kubectl apply -f https://public.edera.dev/kubernetes/runtime-class.yaml

Label your nodes:

kubectl label nodes <node-name> runtime=edera

Troubleshooting

/dev/kvm not found

If you run the installer with HYPERVISOR=kvm on a host without /dev/kvm, the installer fails during preflight. If /dev/kvm was present at install time but disappeared later (KVM module unloaded, host migrated to a hypervisor that no longer exposes nested KVM), the Protect daemon fails to start. In the daemon log:

ERROR protect-daemon: failed to initialize core runtime: missing /dev/kvm

The systemd unit will be in failed state. protect zone list fails because there’s no daemon to answer it.

To recover:

1. Confirm what’s actually missing:

   ls -l /dev/kvm
   lsmod | grep -E '^kvm_(intel|amd)'
   egrep -c '(vmx|svm)' /proc/cpuinfo

2. If the KVM module isn’t loaded, load it and restart the daemon:

   sudo modprobe kvm_intel    # or kvm_amd
   sudo systemctl restart protect-daemon

3. If the CPU doesn’t expose vmx or svm, enable hardware virtualization in BIOS/UEFI.

4. If you’re inside a VM, your outer hypervisor isn’t exposing nested KVM. See nested virtualization above.

5. If none of that is possible on this host, re-install with --xen instead. The Xen path doesn’t need /dev/kvm. You’ll need a Xen-capable kernel and the install will reboot the node, but you’ll end up with a working Protect node.

Daemon won’t start: backend mismatch

A host installed with HYPERVISOR=kvm but now booting under something neither runtime can drive – or a Xen install booted from a non-Xen GRUB menuentry – will have the daemon refuse to start.

Determine what the host is actually running:

ls /sys/hypervisor/type 2>/dev/null && cat /sys/hypervisor/type
ls -l /dev/kvm 2>/dev/null

xen in /sys/hypervisor/type means you’re booted under Xen. A readable /dev/kvm with no Xen means bare Linux with KVM available.

If you expected Xen but you’re on bare Linux, fix GRUB:

sudo grub-set-default 'Edera Protect via Xen'
sudo grub-mkconfig -o /boot/grub/grub.cfg
sudo reboot

If you expected KVM but /dev/kvm is gone, follow the /dev/kvm not found recovery above.

To switch backends on an already-installed host, re-run the installer with a different HYPERVISOR value. Switching from kvm to xen will reconfigure the bootloader and reboot the node.

Verify Edera services

SSH into the node and check:

sudo systemctl status protect-daemon
sudo protect zone list
sudo protect --version

Next steps

• KVM architecture overview: how the KVM and Xen backends compare.
• Monitoring and observability: metrics and Falco integration.