# Building your own Edera zone kernel

**Advanced guide only**  
Most Edera users **do not need to build their own kernel images**. By default, Edera provides and maintains hardened kernel images that cover nearly all workloads.

Note that while you are welcome to use our public configs and CI templates to build our own kernel images, Edera **only** supports images built by Edera and signed by Edera’s production signing key. You are on your own with DIY builds.

This guide is for specialized cases such as:

- **Supply chain verification** (reproducing our kernel builds yourself using our open-source repo and Github CI actions)
- **Custom hardware/silicon** (adding out-of-tree Linux drivers you cannot share with us)

If you just need help or need support for official images, [open a support ticket](https://docs.edera.dev/support/contact-us/).

If you’re not already comfortable building and maintaining Linux kernels, stop here.

## Minimum requirements

If you already know how to build a Linux kernel, these are the essentials your kernel must have to boot inside an Edera zone.

### Guest/virt stack (required)

Edera maintains base config snippets you can use as references:

- [Guest (zone) kernel config](https://github.com/edera-dev/linux-kernel-oci/blob/main/configs/x86_64/zone.config)
- [Host (hypervisor) kernel config](https://github.com/edera-dev/linux-kernel-oci/blob/main/configs/x86_64/host.config)

### Artifacts (required in the OCI image)

Your kernel OCI image must include:

```bash
/kernel/vmlinuz
/kernel/config.gz
/kernel/addons.squashfs
```

`System.map` is optional but useful for debugging.

### Container image

Use a `scratch` base and copy artifacts into `/kernel/`:

```dockerfile
FROM scratch
COPY kernel/ /kernel/
```

## Full build guide (using Edera’s tooling)

If you want to use our open-source build system (CI or local), follow the steps below.

### Approach 1: Build locally (for debugging/iteration)

**Step 1.** Clone:

```bash
git clone https://github.com/edera-dev/linux-kernel-oci.git
cd linux-kernel-oci
```

**Step 2.** Edit `config.yaml`

Narrow architectures, flavors, and versions to reduce build time. Examples can be found in the [linux-kernel-oci README](https://github.com/edera-dev/linux-kernel-oci?tab=readme-ov-file#building-your-own-kernels-with-custom-kconfig-locally-for-debugging).

**Step 3.** Customize configs in `configs/`.
**Step 4.** Build:

```bash
./hack/build/docker-build.sh
```

**Step 5.** Use or push the image:

```bash
docker push ttl.sh/<user>/zone-kernel:6.6.15
```

Inspect it:

```bash
crane export ttl.sh/<user>/zone-kernel:6.6.15 - --platform=linux/amd64 | tar xf - -C ./output
```

### Approach 2: Build with GitHub Actions

**Step 1.** Fork [`edera-dev/linux-kernel-oci`](https://github.com/edera-dev/linux-kernel-oci)  
**Step 2.** Review `.github/workflows/build.yaml`  
**Step 3.** Edit `config.yaml` to set your registry and configs  
**Step 4.** Trigger the `Build Kernels` job in GitHub Actions

For the full instructions, see [Building your own kernels with custom KConfig](https://github.com/edera-dev/linux-kernel-oci?tab=readme-ov-file#building-your-own-kernels-with-custom-kconfig-using-github-actions).

Example workflow input (for the `Build Kernels` job):

```bash
stable:flavor=zone,host
```

## Using your custom kernel

Expose your custom kernel as a named [kernel variant](https://docs.edera.dev/guides/kernel/kernel-variants/) so zones and pods can select it by name.

### Register the variant

Add your image to the `[zone.kernel-variants]` section of the daemon config, mapping a name to your OCI reference:

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

[zone.kernel-variants]
mykernel = "ttl.sh/<user>/zone-kernel:6.6.15"
```

It is strongly recommended to pin the variant to a specific tag or digest so it resolves deterministically. The registry must be accessible and image must be pullable by the daemon. Restart the daemon to apply the change:

```bash
sudo systemctl restart protect-daemon
```

Confirm the daemon resolves the variant:

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

### Launch a zone with the variant

```bash
protect zone launch --kernel-variant mykernel ...
```

Or annotate in Kubernetes:

```yaml
annotations:
  dev.edera/kernel-variant: mykernel
```

## Summary

- **Most users**: use Edera’s provided and supported kernel images.
- **Advanced users**: either (1) meet the bare minimum requirements with your own build, or (2) use our tooling to reproduce/extend our builds.
- Either way, kernels must be packaged as an OCI image with `/kernel/vmlinuz`, `/kernel/config.gz`, and `/kernel/addons.squashfs`.