Run Edera – EderaON

Run Edera

At the end of this guide, you will have launched an isolated zone and run a workload inside it.

Launch a zone Permalink for this section

Launching a zone typically takes less than a minute. If it takes longer, check logs with sudo journalctl -u protect-daemon -n 50.

sudo protect zone launch -n test-zone --wait
sudo protect zone list

Expected output:

┌───────────┬──────────────────────────────────────┬───────┬──────────────┬──────────────────────┐
│ name      ┆ uuid                                 ┆ state ┆ ipv4         ┆ ipv6                 │
╞═══════════╪══════════════════════════════════════╪═══════╪══════════════╪══════════════════════╡
│ test-zone ┆ 1aa92875-eafa-47c9-ba31-f1e63e50079d ┆ ready ┆ 10.75.0.2/16 ┆ fdd4:1476:6c7e::2/48 │
└───────────┴──────────────────────────────────────┴───────┴──────────────┴──────────────────────┘

A zone in ready state is running and available.

Run a workload Permalink for this section

Launch an interactive shell inside the zone:

sudo protect workload launch \
  --zone test-zone \
  --name alpine-shell \
  -t -a \
  docker.io/library/alpine:latest sh

Once inside, run uname -r to confirm you’re running in an isolated zone with its own kernel:

uname -r
# Expected: 6.18.18

Type exit to leave the shell.

Want to see zone isolation in action? docs.edera.dev has guides for launching multiple zones and verifying that workloads are isolated from each other.

The setup script below is intended for demo and evaluation use only and requires Ubuntu 24.04 or above. It bootstraps a single-node cluster on your Edera-protected EC2 instance. Use your own Kubernetes setup (EKS, kubeadm, etc.) in any other context.

ℹ️

Before continuing, make sure you ran the k8s-prepare.sh script from the Prepare Your VM step before installing Edera. If you skipped it, you will see a kubelet.service not found error.

Bootstrap Kubernetes Permalink for this section

Run the bootstrap script on your EC2 instance. It initializes a single-node cluster using the Edera CRI and installs Cilium as the CNI.

/bin/bash -c "$(curl -fsSL https://on.edera.dev/scripts/k8s-bootstrap.sh)"

This takes a few minutes. When it completes, verify the node is ready:

kubectl get nodes
# Expected: STATUS Ready

Apply the Edera RuntimeClass Permalink for this section

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

Run a workload Permalink for this section

kubectl apply -f - <<'EOF'
apiVersion: v1
kind: Pod
metadata:
  name: edera-test
  namespace: default
spec:
  runtimeClassName: edera
  containers:
  - name: alpine
    image: alpine:latest
    command: ["sh", "-c", "uname -r && sleep 3600"]
  restartPolicy: Never
EOF

Wait for the pod and verify it’s running in an isolated zone:

kubectl wait --for=condition=ready pod/edera-test --timeout=120s
kubectl logs edera-test
# Expected: 6.x.y-edera

Use the protect CLI to display the Zone (pod sandbox) and Workload (container) corresponding to the pod created above:

sudo protect zone list

Expected output:

┌────────────────────────┬──────────────────────────────────────┬───────┬───────────────┬──────┐
│ name                   ┆ uuid                                 ┆ state ┆ ipv4          ┆ ipv6 │
╞════════════════════════╪══════════════════════════════════════╪═══════╪═══════════════╪══════╡
│ k8s_default_edera-test ┆ c9307c61-a753-463d-a1b8-499dfea17479 ┆ ready ┆ 10.0.0.102/32 ┆      │
└────────────────────────┴──────────────────────────────────────┴───────┴───────────────┴──────┘

sudo protect workload list

Expected output:

┌───────────────────────────────┬──────────────────────────────────────┬──────────────────────────────────────┬─────────┐
│ name                          ┆ uuid                                 ┆ zone                                 ┆ state   │
╞═══════════════════════════════╪══════════════════════════════════════╪══════════════════════════════════════╪═════════╡
│ k8s_default_edera-test_alpine ┆ 3e668170-bff9-4353-b0e3-76892fc78380 ┆ c9307c61-a753-463d-a1b8-499dfea17479 ┆ running │
└───────────────────────────────┴──────────────────────────────────────┴──────────────────────────────────────┴─────────┘

Troubleshooting Permalink for this section

Daemon not running after reboot Permalink for this section

Check logs: sudo journalctl -u protect-daemon -n 50
Verify the KVM device is present: ls /dev/kvm (if missing, hardware virtualization may be disabled on the host)
Verify Xen booted: ls /proc/xen (if missing, the machine booted into the stock kernel instead of Xen)
Verify UEFI boot: [ -d /sys/firmware/efi ] && echo UEFI || echo BIOS

Instance unreachable after reboot Permalink for this section

Wait 1-2 minutes after reboot. If still unreachable, check the EC2 serial console for boot errors.

Wait 2-3 minutes — Xen boot takes longer than a normal boot. If still unreachable, check the EC2 serial console for boot errors.

Common daemon errors:

“no viable machine identifiers” — The instance may be in BIOS boot mode. Terminate and relaunch with a UEFI-compatible AMI.
Xen not present (/proc/xen missing) — GRUB booted into the stock kernel instead of Xen. Check sudo grub-editenv list and verify the saved entry matches a Xen menu entry.

License already active on another machine Permalink for this section

If the daemon fails with a license activation failed: could not register new machine to license error and your license key is present on the machine, the license is most likely still active on a previous machine.

To fix this:

Go to on.edera.dev and log in
Find the active machine under your license and click Deactivate
Restart the daemon: sudo systemctl restart protect-daemon

One license key can only be active on one machine at a time. Always deactivate before moving to a new machine.

Missing license key Permalink for this section

If the daemon fails with a license activation failed: could not register new machine to license error and no license key file exists on the machine, inject it manually:

sudo mkdir -p /var/lib/edera/protect
echo $EDERA_LICENSE_KEY | sudo tee /var/lib/edera/protect/license.key
sudo systemctl restart protect-daemon

For additional help, file an issue on GitHub.

Clean up Permalink for this section

Deactivate your node at on.edera.dev before terminating so you can reuse your license on another instance.

Terminate the instance and delete the security group:

aws ec2 terminate-instances --instance-ids <INSTANCE_ID>
aws ec2 delete-security-group --group-id <YOUR_SG_ID>

If you used the installer script, you may also use a teardown script. You can view the full usage details in the edera-dev/learn repository.

/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/edera-dev/learn/refs/heads/main/getting-started/edera-on-installer/scripts/ec2-teardown.sh)"