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:
+11
-18
@@ -31,7 +31,6 @@ helm repo update
|
||||
# headlamp-values.yaml
|
||||
config:
|
||||
pluginsDir: /headlamp/plugins
|
||||
watchPlugins: false # CRITICAL for v0.39.0+
|
||||
|
||||
pluginsManager:
|
||||
enabled: true
|
||||
@@ -63,9 +62,8 @@ image:
|
||||
pullPolicy: IfNotPresent
|
||||
|
||||
config:
|
||||
baseURL: ""
|
||||
baseURL: ''
|
||||
pluginsDir: /headlamp/plugins
|
||||
watchPlugins: false # MUST be false for plugin manager
|
||||
|
||||
pluginsManager:
|
||||
enabled: true
|
||||
@@ -81,7 +79,7 @@ ingress:
|
||||
className: nginx
|
||||
annotations:
|
||||
cert-manager.io/cluster-issuer: letsencrypt-prod
|
||||
nginx.ingress.kubernetes.io/force-ssl-redirect: "true"
|
||||
nginx.ingress.kubernetes.io/force-ssl-redirect: 'true'
|
||||
hosts:
|
||||
- host: headlamp.example.com
|
||||
paths:
|
||||
@@ -117,16 +115,16 @@ affinity:
|
||||
# OIDC Authentication (optional)
|
||||
env:
|
||||
- name: HEADLAMP_CONFIG_OIDC_CLIENT_ID
|
||||
value: "headlamp"
|
||||
value: 'headlamp'
|
||||
- name: HEADLAMP_CONFIG_OIDC_CLIENT_SECRET
|
||||
valueFrom:
|
||||
secretKeyRef:
|
||||
name: headlamp-oidc
|
||||
key: client-secret
|
||||
- name: HEADLAMP_CONFIG_OIDC_ISSUER_URL
|
||||
value: "https://auth.example.com/realms/kubernetes"
|
||||
value: 'https://auth.example.com/realms/kubernetes'
|
||||
- name: HEADLAMP_CONFIG_OIDC_SCOPES
|
||||
value: "openid,profile,email,groups"
|
||||
value: 'openid,profile,email,groups'
|
||||
```
|
||||
|
||||
Deploy:
|
||||
@@ -147,7 +145,6 @@ Alternative to Plugin Manager: use an init container to download the plugin.
|
||||
# headlamp-values.yaml
|
||||
config:
|
||||
pluginsDir: /headlamp/plugins
|
||||
watchPlugins: false
|
||||
|
||||
initContainers:
|
||||
- name: install-polaris-plugin
|
||||
@@ -230,7 +227,7 @@ spec:
|
||||
chart:
|
||||
spec:
|
||||
chart: headlamp
|
||||
version: 0.26.x # Use semver range
|
||||
version: 0.26.x # Use semver range
|
||||
sourceRef:
|
||||
kind: HelmRepository
|
||||
name: headlamp
|
||||
@@ -252,7 +249,6 @@ spec:
|
||||
|
||||
config:
|
||||
pluginsDir: /headlamp/plugins
|
||||
watchPlugins: false
|
||||
|
||||
pluginsManager:
|
||||
enabled: true
|
||||
@@ -388,15 +384,12 @@ kubectl -n kube-system rollout status deployment/headlamp
|
||||
# Check Headlamp values
|
||||
helm get values headlamp -n kube-system
|
||||
|
||||
# Verify watchPlugins is false:
|
||||
# config:
|
||||
# watchPlugins: false
|
||||
# Verify plugin files exist
|
||||
kubectl -n kube-system exec deployment/headlamp -c headlamp -- \
|
||||
ls -la /headlamp/plugins/headlamp-polaris-plugin/
|
||||
|
||||
# If incorrect, update values and upgrade:
|
||||
helm upgrade headlamp headlamp/headlamp \
|
||||
--namespace kube-system \
|
||||
--values headlamp-values.yaml \
|
||||
--set config.watchPlugins=false
|
||||
# If missing, reinstall plugin via UI or check init container logs
|
||||
kubectl -n kube-system logs deployment/headlamp -c install-polaris-plugin
|
||||
```
|
||||
|
||||
### Helm Release Stuck
|
||||
|
||||
@@ -29,10 +29,10 @@ metadata:
|
||||
app.kubernetes.io/name: headlamp-polaris-plugin
|
||||
app.kubernetes.io/component: rbac
|
||||
rules:
|
||||
- apiGroups: [""]
|
||||
resources: ["services/proxy"]
|
||||
resourceNames: ["polaris-dashboard"]
|
||||
verbs: ["get"]
|
||||
- apiGroups: ['']
|
||||
resources: ['services/proxy']
|
||||
resourceNames: ['polaris-dashboard']
|
||||
verbs: ['get']
|
||||
|
||||
---
|
||||
# RoleBinding: Grant Headlamp service account access
|
||||
@@ -145,11 +145,11 @@ spec:
|
||||
- name: headlamp
|
||||
image: ghcr.io/headlamp-k8s/headlamp:v0.39.0
|
||||
args:
|
||||
- "-in-cluster"
|
||||
- "-plugins-dir=/headlamp/plugins"
|
||||
- '-in-cluster'
|
||||
- '-plugins-dir=/headlamp/plugins'
|
||||
env:
|
||||
- name: HEADLAMP_CONFIG_WATCH_PLUGINS
|
||||
value: "false" # CRITICAL: Must be false for plugin manager
|
||||
value: 'false' # CRITICAL: Must be false for plugin manager
|
||||
ports:
|
||||
- name: http
|
||||
containerPort: 4466
|
||||
|
||||
@@ -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
|
||||
|
||||
Reference in New Issue
Block a user