Common Issues

Common troubleshooting steps and solutions for Edera deployment and operational issues.

First: Run edera-check

Before digging into manual diagnostics, run edera-check postinstall to validate your system configuration and generate a diagnostic report:

sudo edera-check postinstall

Or via Docker if edera-check isn’t installed:

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

This produces a .tar.gz diagnostic bundle you can share with support.

General Troubleshooting Steps

RuntimeClass Verification

First, verify that the Edera RuntimeClass is properly installed:

kubectl get runtimeclass -o yaml

Confirm that the Edera runtime is installed and visible to Kubernetes.

Pod Zone Verification

Check if pods are running in Edera zones:

# From a node (requires node access)
protect zone list

# From kubectl
kubectl describe pod <pod-name> | grep -B 3 edera

Look for “Runtime Class Name: edera” in the pod description.

Service Status Checks

Verify that all Edera services are running:

systemctl status protect-cri
systemctl status protect-daemon
systemctl list-units --type=service | grep protect

At minimum, these two services should be active:

- protect-cri.service
- protect-daemon.service

Logging and Debugging

Check service logs for errors:

journalctl -u protect-cri
journalctl -u protect-daemon

For more detailed logging, enable debug mode by changing RUST_LOG=info to RUST_LOG=debug in the service configuration.

AWS-Specific Issues

Runtime Not Detected

Problem: Pods are not using the Edera runtime even though RuntimeClass is configured.

Solution:

1. Verify RuntimeClass exists:

   kubectl get runtimeclass

2. Ensure pod specification includes:

   spec:
     runtimeClassName: edera

3. Check container runtime endpoint configuration in kubelet config and restart kubelet if needed.

AMI and Version Information

Get node AMI and Edera version information:

# List Edera-related AMIs
aws ec2 describe-images --filters Name=name,Values="*edera*" --query 'Images[*].[ImageId,Name,CreationDate]' --output table

Kubelet Configuration

Verify runtime endpoint configuration:

• Amazon Linux: --container-runtime-endpoint=unix:///var/lib/edera/protect/cri.socket
• LKE/Akamai: Add --cloud-provider=external

After configuration changes, restart the kubelet service.

Resource Utilization Issues

Monitoring Resource Usage

Check zone resource utilization:

protect zone metrics <zone_name>

This displays:

• Total and available memory
• CPU usage for each attached CPU

CPU Management

Adjust CPU allocation for zones:

# Set minimum CPUs
protect zone update-resources --min-cpus 4 <zone_name>

# Set maximum CPUs
protect zone update-resources --max-cpus 4 <zone_name>

# Set target CPUs
protect zone update-resources --target-cpus 4 <zone_name>

Memory Management

Configure memory allocation:

# Switch allocation policy
protect zone update-resources <zone_name> --adjustment-policy static|dynamic

# Set target memory
protect zone update-resources <zone_name> --target-memory 500

# Set memory limits
protect zone update-resources <zone_name> --min-memory 300
protect zone update-resources <zone_name> --max-memory 700

Note: Dynamic mode is recommended for most workloads (default).

Installation Issues

Manual Installation Requirements

If Edera was manually installed (not via AMI), a node reboot is required for proper operation.

Pod Status Issues

Check pod status and events:

kubectl describe pod <pod-name>
kubectl get events --sort-by='.metadata.creationTimestamp'

Look for runtime-related errors or warnings in the events.

Troubleshooting Utilities

Apply RuntimeClass Without YAML

edera_k8s_apply_runtimeclass() {
  cat <<EOF | kubectl apply -f -
apiVersion: node.k8s.io/v1
kind: RuntimeClass
metadata:
  name: edera
handler: edera
EOF
}

Check All Edera Services

systemctl list-units --type=service | grep protect

Getting Help

Collect Diagnostic Information

When contacting support, gather the following information:

1. Service Status:

   systemctl list-units --type=service | grep protect

2. RuntimeClass Configuration:

   kubectl get runtimeclass -o yaml

3. Pod Details:

   kubectl describe pod <pod-name>

4. Service Logs:

   journalctl -u protect-cri --since "1 hour ago"
   journalctl -u protect-daemon --since "1 hour ago"

5. Resource Usage:

   protect zone list
   protect zone metrics <zone_name>

Contact Support

• Email: support@edera.dev
• Include diagnostic information and detailed problem description
• Reference specific error messages and reproduction steps

Additional Resources

For more troubleshooting documentation, visit:

Edera Troubleshooting Guide