Install Edera

5 min read · Intermediate

Developer Platform Engineer
ℹ️
Using EderaON? Follow the EderaON install guide instead. The setup process is different.

This guide walks you through installing Edera on a Linux instance using either the Xen (default) or KVM (Early Access) hypervisor backend.

Choose a backend

XenKVM
Recommended forProduction workloads; maximum security and performanceTeams already running KVM; lower barrier to entry
Host kernelEdera-built and maintained kernelYour existing distribution kernel
Reboot requiredYesNo
Bootloader modifiedYesNo
Nested virtualization (cloud VMs)Not requiredRequired if not on bare metal
Hardware requirementBroad; supports PV and PVHVT-x or AMD-V

If you’re unsure, use Xen: it’s the default and the production-ready path.

Validate your system

Before installing, run edera-check to confirm your system meets all requirements:

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

All Required checks should pass. If anything fails, address the issue before proceeding. See the edera-check reference for details on each check.

⚠️
The Xen installer reboots the node. Plan for downtime before running.

Prerequisites

  • A Google Artifact Registry (GAR) key from Edera (key.json). Don’t have one? Contact support@edera.dev.
  • Docker or nerdctl installed on the target node with root or sudo access.
  • UEFI boot mode is required.

Step 1: Log in to the registry

Run the following commands on the target node. Copy your key.json to the node first if needed.

docker login us-central1-docker.pkg.dev -u _json_key --password-stdin < key.json

Step 2: Run the installer 

docker run --privileged \
  --env 'TARGET_DIR=/host' \
  --volume '/:/host' \
  --volume "$HOME/.docker/config.json:/root/.docker/config.json" \
  --pid host \
  --net host \
  us-central1-docker.pkg.dev/edera-protect/staging/protect-installer:${TAG}

Set TAG to the release version you want to install. See Edera release notes for current versions.

The installer reboots the node when complete. Wait 1-2 minutes for it to come back online.

Step 3: Verify installation 

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

Expected output from protect zone list:

No zones have been launched.
ℹ️
KVM support is currently in Early Access. It is not intended for production use and has not completed Edera’s security review. For production and Edera’s hypervisor-enforced isolation guarantees, use the Xen backend.

KVM prerequisites

  • A Google Artifact Registry (GAR) key with access to the Edera installer image. Don’t have one? Contact the team.
  • Docker installed on your target node with root or sudo access.
  • Docker authenticated to GAR on the target node: sudo docker login us-central1-docker.pkg.dev.
  • A current, non-EOL LTS kernel. edera-check validates this. See kernel.org for LTS status.
  • Hardware virtualization enabled (VT-x or AMD-V) and /dev/kvm accessible. Verify: ls -la /dev/kvm.

Nested virtualization

ℹ️
Nested virtualization carries a performance penalty. Bare metal is the preferred deployment target for KVM.

If you’re running inside a VM, the outer hypervisor must expose KVM to the guest. For AWS EC2, see Amazon EC2 nested virtualization. Most general-purpose EC2 instance types do not support nested KVM.

Step 1: Run the installer

Run the following command on the target host:

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

Set TAG to the release version you want to install. See Edera release notes for current versions.

⚠️
If HYPERVISOR=kvm is omitted, the installer defaults to Xen. Switching backends later requires reinstalling from scratch.

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 2: Verify installation 

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

Kubernetes

These steps apply to both backends.

Confirm nodes are back online 

watch kubectl get nodes

Apply the Edera RuntimeClass 

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

Expected output:

NAME    HANDLER   AGE
edera   edera     1d

Label nodes for Edera workloads

The Edera RuntimeClass includes a nodeSelector that requires nodes to be labeled with runtime=edera:

kubectl label nodes <node-name> runtime=edera

Test with a Pod 

kubectl apply -f kubernetes/test-workload.yaml
kubectl wait --for=condition=ready pod/edera-test-pod -n edera-test --timeout=300s
kubectl get pods -n edera-test

Troubleshooting

Node unreachable after Xen install

Expected. The installer reboots the node. Wait 1-2 minutes then reconnect and run sudo protect --version to confirm it’s running.

Console UI scrambled screen not available after Xen install

This typically occurs when booting into a node that does not have UEFI enabled. Edera requires UEFI to work properly.

/dev/kvm not found (KVM)

If /dev/kvm is missing at install time, the installer fails during preflight. If it disappears after install, the daemon fails to start:

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

To recover:

  1. Check what’s 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:

    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, the outer hypervisor isn’t exposing nested KVM. See nested virtualization above.

Verify Edera services 

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

Kubernetes troubleshooting

  • Check pod details: kubectl describe pod edera-test-pod -n edera-test
  • Check logs: kubectl logs edera-test-pod -n edera-test
  • Verify RuntimeClass: kubectl get pod edera-test-pod -n edera-test -o=jsonpath="{.spec.runtimeClassName}"

What’s next

Last updated on