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

docs: update Headlamp install namespace references from kube-system to headlamp

Browse Source 
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>
This commit is contained in:
Chris Farhood
2026-05-04 07:25:28 +00:00
committed by Gandalf the Greybeard [agent]
parent dff1265435
commit e2f220c418
17 changed files with 136 additions and 138 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/deployment/helm.md
+20 -20
View File
@@ -41,11 +41,11 @@ pluginsManager:
```bash
# Install Headlamp
helm install headlamp headlamp/headlamp \
--namespace kube-system \
--namespace headlamp \
--values headlamp-values.yaml
# Wait for deployment
kubectl -n kube-system wait --for=condition=available deployment/headlamp --timeout=300s
kubectl -n headlamp wait --for=condition=available deployment/headlamp --timeout=300s
```
After installation, install the plugin via Headlamp UI (**Settings → Plugins → Catalog**).
@@ -131,7 +131,7 @@ Deploy:
```bash
helm upgrade --install headlamp headlamp/headlamp \
--namespace kube-system \
--namespace headlamp \
--values headlamp-values.yaml \
--wait \
--timeout 5m
@@ -177,7 +177,7 @@ apiVersion: v1
kind: ConfigMap
metadata:
name: headlamp-plugin-config
namespace: kube-system
namespace: headlamp
data:
plugin.yml: |
- name: headlamp-polaris-plugin
@@ -191,7 +191,7 @@ Apply ConfigMap then deploy Headlamp:
kubectl apply -f headlamp-plugin-config.yaml
helm upgrade --install headlamp headlamp/headlamp \
--namespace kube-system \
--namespace headlamp \
--values headlamp-values.yaml
```
@@ -221,7 +221,7 @@ apiVersion: helm.toolkit.fluxcd.io/v2
kind: HelmRelease
metadata:
name: headlamp
namespace: kube-system
namespace: headlamp
spec:
interval: 30m
chart:
@@ -300,7 +300,7 @@ kubectl apply -f helmrepository.yaml
kubectl apply -f helmrelease.yaml
# Watch deployment
flux get helmreleases -n kube-system --watch
flux get helmreleases -n headlamp --watch
```
## RBAC Configuration
@@ -329,7 +329,7 @@ metadata:
subjects:
- kind: ServiceAccount
name: headlamp
namespace: kube-system
namespace: headlamp
roleRef:
kind: Role
name: polaris-proxy-reader
@@ -349,7 +349,7 @@ helm repo update
# Upgrade Headlamp (preserves plugin configuration)
helm upgrade headlamp headlamp/headlamp \
--namespace kube-system \
--namespace headlamp \
--values headlamp-values.yaml \
--wait
```
@@ -365,15 +365,15 @@ helm upgrade headlamp headlamp/headlamp \
```bash
# Update ConfigMap with new version
kubectl -n kube-system edit configmap headlamp-plugin-config
kubectl -n headlamp edit configmap headlamp-plugin-config
# Update version and URL:
# version: 0.3.6
# url: https://github.com/.../v0.3.6/polaris-0.3.10.tar.gz
# Restart deployment to trigger init container
kubectl -n kube-system rollout restart deployment/headlamp
kubectl -n kube-system rollout status deployment/headlamp
kubectl -n headlamp rollout restart deployment/headlamp
kubectl -n headlamp rollout status deployment/headlamp
```
## Troubleshooting
@@ -382,25 +382,25 @@ kubectl -n kube-system rollout status deployment/headlamp
```bash
# Check Headlamp values
helm get values headlamp -n kube-system
helm get values headlamp -n headlamp
# Verify plugin files exist
kubectl -n kube-system exec deployment/headlamp -c headlamp -- \
kubectl -n headlamp exec deployment/headlamp -c headlamp -- \
ls -la /headlamp/plugins/headlamp-polaris-plugin/
# If missing, reinstall plugin via UI or check init container logs
kubectl -n kube-system logs deployment/headlamp -c install-polaris-plugin
kubectl -n headlamp logs deployment/headlamp -c install-polaris-plugin
```
### Helm Release Stuck
```bash
# Check Helm release status
helm list -n kube-system
helm list -n headlamp
# If stuck, force upgrade
helm upgrade headlamp headlamp/headlamp \
--namespace kube-system \
--namespace headlamp \
--values headlamp-values.yaml \
--force \
--wait
@@ -410,13 +410,13 @@ helm upgrade headlamp headlamp/headlamp \
```bash
# Check HelmRelease status
flux get helmreleases -n kube-system
flux get helmreleases -n headlamp
# Check events
kubectl -n kube-system describe helmrelease headlamp
kubectl -n headlamp describe helmrelease headlamp
# Force reconciliation
flux reconcile helmrelease headlamp -n kube-system
flux reconcile helmrelease headlamp -n headlamp
```
## Next Steps
docs/deployment/kubernetes.md
+21 -21
View File
@@ -47,7 +47,7 @@ metadata:
subjects:
- kind: ServiceAccount
name: headlamp
namespace: kube-system
namespace: headlamp
roleRef:
kind: Role
name: polaris-proxy-reader
@@ -71,7 +71,7 @@ kubectl -n polaris get rolebinding headlamp-polaris-proxy
# Test permission
kubectl auth can-i get services/proxy \
--as=system:serviceaccount:kube-system:headlamp \
--as=system:serviceaccount:headlamp:headlamp \
-n polaris \
--resource-name=polaris-dashboard
@@ -90,7 +90,7 @@ apiVersion: v1
kind: ConfigMap
metadata:
name: headlamp-plugin-config
namespace: kube-system
namespace: headlamp
labels:
app.kubernetes.io/name: headlamp
app.kubernetes.io/component: plugin-config
@@ -109,7 +109,7 @@ apiVersion: apps/v1
kind: Deployment
metadata:
name: headlamp
namespace: kube-system
namespace: headlamp
labels:
app.kubernetes.io/name: headlamp
spec:
@@ -194,7 +194,7 @@ apiVersion: v1
kind: ServiceAccount
metadata:
name: headlamp
namespace: kube-system
namespace: headlamp
labels:
app.kubernetes.io/name: headlamp
@@ -204,7 +204,7 @@ apiVersion: v1
kind: Service
metadata:
name: headlamp
namespace: kube-system
namespace: headlamp
labels:
app.kubernetes.io/name: headlamp
spec:
@@ -235,27 +235,27 @@ kubectl apply -f headlamp-service.yaml
kubectl apply -f headlamp-serviceaccount.yaml
# Wait for deployment to be ready
kubectl -n kube-system wait --for=condition=available deployment/headlamp --timeout=300s
kubectl -n headlamp wait --for=condition=available deployment/headlamp --timeout=300s
```
### 2. Verify Deployment
```bash
# Check pods are running
kubectl -n kube-system get pods -l app.kubernetes.io/name=headlamp
kubectl -n headlamp get pods -l app.kubernetes.io/name=headlamp
# Expected output:
# NAME READY STATUS RESTARTS AGE
# headlamp-xxxxxxxxxx-xxxxx 1/1 Running 0 2m
# Check init container logs
kubectl -n kube-system logs deployment/headlamp -c install-plugins
kubectl -n headlamp logs deployment/headlamp -c install-plugins
# Expected output:
# Plugin installation complete
# Verify plugin files exist
kubectl -n kube-system exec deployment/headlamp -c headlamp -- \
kubectl -n headlamp exec deployment/headlamp -c headlamp -- \
ls -la /headlamp/plugins/headlamp-polaris-plugin/
# Expected output:
@@ -273,7 +273,7 @@ kubectl get --raw /api/v1/namespaces/polaris/services/polaris-dashboard:80/proxy
```bash
# Port-forward to access locally
kubectl -n kube-system port-forward service/headlamp 8080:80
kubectl -n headlamp port-forward service/headlamp 8080:80
# Open browser to http://localhost:8080
```
@@ -309,7 +309,7 @@ k8s/
apiVersion: kustomize.config.k8s.io/v1beta1
kind: Kustomization
namespace: kube-system
namespace: headlamp
commonLabels:
app.kubernetes.io/name: headlamp
@@ -401,7 +401,7 @@ spec:
- apiVersion: apps/v1
kind: Deployment
name: headlamp
namespace: kube-system
namespace: headlamp
```
## Upgrading the Plugin
@@ -410,24 +410,24 @@ spec:
```bash
# Edit ConfigMap with new version
kubectl -n kube-system edit configmap headlamp-plugin-config
kubectl -n headlamp edit configmap headlamp-plugin-config
# Update version and URL:
# version: 0.3.6
# url: https://github.com/.../v0.3.6/polaris-0.3.10.tar.gz
# Restart deployment to trigger init container
kubectl -n kube-system rollout restart deployment/headlamp
kubectl -n headlamp rollout restart deployment/headlamp
# Wait for rollout to complete
kubectl -n kube-system rollout status deployment/headlamp
kubectl -n headlamp rollout status deployment/headlamp
```
### Verify Upgrade
```bash
# Check init container logs
kubectl -n kube-system logs deployment/headlamp -c install-plugins
kubectl -n headlamp logs deployment/headlamp -c install-plugins
# Verify new version in UI
# Navigate to Settings → Plugins in Headlamp
@@ -439,7 +439,7 @@ kubectl -n kube-system logs deployment/headlamp -c install-plugins
```bash
# Check init container logs
kubectl -n kube-system logs deployment/headlamp -c install-plugins
kubectl -n headlamp logs deployment/headlamp -c install-plugins
# Common issues:
# 1. Network connectivity to GitHub
@@ -451,14 +451,14 @@ kubectl -n kube-system logs deployment/headlamp -c install-plugins
```bash
# Verify HEADLAMP_CONFIG_WATCH_PLUGINS is false
kubectl -n kube-system get deployment headlamp -o yaml | grep WATCH_PLUGINS
kubectl -n headlamp get deployment headlamp -o yaml | grep WATCH_PLUGINS
# Expected output:
# - name: HEADLAMP_CONFIG_WATCH_PLUGINS
# value: "false"
# If not set or "true", update deployment
kubectl -n kube-system edit deployment headlamp
kubectl -n headlamp edit deployment headlamp
```
### RBAC Permissions Denied
@@ -466,7 +466,7 @@ kubectl -n kube-system edit deployment headlamp
```bash
# Test RBAC
kubectl auth can-i get services/proxy \
--as=system:serviceaccount:kube-system:headlamp \
--as=system:serviceaccount:headlamp:headlamp \
-n polaris \
--resource-name=polaris-dashboard
docs/deployment/production.md
+15 -15
View File
@@ -37,8 +37,8 @@ kubectl -n polaris get svc polaris-dashboard
kubectl get --raw /api/v1/namespaces/polaris/services/polaris-dashboard:80/proxy/results.json | jq .PolarisOutputVersion
# Verify Headlamp
kubectl -n kube-system get deployment headlamp
kubectl -n kube-system get svc headlamp
kubectl -n headlamp get deployment headlamp
kubectl -n headlamp get svc headlamp
```
## Production Checklist
@@ -60,17 +60,17 @@ kubectl get --raw /api/v1/namespaces/polaris/services/polaris-dashboard:80/proxy
# 2. Verify RBAC permissions
kubectl auth can-i get services/proxy \
--as=system:serviceaccount:kube-system:headlamp \
--as=system:serviceaccount:headlamp:headlamp \
-n polaris \
--resource-name=polaris-dashboard
# Expected: yes
# 3. Check Headlamp logs for plugin loading
kubectl -n kube-system logs deployment/headlamp | grep -i polaris
kubectl -n headlamp logs deployment/headlamp | grep -i polaris
# Expected: No errors related to plugin loading
# 4. Verify plugin files exist
kubectl -n kube-system exec deployment/headlamp -c headlamp -- ls -la /headlamp/plugins/headlamp-polaris-plugin/
kubectl -n headlamp exec deployment/headlamp -c headlamp -- ls -la /headlamp/plugins/headlamp-polaris-plugin/
# Expected: dist/, package.json present
```
@@ -241,7 +241,7 @@ apiVersion: policy/v1
kind: PodDisruptionBudget
metadata:
name: headlamp-pdb
namespace: kube-system
namespace: headlamp
spec:
minAvailable: 1
selector:
@@ -295,7 +295,7 @@ apiVersion: monitoring.coreos.com/v1
kind: ServiceMonitor
metadata:
name: headlamp
namespace: kube-system
namespace: headlamp
spec:
selector:
matchLabels:
@@ -312,10 +312,10 @@ spec:
```bash
# View logs
kubectl -n kube-system logs deployment/headlamp -f
kubectl -n headlamp logs deployment/headlamp -f
# Filter for plugin-related logs
kubectl -n kube-system logs deployment/headlamp | grep -i polaris
kubectl -n headlamp logs deployment/headlamp | grep -i polaris
```
**Polaris Dashboard Logs:**
@@ -341,14 +341,14 @@ apiVersion: monitoring.coreos.com/v1
kind: PrometheusRule
metadata:
name: headlamp-alerts
namespace: kube-system
namespace: headlamp
spec:
groups:
- name: headlamp
interval: 30s
rules:
- alert: HeadlampPodNotReady
expr: kube_pod_status_ready{namespace="kube-system", pod=~"headlamp-.*"} == 0
expr: kube_pod_status_ready{namespace="headlamp", pod=~"headlamp-.*"} == 0
for: 5m
labels:
severity: warning
@@ -422,9 +422,9 @@ If Headlamp or plugin becomes unavailable:
2. **Redeploy Headlamp:**
```bash
helm upgrade --install headlamp headlamp/headlamp \
--namespace kube-system \
--values headlamp-values.yaml
helm upgrade --install headlamp headlamp/headlamp \
--namespace headlamp \
--values headlamp-values.yaml
```
3. **Reapply RBAC:**
@@ -436,7 +436,7 @@ If Headlamp or plugin becomes unavailable:
4. **Verify plugin files:**
```bash
kubectl -n kube-system exec deployment/headlamp -- \
kubectl -n headlamp exec deployment/headlamp -- \
ls /headlamp/plugins/headlamp-polaris-plugin/
```