Install Edera

9 min read · Intermediate

ℹ️

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.

You can install Edera in two ways:

Bare Installer: run the installer container directly on each target node.
Helm Chart Installation: deploy the installer to your Kubernetes cluster with Helm, for a Kubernetes-native rollout across nodes.

Choose a backend

	Xen	KVM
Recommended for	Production workloads; maximum security and performance	Teams already running KVM; lower barrier to entry
Host kernel	Edera-built and maintained kernel	Your existing distribution kernel
Reboot required	Yes	No
Bootloader modified	Yes	No
Nested virtualization (cloud VMs)	Not required	Required if not on bare metal
Hardware requirement	Broad; supports PV and PVH	VT-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.

Bare Installer

Run the installer container directly on each target node.

⚠️

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

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

export TAG=latest

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}

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

ℹ️

On subsequent runs, the installer exits immediately without modifying anything on the host. It does not update OS services or the bootloader.

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: docker login us-central1-docker.pkg.dev -u _json_key --password-stdin < key.json
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 commands on the target host. Set TAG to the release version you want to install. See Edera release notes for current versions.

export TAG=latest

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}

⚠️

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.

However, you may want to switch to a Linux kernel provided and tested by Edera, like in a Xen installation, by adding the flag below to the installer command. This option will reconfigure the bootloader and cause the node to reboot.

--env 'EDERA_PROTECT_INSTALLER_INSTALL_KERNEL=true'

ℹ️

On subsequent runs, the installer exits immediately without modifying anything on the host. It does not update OS services or the bootloader.

Step 2: Verify installation

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

Helm Chart Installation

The edera-protect Helm chart runs the same installer as the Bare Installer, packaged for a Kubernetes-native rollout. It deploys the installer as a DaemonSet on your cluster nodes. It takes these values:

Value	Description
`hypervisor`	The hypervisor backend to install: `xen` or `kvm`.
`protect.image.tag`	The Protect installer OCI image, tagged with the release you want. See Edera release notes for current versions.
`protect.image.dockerconfigjson`	A base64-encoded Docker config authenticated against Edera’s registry. The chart uses this to create a `kubernetes.io/dockerconfigjson` Secret and reference it as an `imagePullSecrets` entry, so nodes can pull the installer image.
`protect.mode`	Where the Protect core components run. The default value `host` is identical to a Bare Installer installation and installs components as OS services. The value `container` runs these components as Kubernetes-managed containers instead.

protect.mode: container allows upgrading Edera components in-place. On chart updates, Kubernetes restarts Edera components into a newer version, without causing disruption to running zones.

⚠️

The Xen installer reboots each node. Plan for downtime before installing the chart.

Helm Xen prerequisites

A Google Artifact Registry (GAR) key from Edera (key.json). Don’t have one? Contact support@edera.dev.
Helm 3.7 or later.
kubectl configured against the target cluster.
cert-manager installed on the target cluster
UEFI boot mode is required on the target nodes.

Step 1: Get your registry credentials

Generate a base64-encoded Docker config from your GAR key:

export EDERA_KEY=$(kubectl create secret docker-registry edera \
  --docker-server=us-central1-docker.pkg.dev \
  --docker-username=_json_key \
  --docker-password="$(cat /path/to/gar/key.json)" \
  --dry-run=client -o jsonpath='{.data.\.dockerconfigjson}')

Step 2: Install the chart

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

On Azure VMs, including AKS, also add --set xen.cmdlineAppend="hyperv-vmbus" to the helm install command.

export TAG=latest

helm install edera oci://ghcr.io/edera-dev/charts/edera \
  --version 0.2.2 \
  --namespace edera-system --create-namespace \
  --set hypervisor="xen" \
  --set protect.image.tag="${TAG}" \
  --set protect.image.dockerconfigjson="$EDERA_KEY" \
  --set protect.mode="host"

Label any nodes on which the installer should be run:

kubectl label node <name> runtime=edera

The installer init container reboots each node when complete. Wait 1-2 minutes for the nodes to come back online.

ℹ️

On subsequent runs, the installer init container exits immediately without modifying anything on the host. It does not update OS services or the bootloader.

Step 3: Verify installation

kubectl -n edera-system get pods -o wide

ℹ️

Helm KVM prerequisites

A Google Artifact Registry (GAR) key with access to the Edera installer image. Don’t have one? Contact the team.
Helm 3.7 or later.
kubectl configured against the target cluster.
cert-manager installed on the cluster
A current, non-EOL LTS kernel on the target nodes. edera-check validates this. See kernel.org for LTS status.
Hardware virtualization enabled (VT-x or AMD-V) and /dev/kvm accessible on the target nodes. Verify: ls -la /dev/kvm.

If your nodes are VMs, the outer hypervisor must expose KVM to the guest. See Nested virtualization.

Step 1: Get your registry credentials

Generate a base64-encoded Docker config from your GAR key:

export EDERA_KEY=$(kubectl create secret docker-registry edera \
  --docker-server=us-central1-docker.pkg.dev \
  --docker-username=_json_key \
  --docker-password="$(cat /path/to/gar/key.json)" \
  --dry-run=client -o jsonpath='{.data.\.dockerconfigjson}')

This command doesn’t create anything in your cluster. It prints a value that you pass to the chart in the next step.

Step 2: Install the chart

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

export TAG=latest

helm install edera oci://ghcr.io/edera-dev/charts/edera \
  --version 0.2.2 \
  --namespace edera-system --create-namespace \
  --set hypervisor="kvm" \
  --set protect.image.tag="${TAG}" \
  --set protect.image.dockerconfigjson="$EDERA_KEY" \
  --set protect.mode="host"

Label any nodes on which the installer should be run:

kubectl label node <name> runtime=edera

⚠️

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.

However, you may want to switch to a Linux kernel provided and tested by Edera, as in a Xen installation, by adding the flag below to the Helm install command. This option will reconfigure the bootloader and cause the node to reboot.

--set controller.installer.installKernel="true"

ℹ️

On subsequent runs, the installer init container exits immediately without modifying anything on the host. It does not update OS services or the bootloader.

Step 3: Verify installation

kubectl -n edera-system get pods -o wide

Kubernetes

These steps apply to both backends and both installation methods.

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

Run a test Pod with the Edera RuntimeClass:

kubectl run edera-test-pod --image=busybox:1.36 --restart=Never \
  --overrides='{"spec":{"runtimeClassName":"edera"}}' -- sleep 3600

Confirm the Pod runs in an Edera zone by checking its kernel:

kubectl exec edera-test-pod -- uname -r
# Expected output - <version>-edera-zone

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:

Check what’s missing:

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

If the KVM module isn’t loaded:

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

If the CPU doesn’t expose vmx or svm, enable hardware virtualization in BIOS/UEFI.
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
Check logs: kubectl logs edera-test-pod
Verify RuntimeClass: kubectl get pod edera-test-pod -o=jsonpath="{.spec.runtimeClassName}"

What’s next

Monitor your workloads with Prometheus and Grafana
Learn about GPU support for AI/ML workloads (Xen only)
KVM architecture overview for background on how the KVM and Xen backends compare
Kernel customization for custom kernels and boot parameters

Last updated on 2026-10-27

Install Edera

Choose a backend

Validate your system

Bare Installer

Prerequisites

Step 1: Log in to the registry

Step 2: Run the installer

Step 3: Verify installation

KVM prerequisites

Nested virtualization

Step 1: Run the installer

Step 2: Verify installation

Helm Chart Installation

Helm Xen prerequisites

Step 1: Get your registry credentials

Step 2: Install the chart

Step 3: Verify installation

Helm KVM prerequisites

Step 1: Get your registry credentials

Step 2: Install the chart

Step 3: Verify installation

Kubernetes

Confirm nodes are back online

Apply the Edera RuntimeClass

Label nodes for Edera workloads

Test with a Pod

Troubleshooting

Node unreachable after Xen install

Console UI scrambled screen not available after Xen install

/dev/kvm not found (KVM)

Verify Edera services

Kubernetes troubleshooting

What’s next

`/dev/kvm` not found (KVM)