# Selecting a zone kernel variant

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](https://docs.edera.dev/guides/kernel/kernel-variants/#using-a-direct-kernel-image-deprecated) mechanism only.

## List available variants

To discover what variants are currently available:

```bash
sudo protect image list-kernel-variants
```

Output:

```plain
┌─────────┬───────────────────────────────────────────────────────────────┐
│ 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`:

```bash
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:

```yaml
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:

```toml
# /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:

```bash
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](https://docs.edera.dev/reference/configuration/daemon-toml/#zonekernel-variants).

## 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:

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

```yaml
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`.