headlamp-polaris-plugin/docs/troubleshooting/README.md

Troubleshooting

Quick diagnosis guide and common issues for the Headlamp Polaris Plugin.

Quick Diagnosis

Symptom	Likely Cause	Quick Fix	Details
Plugin not in sidebar	Browser cache or plugin not installed	Hard refresh browser (Cmd+Shift+R) and verify plugin files exist	Common Issues
403 Access Denied	Missing RBAC binding for services/proxy	Apply Role + RoleBinding from RBAC section	RBAC Issues
404 or 503	Polaris not installed, or dashboard disabled	Install Polaris with dashboard.enabled: true in polaris namespace	Common Issues
Dark mode white backgrounds	Old plugin version	Upgrade to v0.3.5+ and hard refresh browser	Common Issues
Settings page empty	Old plugin version	Upgrade to v0.3.3+	Common Issues
No data / infinite spinner	Network policy or Polaris pod down	Check network policies and kubectl get pods -n polaris	Network Problems
Namespace drawer white	CSS variable issue	Update to v0.3.5+ with --mui-palette-background-paper	Common Issues
Cluster score not updating	Auto-refresh disabled or interval too long	Check Settings → Plugins → Polaris refresh interval	Common Issues
Custom URL not working	CORS or incorrect URL format	Test with curl, check CORS headers	Network Problems

Detailed Guides

• Common Issues - Comprehensive guide to frequent problems and solutions
• RBAC Issues - Permission debugging, 403 errors, token-auth mode
• Network Problems - NetworkPolicies, connectivity, proxy issues, CORS

Diagnostic Commands

Quick Health Check

# 1. Verify Polaris is running
kubectl -n polaris get pods
kubectl -n polaris get svc polaris-dashboard

# 2. Test Polaris API access
kubectl get --raw /api/v1/namespaces/polaris/services/polaris-dashboard:80/proxy/results.json | jq .PolarisOutputVersion

# Expected output: "1.0" or similar

# 3. Verify RBAC permissions
kubectl auth can-i get services/proxy \
  --as=system:serviceaccount:kube-system:headlamp \
  -n polaris \
  --resource-name=polaris-dashboard

# Expected output: yes

# 4. Check Headlamp pod is running
kubectl -n kube-system get pods -l app.kubernetes.io/name=headlamp

# 5. Check Headlamp logs for plugin errors
kubectl -n kube-system logs deployment/headlamp | grep -i polaris

# Expected: No errors

Plugin Loading Verification

# Verify plugin files exist
kubectl -n kube-system exec deployment/headlamp -c headlamp -- \
  ls -la /headlamp/plugins/headlamp-polaris-plugin/

# Expected output:
# drwxr-xr-x  dist/
# -rw-r--r--  package.json

RBAC Verification

# Check Role exists
kubectl -n polaris get role polaris-proxy-reader

# Check RoleBinding exists
kubectl -n polaris get rolebinding headlamp-polaris-proxy

# Test permission (service account mode)
kubectl auth can-i get services/proxy \
  --as=system:serviceaccount:kube-system:headlamp \
  -n polaris \
  --resource-name=polaris-dashboard

# Test permission (user token mode, replace with your user)
kubectl auth can-i get services/proxy \
  --as=user@example.com \
  -n polaris \
  --resource-name=polaris-dashboard

Network Debugging

# Test from kubectl (uses same service proxy)
kubectl get --raw /api/v1/namespaces/polaris/services/polaris-dashboard:80/proxy/results.json

# Check NetworkPolicies
kubectl -n polaris get networkpolicy

# Test direct service access (from within cluster)
kubectl run -it --rm debug --image=curlimages/curl --restart=Never -- \
  curl http://polaris-dashboard.polaris/results.json

Browser Debugging

Check Browser Console

1. Open browser DevTools (F12)
2. Go to Console tab
3. Look for errors containing "polaris" or "plugin"

Common errors:

• createSvgIcon is not defined → MUI import issue (plugin bug)
• 403 Forbidden → RBAC permission denied
• 404 Not Found → Polaris not installed or wrong URL
• Failed to fetch → Network policy or CORS issue

Clear Browser Cache

Critical: After plugin updates, hard refresh to clear cached JavaScript:

• Mac: Cmd+Shift+R
• Windows/Linux: Ctrl+Shift+R
• Alternatively: Clear all browser data for Headlamp URL

Check localStorage

// Open browser console and run:
localStorage.getItem('polaris-plugin-refresh-interval');
localStorage.getItem('polaris-plugin-dashboard-url');

// Reset to defaults:
localStorage.removeItem('polaris-plugin-refresh-interval');
localStorage.removeItem('polaris-plugin-dashboard-url');

Still Having Issues?

If the quick diagnosis doesn't resolve your issue:

1. Check detailed guides:

   • Common Issues
   • RBAC Issues
   • Network Problems

2. Review documentation:

   • Installation Guide
   • RBAC Permissions
   • Deployment Guide

3. Open a GitHub issue:

   • GitHub Issues
   • Include: Headlamp version, plugin version, error messages, logs

References

• Headlamp Troubleshooting
• Polaris Troubleshooting
• Kubernetes RBAC Troubleshooting