Skip to main content

​
Controller Issues

​
Controller Pods Not Starting

Symptoms: 
kubectl get pods -n kguardian
# kguardian-controller-xxxxx   0/1     CrashLoopBackOff
Common Causes:
kguardian requires Linux kernel 6.2+.Check:
kubectl get nodes -o jsonpath='{range .items[*]}{.metadata.name}{"\t"}{.status.nodeInfo.kernelVersion}{"\n"}{end}'
Solution: Upgrade nodes to kernel 6.2+ or use a distribution with eBPF CO-RE support.
Some cloud providers disable eBPF by default.Check controller logs:
kubectl logs -n kguardian daemonset/kguardian-controller
Look for errors like: “failed to load BPF programs”Solution: Enable eBPF in cloud provider settings or use privileged security context.
Controller needs CAP_BPF, CAP_PERFMON, CAP_SYS_RESOURCE.Check pod security:
kubectl get pod -n kguardian kguardian-controller-xxxxx -o jsonpath='{.spec.containers[0].securityContext}'
Solution: Ensure pod has privileged: true or the required capabilities.

​
Broker Issues

​
No Traffic Data

Symptoms:
  • CLI says “No traffic data found”
  • Empty response from /pod/traffic/ endpoint
Solutions:
1

Check pods are generating traffic

# Generate some traffic
kubectl exec my-pod -- curl http://google.com
2

Check controller is sending data

kubectl logs -n kguardian daemonset/kguardian-controller | grep "Sending traffic"
3

Check broker is receiving data

kubectl logs -n kguardian deployment/kguardian-broker | grep POST
4

Query database directly

kubectl port-forward -n kguardian svc/kguardian-broker 9090:9090
curl http://localhost:9090/pod/traffic/10.244.1.5  # Use actual pod IP

​
CLI Issues

​
Can’t Connect to Broker

Symptoms: 
Error: failed to connect to broker: connection refused
Solution: The CLI auto-discovers the broker via port-forwarding. Ensure you have permissions: 
kubectl auth can-i create pods/portforward -n kguardian
If not, ask your cluster admin for permissions or manually port-forward: 
kubectl port-forward -n kguardian svc/kguardian-broker 9090:9090 &

​
Policy Generation Issues

​
Generated Policy Too Permissive

Cause: Pods lack specific labels, so broader selectors are used. Solution:
  1. Add specific labels to your pods
  2. Manually edit generated policies
  3. Re-generate after labeling

​
Policy Breaks Communication

Cause: Incomplete observation - not all traffic was captured. Solution:
  1. Extend observation period (let app run longer)
  2. Check pod logs for connection errors
  3. Manually add missing rules to the policy

​
Debug Mode

Enable debug logging for more details: 
# For controller
helm upgrade kguardian kguardian/kguardian \
  --namespace kguardian \
  --set controller.debug=true \
  --reuse-values

# For CLI
kubectl kguardian gen netpol my-app --debug

Still having issues?

Ask for help in GitHub Discussions →