Getting started

5 min read

This Getting Started guide walks you through everything you need to launch and run your workloads in an Edera zone, from system prerequisites to production tuning recommendations.

ℹ️

Note: This guide covers the Xen backend only. Instructions for KVM (Early Access) can be found within the install guides referenced on this page.

What is Edera?

Edera is a secure-by-default, cloud-native platform built on a reimagined memory-safe type-1 hypervisor. It provides container isolation without performance tradeoffs by running containers in lightweight virtual machines called “zones.” Each zone has its own dedicated Linux kernel, eliminating the shared-kernel security risks inherent in traditional container deployments. Learn more in the Edera Overview section.

Edera 101

What's a zone? What is paravirtualization? Edera architecture

System requirements and prerequisites

Requirement	Details
Boot mode	UEFI required.
Container runtime	Docker, containerd
Disk space	Minimum: 1 GB on `/usr` 5 GB on `/var/lib` 200 MB on `/boot`
Kubernetes	A running cluster, with kubectl access

Confirm system requirements are met with edera-check:

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

✅ Verified AMI access* with the AMI listing guide
✅ AWS CLI installed and configured
✅ (Optional) An EC2 key pair for SSH access to worker nodes. SSH is disabled by default; enabling it recreates the node group.

*If you need access, contact your Edera account team.

A Google Artifact Registry (GAR) key from Edera (key.json). Contact your Edera account team if you need a GAR key.
Kubernetes 1.35 or later
Helm 3.8 or later
cert-manager installed on the target cluster

1. Install Edera

Option 1 (recommended): Find the latest Edera AMI name and ID, then add it to your cluster deployment configuration. See the AWS Custom AMI support instructions for help setting the AMI ID on a node.

List Edera AMIs:

# Set your region and k8s version
export REGION=us-west-2
export K8S_VERSION=1.36
export HYPERVISOR=xen

# Find the latest release
LATEST=$(aws ec2 describe-images --owners 207567768011 --region $REGION \
  --filters "Name=name,Values=edera-protect-v*" \
  --query 'sort_by(Images,&CreationDate)[-1].Name' --output text | cut -d- -f3)
echo "Latest: $LATEST"

# Get the AMI ID
aws ec2 describe-images --owners 207567768011 --region $REGION \
  --filters "Name=name,Values=edera-protect-${LATEST}-*-${HYPERVISOR}-*-${K8S_VERSION}-*" \
  --query 'sort_by(Images,&Name)[*].[ImageId,Name]' --output table

Add label runtime: edera to the node group, which the Edera RuntimeClass requires.

Once the nodes are up, apply the Edera RuntimeClass:

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

Option 2: Use our complete Terraform example, which creates a new cluster and applies all the configuration automatically.

Before running, make sure you’re logged into AWS:

aws sso login  # or: aws configure
aws sts get-caller-identity  # verify credentials are working

Then:

git clone https://github.com/edera-dev/learn.git
cd learn/getting-started/eks-terraform
cp terraform.tfvars.example terraform.tfvars
# Optional: edit terraform.tfvars to change region, k8s version, or instance type
make deploy
make test

Your EKS cluster with Edera will be ready in about 15 minutes.

Option 3: For advanced installation, see Manual configuration.

Check compatibility by cloud provider before installing.

Option 1 (recommended): Use the Edera Helm chart. Set TAG to the release version you want to install, or use latest (see the release notes).

export TAG=latest

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}')

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 the nodes where the installer should run:

kubectl label node <name> runtime=edera

⚠️

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

Verify the installation:

kubectl -n edera-system get pods

Expected output: one edera and one edera-controller pod per labeled node, plus two edera-webhook pods, all Running:

NAME                             READY   STATUS    RESTARTS      AGE
edera-5gnrx                      1/1     Running   1 (3m4s ago)  4m45s
edera-controller-7vn86           1/1     Running   0             4m45s
edera-webhook-84846d6f4c-sxrpq   1/1     Running   1 (3m4s ago)  4m45s
edera-webhook-84846d6f4c-zxxgf   1/1     Running   1 (3m4s ago)  4m45s

With Xen, expect restarts on these pods. The installer reboots the node, which restarts the pods running on it.

Option 2: For advanced installation, see Managed Kubernetes.

2. Run Edera

Confirm the RuntimeClass exists, then run a test pod in an Edera zone.

Confirm the RuntimeClass

kubectl get runtimeclass edera

The Edera RuntimeClass sets a nodeSelector of runtime: edera, so pods using it only schedule on nodes with that label. You applied this label in step 1.

Deploy a test pod

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

Validate

Wait for the pod to start, then verify it’s running in an isolated zone:

kubectl logs edera-test
# Expected: 6.x.y-edera-zone

That’s it. Your container is isolated in its own VM with a dedicated kernel. To run any other pod in Edera, set runtimeClassName: edera in its spec.