docs: remove incorrect watchPlugins: false references

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:
2026-02-13 09:54:15 -05:00
parent 0faa50cd9d
commit 24033ca977
25 changed files with 775 additions and 468 deletions
+13 -34
View File
@@ -46,7 +46,6 @@ kubectl -n kube-system get svc headlamp
### Deployment
- [ ] Plugin installed via Plugin Manager or sidecar init container
- [ ] `config.watchPlugins: false` set in Headlamp configuration
- [ ] RBAC Role and RoleBinding applied
- [ ] NetworkPolicies configured (if using strict network policies)
- [ ] Headlamp pods running with 2+ replicas (high availability)
@@ -121,7 +120,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
@@ -134,7 +133,7 @@ For fine-grained control, bind specific users or groups:
```yaml
subjects:
- kind: Group
name: sre-team # Only SRE team
name: sre-team # Only SRE team
apiGroup: rbac.authorization.k8s.io
```
@@ -185,12 +184,12 @@ Kubernetes audit logs record every service proxy request:
apiVersion: audit.k8s.io/v1
kind: Policy
rules:
- level: Metadata # Log metadata only (not full request/response)
verbs: ["get"]
- level: Metadata # Log metadata only (not full request/response)
verbs: ['get']
resources:
- group: ""
resources: ["services/proxy"]
namespaces: ["polaris"]
- group: ''
resources: ['services/proxy']
namespaces: ['polaris']
```
### Data Sensitivity
@@ -354,8 +353,8 @@ spec:
labels:
severity: warning
annotations:
summary: "Headlamp pod not ready"
description: "Pod {{ $labels.pod }} in namespace {{ $labels.namespace }} has been not ready for 5 minutes."
summary: 'Headlamp pod not ready'
description: 'Pod {{ $labels.pod }} in namespace {{ $labels.namespace }} has been not ready for 5 minutes.'
```
## Performance Tuning
@@ -414,12 +413,14 @@ Adjust based on cluster size and user count.
If Headlamp or plugin becomes unavailable:
1. **Verify Polaris is running:**
```bash
kubectl -n polaris get pods
kubectl -n polaris get svc polaris-dashboard
```
2. **Redeploy Headlamp:**
```bash
helm upgrade --install headlamp headlamp/headlamp \
--namespace kube-system \
@@ -427,11 +428,13 @@ If Headlamp or plugin becomes unavailable:
```
3. **Reapply RBAC:**
```bash
kubectl apply -f polaris-plugin-rbac.yaml
```
4. **Verify plugin files:**
```bash
kubectl -n kube-system exec deployment/headlamp -- \
ls /headlamp/plugins/headlamp-polaris-plugin/
@@ -442,30 +445,6 @@ If Headlamp or plugin becomes unavailable:
## Known Issues
### Plugin Loading Issue (Headlamp v0.39.0+)
**Symptom:** Plugin appears in Settings but not in sidebar
**Cause:** `config.watchPlugins: true` (default) treats catalog plugins as development plugins
**Fix:**
```yaml
config:
watchPlugins: false # Required for plugin manager
```
**Root Cause:**
With `watchPlugins: true`, Headlamp backend serves plugin metadata but frontend never executes the JavaScript. This causes plugins to appear in Settings but no sidebar/routes/settings work.
**Documentation:** See `deployment/PLUGIN_LOADING_FIX.md` in repository for full analysis.
**After Fix:**
- Restart Headlamp deployment
- Hard refresh browser (**Cmd+Shift+R** / **Ctrl+Shift+R**)
### Skipped Count Limitation
**Symptom:** "Skipped" count in UI is lower than native Polaris dashboard