privilegedescalation/headlamp-polaris-plugin
Archived
12
0
Fork 0
Code Issues 4 Pull Requests 3 Actions Packages Projects Releases 50 Wiki Activity

docs: remove incorrect watchPlugins: false references

Browse Source 
Remove all references to the incorrect `config.watchPlugins: false`
requirement that was believed necessary for Headlamp v0.39.0+.

Investigation revealed that plugins work correctly with the default
`watchPlugins: true` setting. The earlier documentation was based on
a misunderstanding of the plugin loading mechanism.

Changes:
- Remove watchPlugins: false from all YAML configuration examples
- Remove warning sections about watchPlugins requirement
- Update troubleshooting guides to focus on actual issues
- Simplify installation instructions by removing unnecessary config

Files updated:
- README.md (main installation docs and troubleshooting table)
- docs/DEPLOYMENT.md
- docs/TROUBLESHOOTING.md
- docs/getting-started/* (quick-start, installation, prerequisites)
- docs/deployment/* (helm, production)
- docs/troubleshooting/* (common-issues, README)
- Multiple other doc files formatted by prettier

This cleanup ensures ArtifactHub and GitHub documentation show
correct, simplified installation instructions.

Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
Co-Authored-By: Happy <yesreply@happy.engineering>
This commit is contained in:
Chris Farhood
2026-02-13 09:54:15 -05:00
parent 0faa50cd9d
commit 24033ca977
25 changed files with 775 additions and 468 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/troubleshooting/README.md
+18 -20
View File
@@ -4,17 +4,17 @@ Quick diagnosis guide and common issues for the Headlamp Polaris Plugin.
## Quick Diagnosis
| Symptom | Likely Cause | Quick Fix | Details |
|---------|-------------|-----------|---------|
| **Plugin not in sidebar** | Headlamp v0.39.0+ plugin loading issue | Set `config.watchPlugins: false` and hard refresh (Cmd+Shift+R) | [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) |
| 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
@@ -56,11 +56,6 @@ kubectl -n kube-system logs deployment/headlamp | grep -i polaris
### Plugin Loading Verification
```bash
# Check Headlamp config
kubectl -n kube-system get configmap headlamp -o yaml | grep watchPlugins
# Expected: watchPlugins: "false"
# Verify plugin files exist
kubectl -n kube-system exec deployment/headlamp -c headlamp -- \
ls -la /headlamp/plugins/headlamp-polaris-plugin/
@@ -115,6 +110,7 @@ kubectl run -it --rm debug --image=curlimages/curl --restart=Never -- \
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
@@ -132,12 +128,12 @@ kubectl run -it --rm debug --image=curlimages/curl --restart=Never -- \
```javascript
// Open browser console and run:
localStorage.getItem('polaris-plugin-refresh-interval')
localStorage.getItem('polaris-plugin-dashboard-url')
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')
localStorage.removeItem('polaris-plugin-refresh-interval');
localStorage.removeItem('polaris-plugin-dashboard-url');
```
## Still Having Issues?
@@ -145,11 +141,13 @@ localStorage.removeItem('polaris-plugin-dashboard-url')
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)
docs/troubleshooting/common-issues.md
+65 -28
View File
@@ -20,34 +20,17 @@ This guide covers common issues encountered when using the Headlamp Polaris Plug
## Plugin Not Showing in Sidebar
### Symptoms
- Plugin appears in Settings → Plugins but sidebar entry is missing
- No "Polaris" section in navigation
- Routes like `/polaris` return 404 or blank page
### Common Causes
**1. Headlamp v0.39.0+ Plugin Loading Issue**
**Root Cause**: Headlamp v0.39.0+ changed plugin loading behavior. With `config.watchPlugins: true` (default), catalog-managed plugins are treated as "development directory" plugins, causing the backend to serve metadata but frontend to never execute the JavaScript.
**Solution**: Set `config.watchPlugins: false` in Headlamp configuration.
```yaml
# HelmRelease values
config:
watchPlugins: false # CRITICAL for plugin manager
```
After applying this change:
1. Restart Headlamp pod
2. Hard refresh browser (Cmd+Shift+R or Ctrl+Shift+R)
3. Clear browser cache if needed
**References**: See `deployment/PLUGIN_LOADING_FIX.md` for complete root cause analysis.
**2. Plugin Not Installed**
**1. Plugin Not Installed**
**Check plugin installation**:
```bash
# View Headlamp pod logs (plugin sidecar)
kubectl logs -n kube-system deployment/headlamp -c headlamp-plugin
@@ -58,23 +41,26 @@ kubectl logs -n kube-system deployment/headlamp -c headlamp-plugin
```
**Verify plugin files exist**:
```bash
kubectl exec -n kube-system deployment/headlamp -c headlamp -- ls -la /headlamp/plugins/
# Should show: headlamp-polaris-plugin/
```
**3. JavaScript Cached by Browser**
**2. JavaScript Cached by Browser**
After upgrading the plugin, old JavaScript may be cached.
**Solution**:
- Hard refresh: Cmd+Shift+R (macOS) or Ctrl+Shift+R (Linux/Windows)
- Clear browser cache for Headlamp domain
- Open DevTools → Application → Clear Storage → Clear all
**4. Plugin Disabled in Settings**
**3. Plugin Disabled in Settings**
**Check Settings → Plugins**:
- Navigate to Headlamp Settings → Plugins
- Ensure "Polaris" plugin is enabled (toggle should be ON)
- If disabled, enable it and refresh the page
@@ -84,11 +70,13 @@ After upgrading the plugin, old JavaScript may be cached.
## 403 Forbidden Error
### Symptoms
- Error message: "Error loading Polaris audit data: 403 Forbidden"
- Browser console shows 403 response from API proxy
- Plugin sidebar shows but data fails to load
### Root Cause
User or service account lacks `services/proxy` permission on `polaris-dashboard` service in the `polaris` namespace.
### Solution
@@ -96,11 +84,13 @@ User or service account lacks `services/proxy` permission on `polaris-dashboard`
**1. Verify RBAC Configuration**
Check if Role exists:
```bash
kubectl get role polaris-proxy-reader -n polaris -o yaml
```
Expected output:
```yaml
apiVersion: rbac.authorization.k8s.io/v1
kind: Role
@@ -108,20 +98,22 @@ metadata:
name: polaris-proxy-reader
namespace: polaris
rules:
- apiGroups: [""]
resources: ["services/proxy"]
resourceNames: ["polaris-dashboard"]
verbs: ["get"]
- apiGroups: ['']
resources: ['services/proxy']
resourceNames: ['polaris-dashboard']
verbs: ['get']
```
**2. Verify RoleBinding**
For service account mode:
```bash
kubectl get rolebinding headlamp-polaris-proxy -n polaris -o yaml
```
Expected subjects:
```yaml
subjects:
- kind: ServiceAccount
@@ -130,6 +122,7 @@ subjects:
```
For OIDC mode:
```bash
kubectl get rolebinding -n polaris -o yaml | grep -A 5 polaris-proxy-reader
```
@@ -172,6 +165,7 @@ EOF
**4. Test RBAC Permissions**
Service account mode:
```bash
# Impersonate Headlamp service account
kubectl auth can-i get services/proxy \
@@ -182,6 +176,7 @@ kubectl auth can-i get services/proxy \
```
OIDC mode (test as yourself):
```bash
kubectl auth can-i get services/proxy \
--resource-name=polaris-dashboard \
@@ -192,6 +187,7 @@ kubectl auth can-i get services/proxy \
**5. Restart Headlamp**
After applying RBAC changes:
```bash
kubectl rollout restart deployment headlamp -n kube-system
```
@@ -201,11 +197,13 @@ kubectl rollout restart deployment headlamp -n kube-system
## 404 Not Found Error
### Symptoms
- Error message: "Error loading Polaris audit data: 404 Not Found"
- Service proxy request returns 404
- Polaris dashboard not reachable
### Root Cause
Polaris dashboard service doesn't exist or is in a different namespace.
### Solution
@@ -213,12 +211,14 @@ Polaris dashboard service doesn't exist or is in a different namespace.
**1. Verify Polaris Installation**
Check if Polaris is installed:
```bash
kubectl get pods -n polaris
# Expected: polaris-dashboard-* pod running
```
Check if service exists:
```bash
kubectl get service polaris-dashboard -n polaris
# Expected: ClusterIP service on port 80
@@ -227,6 +227,7 @@ kubectl get service polaris-dashboard -n polaris
**2. Verify Service Name and Port**
The plugin expects:
- **Namespace**: `polaris`
- **Service Name**: `polaris-dashboard`
- **Port**: `80` (or named port `dashboard`)
@@ -246,11 +247,13 @@ If this returns 404, Polaris service is not configured correctly.
**4. Check Polaris Dashboard Configuration**
Verify Polaris is running with dashboard enabled:
```bash
kubectl get deployment polaris-dashboard -n polaris -o yaml | grep -A 5 dashboard
```
If `dashboard.enabled: false` in Helm values, enable it:
```yaml
# values.yaml
dashboard:
@@ -260,6 +263,7 @@ dashboard:
**5. Reinstall Polaris**
If Polaris is missing or misconfigured:
```bash
helm repo add fairwinds-stable https://charts.fairwinds.com/stable
helm upgrade --install polaris fairwinds-stable/polaris \
@@ -273,21 +277,25 @@ helm upgrade --install polaris fairwinds-stable/polaris \
## Plugin Settings Page Empty
### Symptoms
- Settings → Polaris shows title but no content
- Refresh interval and dashboard URL fields not visible
### Root Cause (Fixed in v0.3.3)
Plugin settings registration name didn't match `package.json` name.
### Solution
Upgrade to v0.3.3 or later:
```bash
# Via Headlamp UI: Settings → Plugins → Update
# Or redeploy with latest version
```
If manually installing, ensure plugin name matches `package.json`:
```typescript
registerPluginSettings('headlamp-polaris-plugin', PolarisSettings, true);
// NOT 'polaris' — must match package.json name
@@ -298,6 +306,7 @@ registerPluginSettings('headlamp-polaris-plugin', PolarisSettings, true);
## Dark Mode Issues
### Symptoms
- Drawer background remains white in dark mode
- Text is hard to read in dark mode
- Theme colors don't match Headlamp UI
@@ -308,6 +317,7 @@ Upgrade to v0.3.5 or later for complete dark mode support.
**Verify CSS Variables**:
The plugin uses MUI CSS variables for theming:
- `--mui-palette-background-default` (drawer background)
- `--mui-palette-text-primary` (text color)
- `--mui-palette-primary-main` (links, buttons)
@@ -317,6 +327,7 @@ These automatically adapt to Headlamp's theme (light/dark/system).
**Hard Refresh Required**:
After upgrading from v0.3.4 or earlier, hard refresh your browser:
- macOS: Cmd+Shift+R
- Linux/Windows: Ctrl+Shift+R
@@ -328,6 +339,7 @@ If hard refresh doesn't help, clear cache for Headlamp domain.
## Data Not Loading / Infinite Spinner
### Symptoms
- Plugin shows "Loading Polaris audit data..." forever
- No error message in UI
- Data never appears
@@ -339,6 +351,7 @@ If hard refresh doesn't help, clear cache for Headlamp domain.
Open DevTools (F12) → Console tab.
Look for:
- Network errors (CORS, timeouts, 5xx responses)
- JavaScript errors
- Failed API requests
@@ -348,6 +361,7 @@ Look for:
Open DevTools → Network tab → Filter by "results.json"
Expected request:
```
GET /api/v1/namespaces/polaris/services/polaris-dashboard:80/proxy/results.json
Status: 200
@@ -355,6 +369,7 @@ Response: JSON data
```
Common issues:
- **Status 0 / Failed**: Network policy blocking request
- **Status 403**: RBAC issue (see [403 Forbidden Error](#403-forbidden-error))
- **Status 404**: Service not found (see [404 Not Found Error](#404-not-found-error))
@@ -378,6 +393,7 @@ curl http://localhost:8080/results.json
**4. Check Network Policies**
If your cluster uses NetworkPolicies:
```bash
kubectl get networkpolicy -n polaris
```
@@ -385,6 +401,7 @@ kubectl get networkpolicy -n polaris
Ensure API server (or Headlamp pod) can reach Polaris dashboard.
**Example fix**:
```yaml
apiVersion: networking.k8s.io/v1
kind: NetworkPolicy
@@ -399,7 +416,7 @@ spec:
- Ingress
ingress:
- from:
- namespaceSelector: {} # Allow from all namespaces (API server)
- namespaceSelector: {} # Allow from all namespaces (API server)
ports:
- protocol: TCP
port: 8080
@@ -408,6 +425,7 @@ spec:
**5. Increase Timeout / Disable Auto-Refresh**
If Polaris responds slowly:
- Open Settings → Polaris
- Increase refresh interval to 10+ minutes
- Or set to "Manual only" to disable auto-refresh
@@ -423,6 +441,7 @@ If Polaris responds slowly:
**Cause**: Network request failed (CORS, network policy, timeout)
**Solution**:
1. Check Network tab for actual HTTP status
2. Verify network policies allow API server → Polaris
3. Check Polaris pod is running
@@ -434,6 +453,7 @@ If Polaris responds slowly:
**Cause**: API returned HTML (error page) instead of JSON
**Solution**:
1. Check Network tab response body (likely 404 or 500 error page)
2. Verify Polaris service exists and is healthy
3. Check service proxy URL is correct
@@ -453,6 +473,7 @@ If Polaris responds slowly:
**Cause**: Polaris returned empty or malformed response
**Solution**:
1. Check Polaris logs for errors
2. Verify Polaris is scanning the cluster (check audit timestamp)
3. Test `/results.json` endpoint directly
@@ -538,11 +559,13 @@ kubectl logs -n kube-system kube-apiserver-* | grep polaris-dashboard
### Sidecar Fails to Install Plugin
**Symptoms**:
- Plugin sidecar logs show download errors
- Plugin directory is empty
- Settings → Plugins shows nothing
**Check sidecar logs**:
```bash
kubectl logs -n kube-system deployment/headlamp -c headlamp-plugin
```
@@ -566,11 +589,13 @@ Error: 404 Not Found
```
**Solution**: Verify `archive-url` in plugin config matches GitHub release:
```bash
kubectl get configmap headlamp-plugin-config -n kube-system -o yaml
```
Expected format:
```
https://github.com/privilegedescalation/headlamp-polaris-plugin/releases/download/v0.3.10/polaris-0.3.10.tar.gz
```
@@ -580,6 +605,7 @@ https://github.com/privilegedescalation/headlamp-polaris-plugin/releases/downloa
**3. Permission denied writing to /headlamp/plugins**
**Solution**: Ensure volume mount is writable:
```yaml
volumeMounts:
- name: plugins
@@ -591,17 +617,18 @@ volumeMounts:
### Plugin Manager Not Working
**Symptoms**:
- Headlamp → Settings → Plugins shows "Catalog" tab but plugins don't install
- "Install" button does nothing
**Root Cause**: Plugin manager requires `config.pluginsDir` to be set.
**Solution**: Configure Headlamp for plugin manager:
```yaml
# HelmRelease values
config:
pluginsDir: /headlamp/plugins
watchPlugins: false # CRITICAL for v0.39.0+
```
---
@@ -609,25 +636,30 @@ config:
## ArtifactHub Sync Delays
### Symptoms
- New version released on GitHub but not showing in ArtifactHub
- Headlamp plugin catalog shows old version
### Root Cause
ArtifactHub pulls metadata every 30 minutes. There is no webhook or push mechanism.
### Solution
**Wait 30 minutes** after pushing a GitHub release, then check:
```
https://artifacthub.io/packages/headlamp/headlamp-polaris-plugin/headlamp-polaris-plugin
```
**Verify metadata**:
1. Check `artifacthub-pkg.yml` is in repository root
2. Check `headlamp/plugin/archive-url` points to GitHub release
3. Check `headlamp/plugin/archive-checksum` matches tarball SHA256
**Force sync** (ArtifactHub UI):
- Log in to ArtifactHub as package maintainer
- Go to package settings
- Click "Reindex now"
@@ -643,23 +675,28 @@ If none of these solutions work, gather debugging information and open an issue:
### Required Information
1. **Version Information**:
```bash
kubectl get pods -n kube-system -l app.kubernetes.io/name=headlamp -o yaml | grep image:
```
2. **Plugin Version**:
- Check Settings → Plugins in Headlamp UI
- Or: `kubectl exec -n kube-system deployment/headlamp -c headlamp -- cat /headlamp/plugins/headlamp-polaris-plugin/package.json`
3. **Browser Console Output**:
- Open DevTools (F12) → Console
- Screenshot or copy errors
4. **Network Tab**:
- Open DevTools → Network
- Screenshot failed requests to `results.json`
5. **Pod Logs**:
```bash
kubectl logs -n kube-system deployment/headlamp -c headlamp --tail=100
kubectl logs -n polaris deployment/polaris-dashboard --tail=100
docs/troubleshooting/network-problems.md
+1 -1
View File
@@ -87,7 +87,7 @@ dashboard:
enabled: true
env:
- name: CORS_ALLOWED_ORIGINS
value: "https://headlamp.example.com"
value: 'https://headlamp.example.com'
```
Test CORS headers:
docs/troubleshooting/rbac-issues.md
+1 -1
View File
@@ -70,7 +70,7 @@ metadata:
namespace: polaris
subjects:
- kind: Group
name: system:authenticated # All authenticated users
name: system:authenticated # All authenticated users
apiGroup: rbac.authorization.k8s.io
roleRef:
kind: Role