How to fix agent not ready in Kubernetes

KubernetesADVANCEDHIGHUpdated Dec 6, 2025· 215 views

Cilium agent not ready errors occur during initialization or when dependencies fail. Fix by checking pod logs, verifying kernel compatibility, and ensuring sufficient system resources.

Quick fix

Fixes agent not ready

kubectl logs -n kube-system -l app=cilium --tail=100
kubectl logs -n kube-system -l app=cilium --previous
  1. Check Cilium pod logs for errors
  2. Verify kernel version meets minimum requirements
  3. Check node taint status
  4. Verify eBPF support on node
kubernetes — error
kubectl logs -n kube-system -l app=cilium --tail=100
kubectl logs -n kube-system -l app=cilium --previous
agent not ready

What this error means

The Cilium agent daemon is responsible for eBPF policy enforcement and pod networking on each node. When the agent is not ready, the node cannot schedule pods or enforce network policies. The agent must complete initialization including eBPF program loading and kernel module setup before becoming ready.

Typical symptoms

  • Cilium pod shows CrashLoopBackOff or not ready status
  • Node has taint node.cilium.io/agent-not-ready
  • Error message "cni plugin not initialized"
  • Pod creation fails with "unable to allocate IP via local cilium agent"
  • Agent reports "unable to connect to cilium" in pod events
  • Pods stuck in Pending state unable to get network
  • Agent keeps restarting with crash errors
  • Node becomes SchedulingDisabled due to agent failure

Common causes

  1. eBPF programs failing to load due to kernel incompatibility
  2. Required Linux kernel modules not available
  3. Insufficient memory or CPU causing initialization timeout
  4. Taint not removed after agent starts (stuck in not-ready)
  5. IP address allocation failure (IP pool exhausted)
  6. CNI plugin chain configuration issue with other plugins
  7. Kernel version below Cilium minimum requirements
  8. SELinux or AppArmor blocking eBPF operations

How to fix "agent not ready"

1Check Cilium pod logs for errors

View detailed initialization logs:

bash
kubectl logs -n kube-system -l app=cilium --tail=100
kubectl logs -n kube-system -l app=cilium --previous

Look for eBPF loading errors, memory allocation failures, or kernel incompatibility messages.

2Verify kernel version meets minimum requirements

Check kernel compatibility with Cilium version:

bash
uname -r
kubectl describe node <node-name> | grep -i kernel

Minimum kernel depends on Cilium version (typically 4.9+).

3Check node taint status

Verify if agent-not-ready taint is present:

bash
kubectl describe node <node-name> | grep Taints
kubectl get nodes -o custom-columns=NAME:.metadata.name,TAINTS:.spec.taints

Taint should be removed once agent becomes ready.

4Verify eBPF support on node

Ensure kernel eBPF features are available:

bash
grep BPF /boot/config-$(uname -r)
ls -la /sys/kernel/debug/tracing/
grep -E "(bpf|tracepoint)" /proc/sys/kernel/perf_event_paranoid
5Check Cilium IP allocation status

If agent fails due to IP allocation, check IP pool:

bash
kubectl exec -it -n kube-system ds/cilium -- cilium-dbg status | grep -i ipam
kubectl exec -it -n kube-system ds/cilium -- cilium-dbg ipam
6Review node resource availability

Ensure sufficient CPU and memory:

bash
kubectl top nodes
kubectl describe node <node-name> | grep -A 5 "Allocatable"

Cilium requires at least 512MB RAM per node.

7Check CNI configuration for plugin conflicts

Review CNI config for conflicts with other plugins:

bash
cat /etc/cni/net.d/*
kubectl get daemonset -n kube-system | grep -i cni

Ensure only one CNI plugin is configured.

8Restart Cilium daemonset to retry initialization

Force full restart of Cilium:

bash
kubectl rollout restart daemonset/cilium -n kube-system
kubectl rollout status daemonset/cilium -n kube-system --timeout=5m

Monitor logs during restart for initialization progress.

Advanced notes

For production, ensure all nodes meet kernel and resource requirements before deploying Cilium. Pre-load eBPF programs for faster agent startup. Monitor Cilium agent health via metrics endpoint. Use BPF ring buffer for events instead of perf ring in high-throughput environments. For multi-node clusters, implement node affinity for critical workloads while Cilium stabilizes on some nodes.

Frequently asked questions

What does "agent not ready" mean?
The Cilium agent daemon is responsible for eBPF policy enforcement and pod networking on each node. When the agent is not ready, the node cannot schedule pods or enforce network policies. The agent must complete initialization including eBPF program loading and kernel module setup before becoming ready.
How do I fix "agent not ready"?
Cilium agent not ready errors occur during initialization or when dependencies fail. Fix by checking pod logs, verifying kernel compatibility, and ensuring sufficient system resources.
What causes "agent not ready"?
eBPF programs failing to load due to kernel incompatibility Required Linux kernel modules not available Insufficient memory or CPU causing initialization timeout
Is the "agent not ready" error serious?
Yes. This is a high-severity error that usually blocks work until it is fixed, but the steps above resolve it.

Official resources & further reading