Selecting a zone kernel variant

3 min read · Intermediate

A kernel variant is a named, alternate zone kernel with different configuration or features than the default zone kernel. It is not necessary to specify a kernel variant most of the time, as Edera’s default zone kernel is generic, hardened, and supports all baseline features. Some features, such as GPU support, specifically require alternate kernel variants.

Kernel variants are always referenced by their name, such as nvidia, and are defined in the Edera daemon’s daemon.toml in the [zone.kernel-variants] section.

Each variant name maps to a specific OCI image that contains that kernel. Edera ships with some default kernel variants, additional variants may be defined by the user.

You may host your own kernels in an OCI registry, and define your own site-local kernel variants as well.

ℹ️

Kernel variants are available and supported starting with Edera v1.11. Earlier releases use the direct kernel image mechanism only.

List available variants

To discover what variants are currently available:

sudo protect image list-kernel-variants

Output:

┌─────────┬───────────────────────────────────────────────────────────────┐
│ variant ┆ image                                                         │
╞═════════╪═══════════════════════════════════════════════════════════════╡
│ nvidia  ┆ ghcr.io/edera-dev/zone-nvidiagpu-kernel:6.18-nvidia-610.43.02 │
└─────────┴───────────────────────────────────────────────────────────────┘

The variant column lists the names you can pass to --kernel-variant or the dev.edera/kernel-variant annotation. Use --output json-pretty (or json, jsonl, yaml, simple) for machine-readable output.

Launch a zone with a variant

Pass the variant name to protect zone launch:

sudo protect zone launch --name zone-gpu --kernel-variant nvidia

The daemon resolves nvidia to the image configured under [zone.kernel-variants] and uses it for the zone.

Use a variant in Kubernetes

Set the dev.edera/kernel-variant annotation on the pod:

apiVersion: v1
kind: Pod
metadata:
  name: gpu-workload
  annotations:
    dev.edera/kernel-variant: nvidia
spec:
  runtimeClassName: edera
  containers:
    - name: workload
      image: nvidia/cuda:13.3.0-devel-ubuntu26.04

The daemon resolves nvidia to the image configured under [zone.kernel-variants] and uses it for the zone that backs the pod.

Define your own variant

Variants are configured in daemon.toml under [zone.kernel-variants] as a map from a name to an OCI reference. Add or override entries to expose your own kernels by name:

# /var/lib/edera/protect/daemon.toml

[zone.kernel-variants]
nvidia = "ghcr.io/edera-dev/zone-nvidiagpu-kernel:6.18.38-nvidia-610.43.02"
mykernel = "docker.io/myorg/zone-mykernel:7.1.20"

It is strongly recommended to pin variants to a specific version tag (or a digest) so a variant resolves deterministically. Note that the registry and the image must be accessible to (and pullable by) the daemon.

Restart the daemon to apply the change:

sudo systemctl restart protect-daemon

Confirm the daemon picked up the new mapping with protect image list-kernel-variants.

For the full [zone.kernel-variants] reference, see daemon.toml.

Using a direct kernel image (deprecated)

The --kernel flag and the dev.edera/kernel annotation are deprecated as of 1.11, but are still supported:

sudo protect zone launch --name zone-test \
  --kernel ghcr.io/edera-dev/zone-kernel:latest

metadata:
  annotations:
    dev.edera/kernel: ghcr.io/edera-dev/zone-kernel:latest

⚠️

--kernel and the dev.edera/kernel annotation are deprecated in favor of --kernel-variant and dev.edera/kernel-variant. Prefer variants for custom kernels, as described above.

Support for this method will be removed in a future release.

Precedence

--kernel-variant takes precedence over --kernel.
dev.edera/kernel-variant takes precedence over dev.edera/kernel.