# General troubleshooting

## First step: run edera-check

If something isn’t working, start by running [`edera-check postinstall`](https://docs.edera.dev/reference/edera-check/) on the affected node:

```bash
sudo edera-check postinstall
```

Or via Docker:

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

This validates your system configuration and generates a diagnostic report bundle (a `.tar.gz` file saved locally). If you need to contact support, send this bundle to [support@edera.dev](mailto:support@edera.dev). It contains the system info we need to help diagnose your environment.

## RuntimeClass: check installation

To verify the Edera runtime is installed and visible to Kubernetes:

```bash
kubectl get runtimeclass -o yaml
```

You should see output similar to:

```yaml
apiVersion: v1
items:
- apiVersion: node.k8s.io/v1
  handler: edera
  kind: RuntimeClass
  metadata:
    annotations:
      kubectl.kubernetes.io/last-applied-configuration: |
        {"apiVersion":"node.k8s.io/v1","handler":"edera","kind":"RuntimeClass","metadata":{"annotations":{},"name":"edera"}}
    creationTimestamp: "2025-05-15T20:48:52Z"
    name: edera
    resourceVersion: "35453"
    uid: f51f6d5f-237a-4c35-bf72-0d69a34ff6cb
kind: List
metadata:
  resourceVersion: ""
```

## Is the pod running in an Edera zone?

To use the `protect` cli you will need access to your node:

```bash
protect zone list
```

You should see something like:

```bash
┌─────────────────────────────────────┬──────────────────────────────────────┬───────┬───────────────┬──────────────────────────────┐
│ name                                ┆ uuid                                 ┆ state ┆ ipv4          ┆ ipv6                         │
╞═════════════════════════════════════╪══════════════════════════════════════╪═══════╪═══════════════╪══════════════════════════════╡
│ k8s_edera-protect_edera-protect-pod ┆ ab2e8fdc-48dd-4b4e-8c83-0e81228da5f0 ┆ ready ┆ 10.0.2.169/32 ┆ fe80::a4d6:c6ff:fef8:c3aa/32 │
└─────────────────────────────────────┴──────────────────────────────────────┴───────┴───────────────┴──────────────────────────────┘
```

If you don’t have node access, you can check with `kubectl`:

```bash
kubectl describe pod <pod-name> | grep -B 3 edera
```

Expected output:

```bash
Name:                edera-protect-pod
Namespace:           edera-protect
Priority:            0
Runtime Class Name:  edera
```

💡 Tip: Use `protect zone list -o yaml` for more detailed zone or workload info.

## Debugging Edera

Here are some general steps to debug issues with Edera:

### Confirm the pod exists

```bash
kubectl get pods --all-namespaces
```

### Check Edera sees the pod

(The below requires node access)

```bash
protect zone list
```

### Check Edera services

Make sure the systemd services are running:

```bash
systemctl status protect-cri
systemctl status protect-daemon
```

Example output:

```bash
 protect-cri.service - Edera Protect CRI
   Loaded: loaded (/usr/lib/systemd/system/protect-cri.service; enabled; vendor preset: disabled)
   Active: active (running) since Thu 2025-05-15 18:08:36 UTC; 1 weeks 5 days ago
 Main PID: 2806 (protect-cri)
   CGroup: /system.slice/protect-cri.service
           └─2806 /usr/sbin/protect-cri
```

### View logs

Check logs for the CRI and daemon services:
`protect-cri` invokes `protect-daemon` so checking the logs of both of those systemd services will usually show you how/where things went bad.

```bash
journalctl -u protect-cri
journalctl -u protect-daemon
```

### Enable debug logging

Edit the systemd service file:

```bash
sudo vi /usr/lib/systemd/system/protect-cri.service
# Change:
Environment=RUST_LOG=info
# To:
Environment=RUST_LOG=debug
```

Then reload and restart:

```bash
sudo systemctl daemon-reload
sudo systemctl restart protect-cri
journalctl -u protect-cri
```

### Check pod status

If a pod won’t start:

```bash
kubectl describe pod <pod-name> -n <namespace>
```

If no cause is shown, `protect zone list` may show a zone that failed to start.

## Installing Edera manually

If you’ve installed Edera manually, you’ll need to reboot the node post-installation to boot the node with our hypervisor so our CRI can provide the backend for the edera runtime

## Verify Edera is running

The Edera services must be in the `active` state:

```bash
sudo systemctl is-active protect-daemon
sudo systemctl is-active protect-cri
```

## Verify the Kubelet is aware of Edera

The Edera installer hooks into the kubelet as a CLI argument to take precedence over the on-disk config.

```bash
ps aux | grep kubelet
```

To verify the runtime is pointing at Edera.

## Pod terminated with OOMKilled

Starting in v1.6.0, Edera properly reports OOMKilled status to Kubernetes when a container exceeds its memory limit.

To check if a pod was OOMKilled:

```bash
kubectl describe pod <pod-name> | grep -A 5 "Last State"
```

Expected output for an OOMKilled container:

```bash
Last State:     Terminated
  Reason:       OOMKilled
  Exit Code:    137
```

**Common causes:**

- Memory limit set too low for the workload
- Memory leak in the application
- Burst memory usage during startup

**Solutions:**

- Increase the memory limit in your pod spec
- Use `protect zone metrics <zone>` to monitor memory usage
- Check application logs before the OOM event

## Kubelet is failing `systemctl status kubelet`

If Edera Protect is installed, but the Kubelet is failing `systemctl status kubelet`, it might be due to the configuration file not being correct.

For Amazon Linux it should look like:

```bash
cat /etc/default/kubelet
KUBELET_EXTRA_ARGS=" --container-runtime-endpoint=unix:///var/lib/edera/protect/cri.socket"
```

For LKE / Akamai it should look like:

```bash
cat /etc/default/kubelet
KUBELET_EXTRA_ARGS="--cloud-provider=external --container-runtime-endpoint=unix:///var/lib/edera/protect/cri.socket"
```

Last updated on 2026-02-24