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/getting-started/installation.md
+16 -30
View File
@@ -33,16 +33,19 @@ The plugin is published on [Artifact Hub](https://artifacthub.io/packages/headla
#### Via Headlamp UI
1. **Navigate to Plugin Settings:**
- Open Headlamp in your browser
- Go to **Settings → Plugins**
- Click the **Catalog** tab
2. **Search and Install:**
- Search for "Polaris"
- Find "Headlamp Polaris Plugin"
- Click **Install**
3. **Hard Refresh Browser:**
- **Mac:** Cmd+Shift+R
- **Windows/Linux:** Ctrl+Shift+R
@@ -58,7 +61,6 @@ Add to your Headlamp Helm values:
# headlamp-values.yaml
config:
pluginsDir: /headlamp/plugins
watchPlugins: false # CRITICAL for v0.39.0+
pluginsManager:
enabled: true
@@ -76,23 +78,6 @@ helm upgrade --install headlamp headlamp/headlamp \
Then install the plugin via Headlamp UI as described above.
#### Critical Configuration for Headlamp v0.39.0+
**⚠️ IMPORTANT:** You **must** set `config.watchPlugins: false` or the plugin will not load.
**Why?**
- With `watchPlugins: true` (default), catalog-managed plugins are treated as "development directory" plugins
- This causes the backend to serve metadata but the frontend never executes the JavaScript
- Result: Plugin appears in Settings but no sidebar/routes/settings work
**Fix:**
```yaml
config:
watchPlugins: false # Required for plugin manager
```
See [deployment/PLUGIN_LOADING_FIX.md](../deployment/production.md#plugin-loading-issue-headlamp-v0390) for full root cause analysis.
### Option 2: Sidecar Container
**Best for:** Controlled plugin versions, air-gapped environments, specific version pinning
@@ -105,7 +90,6 @@ This method uses an init container to download and install the plugin from a tar
# headlamp-values.yaml
config:
pluginsDir: /headlamp/plugins
watchPlugins: false
initContainers:
- name: install-polaris-plugin
@@ -204,7 +188,7 @@ config:
volumes:
- name: plugins
hostPath:
path: /path/to/plugins # Where you extracted the tarball
path: /path/to/plugins # Where you extracted the tarball
type: Directory
volumeMounts:
@@ -316,6 +300,7 @@ kubectl -n kube-system wait --for=condition=ready pod -l app.kubernetes.io/name=
### 4. Verify Installation
**UI Verification:**
1. Navigate to **Settings → Plugins**
2. Verify "headlamp-polaris-plugin" is listed
3. Check version matches installed version
@@ -351,22 +336,22 @@ kubectl get --raw /api/v1/namespaces/polaris/services/polaris-dashboard:80/proxy
**Symptom:** Plugin listed in Settings → Plugins but no "Polaris" entry in sidebar
**Causes:**
1. `watchPlugins: true` (should be `false` for v0.39.0+)
2. Browser cache not cleared
3. Plugin JavaScript failed to load
1. Browser cache not cleared
2. Plugin JavaScript failed to load
3. Plugin files not properly installed
**Solution:**
```bash
# 1. Check Headlamp config
kubectl -n kube-system get configmap headlamp -o yaml | grep watchPlugins
# 1. Verify plugin files exist
kubectl -n kube-system exec deployment/headlamp -c headlamp -- \
ls -la /headlamp/plugins/headlamp-polaris-plugin/
# If "true" or missing, fix it:
kubectl -n kube-system edit configmap headlamp
# Set: watchPlugins: "false"
# Expected: dist/, package.json present
# 2. Restart Headlamp
kubectl -n kube-system rollout restart deployment/headlamp
# 2. Check Headlamp logs for plugin errors
kubectl -n kube-system logs deployment/headlamp | grep -i polaris
# 3. Hard refresh browser (Cmd+Shift+R or Ctrl+Shift+R)
@@ -389,6 +374,7 @@ See [RBAC Issues](../troubleshooting/rbac-issues.md) for detailed debugging.
**Symptom:** Error loading Polaris data, 404 in browser console
**Causes:**
1. Polaris not deployed
2. Polaris service name incorrect
3. Polaris namespace incorrect
docs/getting-started/prerequisites.md
+13 -13
View File
@@ -4,12 +4,12 @@ Before installing the Headlamp Polaris Plugin, ensure your environment meets the
## Required Components
| Requirement | Minimum Version | Recommended Version |
| -------------------------------- | ------------------ | ------------------- |
| **Kubernetes** | v1.24+ | v1.28+ |
| **Headlamp** | v0.26+ | v0.39+ |
| **Polaris** (dashboard enabled) | Any recent release | Latest stable |
| **Browser** | Modern (ES2020+) | Latest Chrome/Firefox/Safari/Edge |
| Requirement | Minimum Version | Recommended Version |
| ------------------------------- | ------------------ | --------------------------------- |
| **Kubernetes** | v1.24+ | v1.28+ |
| **Headlamp** | v0.26+ | v0.39+ |
| **Polaris** (dashboard enabled) | Any recent release | Latest stable |
| **Browser** | Modern (ES2020+) | Latest Chrome/Firefox/Safari/Edge |
## Polaris Requirements
@@ -91,7 +91,6 @@ helm repo update
helm install headlamp headlamp/headlamp \
--namespace kube-system \
--set config.pluginsDir="/headlamp/plugins" \
--set config.watchPlugins=false \
--set pluginsManager.enabled=true
# Wait for pod to be ready
@@ -133,6 +132,7 @@ Headlamp Pod → Kubernetes API Server → Polaris Dashboard Service
```
**Required network paths:**
- Headlamp pod → Kubernetes API server (443)
- Kubernetes API server → Polaris dashboard service (80)
@@ -161,12 +161,12 @@ The plugin uses modern JavaScript features and requires:
### Tested Browsers
| Browser | Minimum Version |
| ---------------- | --------------- |
| Chrome/Chromium | 80+ |
| Firefox | 75+ |
| Safari | 13.1+ |
| Edge | 80+ |
| Browser | Minimum Version |
| --------------- | --------------- |
| Chrome/Chromium | 80+ |
| Firefox | 75+ |
| Safari | 13.1+ |
| Edge | 80+ |
## Optional Components
docs/getting-started/quick-start.md
+8 -9
View File
@@ -29,7 +29,6 @@ Don't have these? See [Prerequisites](prerequisites.md) for installation instruc
cat <<EOF > headlamp-values.yaml
config:
pluginsDir: /headlamp/plugins
watchPlugins: false # CRITICAL for v0.39.0+
pluginsManager:
enabled: true
@@ -86,14 +85,17 @@ EOF
### UI Verification
1. **Check Plugin is Loaded:**
- Go to **Settings → Plugins**
- Verify "headlamp-polaris-plugin" is listed
2. **Check Sidebar:**
- Look for **Polaris** entry in the left sidebar
- If not visible, hard refresh: **Cmd+Shift+R** / **Ctrl+Shift+R**
3. **View Overview Dashboard:**
- Click **Polaris** in sidebar
- Overview page loads with:
- Cluster score gauge
@@ -137,6 +139,7 @@ kubectl get --raw /api/v1/namespaces/polaris/services/polaris-dashboard:80/proxy
Navigate to **Polaris → Overview**:
- **Cluster Score Gauge:** Overall cluster health (0-100%)
- Green (≥80%): Excellent
- Yellow (50-79%): Needs improvement
- Red (<50%): Critical issues
@@ -181,15 +184,11 @@ Cluster score badge in top navigation:
### Plugin Not in Sidebar
```bash
# Check Headlamp config
kubectl -n kube-system get configmap headlamp -o yaml | grep watchPlugins
# Verify plugin files exist
kubectl -n kube-system exec -it deployment/headlamp -c headlamp -- \
ls /headlamp/plugins/headlamp-polaris-plugin/
# If "true" or missing, set to false:
kubectl -n kube-system edit configmap headlamp
# Set: watchPlugins: "false"
# Restart Headlamp
kubectl -n kube-system rollout restart deployment/headlamp
# If missing, reinstall via Headlamp UI or sidecar method
# Hard refresh browser
# Cmd+Shift+R (Mac) or Ctrl+Shift+R (Windows/Linux)