privilegedescalation/headlamp-polaris-plugin
12
0
Fork 0
Code Issues 4 Pull Requests 3 Actions Packages Projects Releases 50 Wiki Activity
Files
6c04ca39a2cfa85639bee327e53b2b62dc1cc46a
headlamp-polaris-plugin/docs/troubleshooting/README.md
T
privilegedescalation-ceo[bot] e2ae92648c docs: replace hardcoded namespace with <your-namespace> placeholder 
* docs: update Headlamp install namespace references from kube-system to headlamp

Updates all documentation references to the Headlamp install namespace
from kube-system to headlamp as part of PRI-433.

In-scope files updated:
- README.md, SECURITY.md
- docs/getting-started/installation.md, quick-start.md, prerequisites.md
- docs/deployment/helm.md, kubernetes.md, production.md
- docs/troubleshooting/README.md, common-issues.md, rbac-issues.md
- docs/user-guide/configuration.md, rbac-permissions.md
- docs/TESTING.md, TROUBLESHOOTING.md, DEPLOYMENT.md

Out-of-scope (unchanged):
- Source files referencing upstream workload namespace
- RBAC manifests describing Polaris namespace (polaris ns is unchanged)
- NetworkPolicy namespaceSelector (API server runs in kube-system)
- design-decisions.md and ARCHITECTURE.md (URL hashes refer to cluster namespaces, not Headlamp install ns)

Co-Authored-By: Paperclip <noreply@paperclip.ing>

* fix: correct RBAC manifest per QA review (PRI-555)

- Remove rbac.authorization.k8s.io privilege escalation block
- Fix orphaned comment from round 1
- Add EOF newline
- Keep serviceaccounts/token for E2E auth (confirmed needed)
- Namespace already correct (privilegedescalation-dev)

Co-Authored-By: Paperclip <noreply@paperclip.ing>

* docs: replace hardcoded namespace with <your-namespace> placeholder

Users choose their own namespace for Headlamp. Replace all hardcoded
namespace references (headlamp, kube-system) in user-facing docs with
<your-namespace> so users substitute their own value.

Conventions:
- Helm install: --namespace <your-namespace> --create-namespace
- kubectl commands: -n <your-namespace>
- YAML metadata: namespace: <your-namespace>
- Prose: "the namespace where Headlamp is installed"

Out-of-scope references left untouched:
- kube-system in NetworkPolicy selectors (API server namespace)
- polaris namespace references (upstream workload namespace)
- Source code and test files

Refs: PRI-433

Co-Authored-By: Paperclip <noreply@paperclip.ing>

* docs: fix remaining hardcoded headlamp namespace to <your-namespace> placeholder

Prior commit was inconsistent — some files used <your-namespace> while
DEPLOYMENT.md, TROUBLESHOOTING.md and several troubleshooting/user-guide
docs still hardcoded headlamp as the namespace.

Co-Authored-By: Paperclip <noreply@paperclip.ing>

---------

Co-authored-by: Chris Farhood <chris@farhood.org>
Co-authored-by: Paperclip <noreply@paperclip.ing>
2026-05-10 21:34:49 +00:00

164 lines
6.5 KiB
Markdown
Raw Blame History

# 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](common-issues.md#plugin-not-in-sidebar) |
| **403 Access Denied** | Missing RBAC binding for `services/proxy` | Apply Role + RoleBinding from RBAC section | [RBAC Issues](rbac-issues.md) |
| **404 or 503** | Polaris not installed, or dashboard disabled | Install Polaris with `dashboard.enabled: true` in `polaris` namespace | [Common Issues](common-issues.md#404-not-found) |
| **Dark mode white backgrounds** | Old plugin version | Upgrade to v0.3.5+ and hard refresh browser | [Common Issues](common-issues.md#dark-mode-issues) |
| **Settings page empty** | Old plugin version | Upgrade to v0.3.3+ | [Common Issues](common-issues.md#settings-page-empty) |
| **No data / infinite spinner** | Network policy or Polaris pod down | Check network policies and `kubectl get pods -n polaris` | [Network Problems](network-problems.md) |
| **Namespace drawer white** | CSS variable issue | Update to v0.3.5+ with `--mui-palette-background-paper` | [Common Issues](common-issues.md#dark-mode-issues) |
| **Cluster score not updating** | Auto-refresh disabled or interval too long | Check Settings → Plugins → Polaris refresh interval | [Common Issues](common-issues.md#data-not-refreshing) |
| **Custom URL not working** | CORS or incorrect URL format | Test with curl, check CORS headers | [Network Problems](network-problems.md#cors-issues) |
## Detailed Guides
- **[Common Issues](common-issues.md)** - Comprehensive guide to frequent problems and solutions
- **[RBAC Issues](rbac-issues.md)** - Permission debugging, 403 errors, token-auth mode
- **[Network Problems](network-problems.md)** - NetworkPolicies, connectivity, proxy issues, CORS
## Diagnostic Commands
### Quick Health Check
```bash
# 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:<your-namespace>:headlamp \
-n polaris \
--resource-name=polaris-dashboard
# Expected output: yes
# 4. Check Headlamp pod is running
kubectl -n <your-namespace> get pods -l app.kubernetes.io/name=headlamp
# 5. Check Headlamp logs for plugin errors
kubectl -n <your-namespace> logs deployment/headlamp | grep -i polaris
# Expected: No errors
```
### Plugin Loading Verification
```bash
# Verify plugin files exist
kubectl -n <your-namespace> 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
```bash
# 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:<your-namespace>: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
```bash
# 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
```javascript
// 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](common-issues.md)
- [RBAC Issues](rbac-issues.md)
- [Network Problems](network-problems.md)
2. **Review documentation:**
- [Installation Guide](../getting-started/installation.md)
- [RBAC Permissions](../user-guide/rbac-permissions.md)
- [Deployment Guide](../deployment/kubernetes.md)
3. **Open a GitHub issue:**
- [GitHub Issues](https://github.com/privilegedescalation/headlamp-polaris-plugin/issues)
- Include: Headlamp version, plugin version, error messages, logs
## References
- [Headlamp Troubleshooting](https://headlamp.dev/docs/latest/troubleshooting/)
- [Polaris Troubleshooting](https://polaris.docs.fairwinds.com/troubleshooting/)
- [Kubernetes RBAC Troubleshooting](https://kubernetes.io/docs/reference/access-authn-authz/rbac/#troubleshooting)
Reference in New Issue View Git Blame Copy Permalink