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

docs: replace hardcoded namespace with <your-namespace> placeholder

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

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>

* fix: correct RBAC manifest per QA review (PRI-555)

- Remove rbac.authorization.k8s.io privilege escalation block
- Fix orphaned comment from round 1
- Add EOF newline
- Keep serviceaccounts/token for E2E auth (confirmed needed)
- Namespace already correct (privilegedescalation-dev)

Co-Authored-By: Paperclip <noreply@paperclip.ing>

* docs: replace hardcoded namespace with <your-namespace> placeholder

Users choose their own namespace for Headlamp. Replace all hardcoded
namespace references (headlamp, kube-system) in user-facing docs with
<your-namespace> so users substitute their own value.

Conventions:
- Helm install: --namespace <your-namespace> --create-namespace
- kubectl commands: -n <your-namespace>
- YAML metadata: namespace: <your-namespace>
- Prose: "the namespace where Headlamp is installed"

Out-of-scope references left untouched:
- kube-system in NetworkPolicy selectors (API server namespace)
- polaris namespace references (upstream workload namespace)
- Source code and test files

Refs: PRI-433

Co-Authored-By: Paperclip <noreply@paperclip.ing>

* docs: fix remaining hardcoded headlamp namespace to <your-namespace> placeholder

Prior commit was inconsistent — some files used <your-namespace> while
DEPLOYMENT.md, TROUBLESHOOTING.md and several troubleshooting/user-guide
docs still hardcoded headlamp as the namespace.

Co-Authored-By: Paperclip <noreply@paperclip.ing>

---------

Co-authored-by: Chris Farhood <chris@farhood.org>
Co-authored-by: Paperclip <noreply@paperclip.ing>
This commit was merged in pull request #155.
This commit is contained in:
privilegedescalation-ceo[bot]
2026-05-10 21:34:49 +00:00
committed by GitHub
parent 7a0c068a93
commit e2ae92648c
17 changed files with 138 additions and 140 deletions
Download Patch File Download Diff File Expand all files Collapse all files
README.md
+2 -2
View File
@@ -97,7 +97,7 @@ metadata:
subjects:
- kind: ServiceAccount
name: headlamp # adjust to match your Headlamp service account
namespace: kube-system # adjust to match the namespace Headlamp runs in
namespace: <your-namespace>
roleRef:
kind: Role
name: polaris-proxy-reader
@@ -197,7 +197,7 @@ npm test
npm run test:watch
# E2E tests (Playwright)
export HEADLAMP_TOKEN=$(kubectl create token headlamp -n kube-system --duration=24h)
export HEADLAMP_TOKEN=$(kubectl create token headlamp -n <your-namespace> --duration=24h)
npm run e2e
npm run e2e:headed # see browser
```
SECURITY.md
+3 -3
View File
@@ -71,7 +71,7 @@ metadata:
subjects:
- kind: ServiceAccount
name: headlamp
namespace: kube-system
namespace: <your-namespace>
roleRef:
kind: Role
name: polaris-proxy-reader
@@ -149,7 +149,7 @@ spec:
### Service Account (Default)
Headlamp runs with a dedicated service account (`headlamp` in `kube-system`). All users share the same permissions defined by this service account's RBAC bindings.
Headlamp runs with a dedicated service account (`headlamp` in the namespace where Headlamp is installed). All users share the same permissions defined by this service account's RBAC bindings.
**Security Considerations:**
- All users have identical access to the plugin
@@ -317,7 +317,7 @@ All service proxy requests are logged in Kubernetes API audit logs (if enabled):
"verb": "get",
"requestURI": "/api/v1/namespaces/polaris/services/polaris-dashboard:80/proxy/results.json",
"user": {
"username": "system:serviceaccount:kube-system:headlamp",
"username": "system:serviceaccount:<your-namespace>:headlamp",
"groups": ["system:serviceaccounts", "system:authenticated"]
}
}
docs/DEPLOYMENT.md
+2 -2
View File
@@ -33,7 +33,7 @@ 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 is deployed
kubectl -n kube-system get pods -l app.kubernetes.io/name=headlamp
kubectl -n <your-namespace> get pods -l app.kubernetes.io/name=headlamp
```
## Installation Methods
@@ -59,7 +59,7 @@ kubectl -n kube-system get pods -l app.kubernetes.io/name=headlamp
```bash
helm upgrade --install headlamp headlamp/headlamp \
--namespace kube-system \
--namespace <your-namespace> \
--values headlamp-values.yaml
```
docs/TESTING.md
+2 -3
View File
@@ -268,10 +268,9 @@ npm run e2e
```bash
# Create token
export HEADLAMP_TOKEN=$(kubectl create token headlamp -n kube-system --duration=24h)
export HEADLAMP_TOKEN=$(kubectl create token headlamp -n <your-namespace> --duration=24h)
# Port-forward for local testing
kubectl port-forward -n kube-system svc/headlamp 4466:80
kubectl port-forward -n <your-namespace> svc/headlamp 4466:80
# Run tests
HEADLAMP_URL=http://localhost:4466 npm run e2e
docs/TROUBLESHOOTING.md
+16 -16
View File
@@ -33,7 +33,7 @@ This guide covers common issues encountered when using the Headlamp Polaris Plug
```bash
# View Headlamp pod logs (plugin sidecar)
kubectl logs -n kube-system deployment/headlamp -c headlamp-plugin
kubectl logs -n <your-namespace> deployment/headlamp -c headlamp-plugin
# Expected output:
# Installing plugin from https://github.com/.../headlamp-polaris-plugin-X.Y.Z.tar.gz
@@ -43,7 +43,7 @@ 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/
kubectl exec -n <your-namespace> deployment/headlamp -c headlamp -- ls -la /headlamp/plugins/
# Should show: headlamp-polaris-plugin/
```
@@ -118,7 +118,7 @@ Expected subjects:
subjects:
- kind: ServiceAccount
name: headlamp
namespace: kube-system
namespace: <your-namespace>
```
For OIDC mode:
@@ -154,7 +154,7 @@ metadata:
subjects:
- kind: ServiceAccount
name: headlamp
namespace: kube-system
namespace: <your-namespace>
roleRef:
kind: Role
name: polaris-proxy-reader
@@ -169,7 +169,7 @@ Service account mode:
```bash
# Impersonate Headlamp service account
kubectl auth can-i get services/proxy \
--as=system:serviceaccount:kube-system:headlamp \
--as=system:serviceaccount:<your-namespace>:headlamp \
--resource-name=polaris-dashboard \
-n polaris
# Expected: yes
@@ -189,7 +189,7 @@ kubectl auth can-i get services/proxy \
After applying RBAC changes:
```bash
kubectl rollout restart deployment headlamp -n kube-system
kubectl rollout restart deployment headlamp -n <your-namespace>
```
---
@@ -490,7 +490,7 @@ Run this script to test all RBAC components:
#!/bin/bash
NS="polaris"
SA="headlamp"
SA_NS="kube-system"
SA_NS="<your-namespace>"
echo "=== Testing RBAC for Polaris Plugin ==="
@@ -529,8 +529,8 @@ echo "=== Test complete ==="
Test connectivity from Headlamp to Polaris:
```bash
# Create debug pod in kube-system namespace
kubectl run netdebug -n kube-system --rm -it --image=nicolaka/netshoot -- bash
# Create debug pod in headlamp namespace
kubectl run netdebug -n <your-namespace> --rm -it --image=nicolaka/netshoot -- bash
# Inside pod, test DNS and HTTP
nslookup polaris-dashboard.polaris.svc.cluster.local
@@ -545,11 +545,11 @@ If you have audit logging enabled, check for denied requests:
```bash
# View recent audit logs (location varies by cluster)
kubectl logs -n kube-system kube-apiserver-* | grep polaris-dashboard
kubectl logs -n <your-namespace> kube-apiserver-* | grep polaris-dashboard
# Look for lines with:
# "reason": "Forbidden"
# "user": "system:serviceaccount:kube-system:headlamp"
# "user": "system:serviceaccount:<your-namespace>:headlamp"
```
---
@@ -567,7 +567,7 @@ kubectl logs -n kube-system kube-apiserver-* | grep polaris-dashboard
**Check sidecar logs**:
```bash
kubectl logs -n kube-system deployment/headlamp -c headlamp-plugin
kubectl logs -n <your-namespace> deployment/headlamp -c headlamp-plugin
```
**Common errors**:
@@ -591,7 +591,7 @@ 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
kubectl get configmap headlamp-plugin-config -n <your-namespace> -o yaml
```
Expected format:
@@ -677,13 +677,13 @@ If none of these solutions work, gather debugging information and open an issue:
1. **Version Information**:
```bash
kubectl get pods -n kube-system -l app.kubernetes.io/name=headlamp -o yaml | grep image:
kubectl get pods -n <your-namespace> -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`
- Or: `kubectl exec -n <your-namespace> deployment/headlamp -c headlamp -- cat /headlamp/plugins/headlamp-polaris-plugin/package.json`
3. **Browser Console Output**:
@@ -698,7 +698,7 @@ If none of these solutions work, gather debugging information and open an issue:
5. **Pod Logs**:
```bash
kubectl logs -n kube-system deployment/headlamp -c headlamp --tail=100
kubectl logs -n <your-namespace> deployment/headlamp -c headlamp --tail=100
kubectl logs -n polaris deployment/polaris-dashboard --tail=100
```
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 <your-namespace> \
--values headlamp-values.yaml
# Wait for deployment
kubectl -n kube-system wait --for=condition=available deployment/headlamp --timeout=300s
kubectl -n <your-namespace> 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 <your-namespace> \
--values headlamp-values.yaml \
--wait \
--timeout 5m
@@ -177,7 +177,7 @@ apiVersion: v1
kind: ConfigMap
metadata:
name: headlamp-plugin-config
namespace: kube-system
namespace: <your-namespace>
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 <your-namespace> \
--values headlamp-values.yaml
```
@@ -221,7 +221,7 @@ apiVersion: helm.toolkit.fluxcd.io/v2
kind: HelmRelease
metadata:
name: headlamp
namespace: kube-system
namespace: <your-namespace>
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 <your-namespace> --watch
```
## RBAC Configuration
@@ -329,7 +329,7 @@ metadata:
subjects:
- kind: ServiceAccount
name: headlamp
namespace: kube-system
namespace: <your-namespace>
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 <your-namespace> \
--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 <your-namespace> 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 <your-namespace> rollout restart deployment/headlamp
kubectl -n <your-namespace> 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 <your-namespace>
# Verify plugin files exist
kubectl -n kube-system exec deployment/headlamp -c headlamp -- \
kubectl -n <your-namespace> 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 <your-namespace> logs deployment/headlamp -c install-polaris-plugin
```
### Helm Release Stuck
```bash
# Check Helm release status
helm list -n kube-system
helm list -n <your-namespace>
# If stuck, force upgrade
helm upgrade headlamp headlamp/headlamp \
--namespace kube-system \
--namespace <your-namespace> \
--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 <your-namespace>
# Check events
kubectl -n kube-system describe helmrelease headlamp
kubectl -n <your-namespace> describe helmrelease headlamp
# Force reconciliation
flux reconcile helmrelease headlamp -n kube-system
flux reconcile helmrelease headlamp -n <your-namespace>
```
## Next Steps
docs/deployment/kubernetes.md
+21 -21
View File
@@ -47,7 +47,7 @@ metadata:
subjects:
- kind: ServiceAccount
name: headlamp
namespace: kube-system
namespace: <your-namespace>
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:<your-namespace>:headlamp \
-n polaris \
--resource-name=polaris-dashboard
@@ -90,7 +90,7 @@ apiVersion: v1
kind: ConfigMap
metadata:
name: headlamp-plugin-config
namespace: kube-system
namespace: <your-namespace>
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: <your-namespace>
labels:
app.kubernetes.io/name: headlamp
spec:
@@ -194,7 +194,7 @@ apiVersion: v1
kind: ServiceAccount
metadata:
name: headlamp
namespace: kube-system
namespace: <your-namespace>
labels:
app.kubernetes.io/name: headlamp
@@ -204,7 +204,7 @@ apiVersion: v1
kind: Service
metadata:
name: headlamp
namespace: kube-system
namespace: <your-namespace>
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 <your-namespace> 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 <your-namespace> 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 <your-namespace> 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 <your-namespace> 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 <your-namespace> 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: <your-namespace>
commonLabels:
app.kubernetes.io/name: headlamp
@@ -401,7 +401,7 @@ spec:
- apiVersion: apps/v1
kind: Deployment
name: headlamp
namespace: kube-system
namespace: <your-namespace>
```
## 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 <your-namespace> 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 <your-namespace> rollout restart deployment/headlamp
# Wait for rollout to complete
kubectl -n kube-system rollout status deployment/headlamp
kubectl -n <your-namespace> rollout status deployment/headlamp
```
### Verify Upgrade
```bash
# Check init container logs
kubectl -n kube-system logs deployment/headlamp -c install-plugins
kubectl -n <your-namespace> 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 <your-namespace> 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 <your-namespace> 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 <your-namespace> 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:<your-namespace>: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 <your-namespace> get deployment headlamp
kubectl -n <your-namespace> 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:<your-namespace>: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 <your-namespace> 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 <your-namespace> 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: <your-namespace>
spec:
minAvailable: 1
selector:
@@ -295,7 +295,7 @@ apiVersion: monitoring.coreos.com/v1
kind: ServiceMonitor
metadata:
name: headlamp
namespace: kube-system
namespace: <your-namespace>
spec:
selector:
matchLabels:
@@ -312,10 +312,10 @@ spec:
```bash
# View logs
kubectl -n kube-system logs deployment/headlamp -f
kubectl -n <your-namespace> logs deployment/headlamp -f
# Filter for plugin-related logs
kubectl -n kube-system logs deployment/headlamp | grep -i polaris
kubectl -n <your-namespace> 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: <your-namespace>
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="<your-namespace>", 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 <your-namespace> \
--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 <your-namespace> exec deployment/headlamp -- \
ls /headlamp/plugins/headlamp-polaris-plugin/
```
docs/development/testing.md
+2 -3
View File
@@ -268,10 +268,9 @@ npm run e2e
```bash
# Create token
export HEADLAMP_TOKEN=$(kubectl create token headlamp -n kube-system --duration=24h)
export HEADLAMP_TOKEN=$(kubectl create token headlamp -n <your-namespace> --duration=24h)
# Port-forward for local testing
kubectl port-forward -n kube-system svc/headlamp 4466:80
kubectl port-forward -n <your-namespace> svc/headlamp 4466:80
# Run tests
HEADLAMP_URL=http://localhost:4466 npm run e2e
docs/getting-started/installation.md
+13 -13
View File
@@ -72,7 +72,7 @@ Deploy or update Headlamp:
```bash
helm upgrade --install headlamp headlamp/headlamp \
--namespace kube-system \
--namespace <your-namespace> \
--values headlamp-values.yaml
```
@@ -122,7 +122,7 @@ apiVersion: v1
kind: ConfigMap
metadata:
name: headlamp-plugin-config
namespace: kube-system
namespace: <your-namespace>
data:
plugin.yml: |
- name: headlamp-polaris-plugin
@@ -138,14 +138,14 @@ kubectl apply -f headlamp-plugin-config.yaml
# Deploy/update Headlamp with sidecar
helm upgrade --install headlamp headlamp/headlamp \
--namespace kube-system \
--namespace <your-namespace> \
--values headlamp-values.yaml
# Wait for pod to be ready
kubectl -n kube-system wait --for=condition=ready pod -l app.kubernetes.io/name=headlamp --timeout=300s
kubectl -n <your-namespace> wait --for=condition=ready pod -l app.kubernetes.io/name=headlamp --timeout=300s
# Verify plugin files
kubectl -n kube-system exec -it deployment/headlamp -c headlamp -- ls -la /headlamp/plugins/headlamp-polaris-plugin/
kubectl -n <your-namespace> exec -it deployment/headlamp -c headlamp -- ls -la /headlamp/plugins/headlamp-polaris-plugin/
# Expected output:
# drwxr-xr-x dist/
@@ -270,7 +270,7 @@ metadata:
subjects:
- kind: ServiceAccount
name: headlamp
namespace: kube-system
namespace: <your-namespace>
roleRef:
kind: Role
name: polaris-proxy-reader
@@ -284,10 +284,10 @@ See [RBAC Permissions](../user-guide/rbac-permissions.md) for detailed RBAC conf
```bash
# If you updated Helm values or ConfigMaps
kubectl -n kube-system rollout restart deployment/headlamp
kubectl -n <your-namespace> rollout restart deployment/headlamp
# Wait for pod to be ready
kubectl -n kube-system wait --for=condition=ready pod -l app.kubernetes.io/name=headlamp --timeout=300s
kubectl -n <your-namespace> wait --for=condition=ready pod -l app.kubernetes.io/name=headlamp --timeout=300s
```
### 3. Clear Browser Cache
@@ -312,14 +312,14 @@ kubectl -n kube-system wait --for=condition=ready pod -l app.kubernetes.io/name=
```bash
# Verify plugin files exist
kubectl -n kube-system exec -it deployment/headlamp -c headlamp -- ls -la /headlamp/plugins/headlamp-polaris-plugin/
kubectl -n <your-namespace> exec -it deployment/headlamp -c headlamp -- ls -la /headlamp/plugins/headlamp-polaris-plugin/
# Expected output:
# drwxr-xr-x dist/
# -rw-r--r-- package.json
# Check Headlamp logs for errors
kubectl -n kube-system logs deployment/headlamp | grep -i polaris
kubectl -n <your-namespace> logs deployment/headlamp | grep -i polaris
# Expected: No errors related to plugin loading
@@ -345,13 +345,13 @@ kubectl get --raw /api/v1/namespaces/polaris/services/polaris-dashboard:80/proxy
```bash
# 1. Verify plugin files exist
kubectl -n kube-system exec deployment/headlamp -c headlamp -- \
kubectl -n <your-namespace> exec deployment/headlamp -c headlamp -- \
ls -la /headlamp/plugins/headlamp-polaris-plugin/
# Expected: dist/, package.json present
# 2. Check Headlamp logs for plugin errors
kubectl -n kube-system logs deployment/headlamp | grep -i polaris
kubectl -n <your-namespace> logs deployment/headlamp | grep -i polaris
# 3. Hard refresh browser (Cmd+Shift+R or Ctrl+Shift+R)
@@ -404,7 +404,7 @@ helm install polaris fairwinds-stable/polaris \
```bash
# Wait 30 minutes for ArtifactHub sync
# Or manually force Headlamp restart:
kubectl -n kube-system rollout restart deployment/headlamp
kubectl -n <your-namespace> rollout restart deployment/headlamp
```
## Next Steps
docs/getting-started/prerequisites.md
+5 -5
View File
@@ -67,14 +67,14 @@ kubectl -n polaris wait --for=condition=ready pod -l app.kubernetes.io/name=pola
```bash
# Check Headlamp is deployed
kubectl -n kube-system get pods -l app.kubernetes.io/name=headlamp
kubectl -n <your-namespace> get pods -l app.kubernetes.io/name=headlamp
# Expected output:
# NAME READY STATUS RESTARTS AGE
# headlamp-xxxxxxxxxx-xxxxx 1/1 Running 0 1h
# Check Headlamp version (must be v0.26+)
kubectl -n kube-system get deployment headlamp -o jsonpath='{.spec.template.spec.containers[0].image}'
kubectl -n <your-namespace> get deployment headlamp -o jsonpath='{.spec.template.spec.containers[0].image}'
# Expected output:
# ghcr.io/headlamp-k8s/headlamp:v0.39.0 (or similar)
@@ -89,12 +89,12 @@ helm repo update
# Install Headlamp
helm install headlamp headlamp/headlamp \
--namespace kube-system \
--namespace <your-namespace> \
--set config.pluginsDir="/headlamp/plugins" \
--set pluginsManager.enabled=true
# Wait for pod to be ready
kubectl -n kube-system wait --for=condition=ready pod -l app.kubernetes.io/name=headlamp --timeout=300s
kubectl -n <your-namespace> wait --for=condition=ready pod -l app.kubernetes.io/name=headlamp --timeout=300s
```
## RBAC Requirements
@@ -112,7 +112,7 @@ The plugin requires permissions to access the Polaris dashboard via Kubernetes s
```bash
# Test if Headlamp service account has permission
kubectl auth can-i get services/proxy \
--as=system:serviceaccount:kube-system:headlamp \
--as=system:serviceaccount:<your-namespace>:headlamp \
-n polaris \
--resource-name=polaris-dashboard
docs/getting-started/quick-start.md
+5 -5
View File
@@ -38,7 +38,7 @@ EOF
# Update Headlamp
helm upgrade --install headlamp headlamp/headlamp \
--namespace kube-system \
--namespace <your-namespace> \
--values headlamp-values.yaml
```
@@ -70,7 +70,7 @@ metadata:
subjects:
- kind: ServiceAccount
name: headlamp
namespace: kube-system
namespace: <your-namespace>
roleRef:
kind: Role
name: polaris-proxy-reader
@@ -111,7 +111,7 @@ EOF
```bash
# Verify plugin files exist
kubectl -n kube-system exec -it deployment/headlamp -c headlamp -- \
kubectl -n <your-namespace> exec -it deployment/headlamp -c headlamp -- \
ls /headlamp/plugins/headlamp-polaris-plugin/dist/
# Expected output:
@@ -119,7 +119,7 @@ kubectl -n kube-system exec -it deployment/headlamp -c headlamp -- \
# Verify RBAC is correct
kubectl auth can-i get services/proxy \
--as=system:serviceaccount:kube-system:headlamp \
--as=system:serviceaccount:<your-namespace>:headlamp \
-n polaris \
--resource-name=polaris-dashboard
@@ -185,7 +185,7 @@ Cluster score badge in top navigation:
```bash
# Verify plugin files exist
kubectl -n kube-system exec -it deployment/headlamp -c headlamp -- \
kubectl -n <your-namespace> exec -it deployment/headlamp -c headlamp -- \
ls /headlamp/plugins/headlamp-polaris-plugin/
# If missing, reinstall via Headlamp UI or sidecar method
docs/troubleshooting/README.md
+5 -5
View File
@@ -38,17 +38,17 @@ kubectl get --raw /api/v1/namespaces/polaris/services/polaris-dashboard:80/proxy
# 3. Verify RBAC permissions
kubectl auth can-i get services/proxy \
--as=system:serviceaccount:kube-system:headlamp \
--as=system:serviceaccount:<your-namespace>:headlamp \
-n polaris \
--resource-name=polaris-dashboard
# Expected output: yes
# 4. Check Headlamp pod is running
kubectl -n kube-system get pods -l app.kubernetes.io/name=headlamp
kubectl -n <your-namespace> get pods -l app.kubernetes.io/name=headlamp
# 5. Check Headlamp logs for plugin errors
kubectl -n kube-system logs deployment/headlamp | grep -i polaris
kubectl -n <your-namespace> logs deployment/headlamp | grep -i polaris
# Expected: No errors
```
@@ -57,7 +57,7 @@ kubectl -n kube-system logs deployment/headlamp | grep -i polaris
```bash
# Verify plugin files exist
kubectl -n kube-system exec deployment/headlamp -c headlamp -- \
kubectl -n <your-namespace> exec deployment/headlamp -c headlamp -- \
ls -la /headlamp/plugins/headlamp-polaris-plugin/
# Expected output:
@@ -76,7 +76,7 @@ kubectl -n polaris get rolebinding headlamp-polaris-proxy
# Test permission (service account mode)
kubectl auth can-i get services/proxy \
--as=system:serviceaccount:kube-system:headlamp \
--as=system:serviceaccount:<your-namespace>:headlamp \
-n polaris \
--resource-name=polaris-dashboard
docs/troubleshooting/common-issues.md
+16 -16
View File
@@ -33,7 +33,7 @@ This guide covers common issues encountered when using the Headlamp Polaris Plug
```bash
# View Headlamp pod logs (plugin sidecar)
kubectl logs -n kube-system deployment/headlamp -c headlamp-plugin
kubectl logs -n <your-namespace> deployment/headlamp -c headlamp-plugin
# Expected output:
# Installing plugin from https://github.com/.../headlamp-polaris-plugin-X.Y.Z.tar.gz
@@ -43,7 +43,7 @@ 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/
kubectl exec -n <your-namespace> deployment/headlamp -c headlamp -- ls -la /headlamp/plugins/
# Should show: headlamp-polaris-plugin/
```
@@ -118,7 +118,7 @@ Expected subjects:
subjects:
- kind: ServiceAccount
name: headlamp
namespace: kube-system
namespace: <your-namespace>
```
For OIDC mode:
@@ -154,7 +154,7 @@ metadata:
subjects:
- kind: ServiceAccount
name: headlamp
namespace: kube-system
namespace: <your-namespace>
roleRef:
kind: Role
name: polaris-proxy-reader
@@ -169,7 +169,7 @@ Service account mode:
```bash
# Impersonate Headlamp service account
kubectl auth can-i get services/proxy \
--as=system:serviceaccount:kube-system:headlamp \
--as=system:serviceaccount:<your-namespace>:headlamp \
--resource-name=polaris-dashboard \
-n polaris
# Expected: yes
@@ -189,7 +189,7 @@ kubectl auth can-i get services/proxy \
After applying RBAC changes:
```bash
kubectl rollout restart deployment headlamp -n kube-system
kubectl rollout restart deployment headlamp -n <your-namespace>
```
---
@@ -490,7 +490,7 @@ Run this script to test all RBAC components:
#!/bin/bash
NS="polaris"
SA="headlamp"
SA_NS="kube-system"
SA_NS="<your-namespace>"
echo "=== Testing RBAC for Polaris Plugin ==="
@@ -529,8 +529,8 @@ echo "=== Test complete ==="
Test connectivity from Headlamp to Polaris:
```bash
# Create debug pod in kube-system namespace
kubectl run netdebug -n kube-system --rm -it --image=nicolaka/netshoot -- bash
# Create debug pod in the namespace where Headlamp is installed
kubectl run netdebug -n <your-namespace> --rm -it --image=nicolaka/netshoot -- bash
# Inside pod, test DNS and HTTP
nslookup polaris-dashboard.polaris.svc.cluster.local
@@ -545,11 +545,11 @@ If you have audit logging enabled, check for denied requests:
```bash
# View recent audit logs (location varies by cluster)
kubectl logs -n kube-system kube-apiserver-* | grep polaris-dashboard
kubectl logs -n <your-namespace> kube-apiserver-* | grep polaris-dashboard
# Look for lines with:
# "reason": "Forbidden"
# "user": "system:serviceaccount:kube-system:headlamp"
# "user": "system:serviceaccount:<your-namespace>:headlamp"
```
---
@@ -567,7 +567,7 @@ kubectl logs -n kube-system kube-apiserver-* | grep polaris-dashboard
**Check sidecar logs**:
```bash
kubectl logs -n kube-system deployment/headlamp -c headlamp-plugin
kubectl logs -n <your-namespace> deployment/headlamp -c headlamp-plugin
```
**Common errors**:
@@ -591,7 +591,7 @@ 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
kubectl get configmap headlamp-plugin-config -n <your-namespace> -o yaml
```
Expected format:
@@ -677,13 +677,13 @@ If none of these solutions work, gather debugging information and open an issue:
1. **Version Information**:
```bash
kubectl get pods -n kube-system -l app.kubernetes.io/name=headlamp -o yaml | grep image:
kubectl get pods -n <your-namespace> -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`
- Or: `kubectl exec -n <your-namespace> deployment/headlamp -c headlamp -- cat /headlamp/plugins/headlamp-polaris-plugin/package.json`
3. **Browser Console Output**:
@@ -698,7 +698,7 @@ If none of these solutions work, gather debugging information and open an issue:
5. **Pod Logs**:
```bash
kubectl logs -n kube-system deployment/headlamp -c headlamp --tail=100
kubectl logs -n <your-namespace> deployment/headlamp -c headlamp --tail=100
kubectl logs -n polaris deployment/polaris-dashboard --tail=100
```
docs/troubleshooting/rbac-issues.md
+2 -2
View File
@@ -43,7 +43,7 @@ metadata:
subjects:
- kind: ServiceAccount
name: headlamp
namespace: kube-system
namespace: <your-namespace>
roleRef:
kind: Role
name: polaris-proxy-reader
@@ -83,7 +83,7 @@ roleRef:
```bash
# Test service account (in-cluster mode)
kubectl auth can-i get services/proxy \
--as=system:serviceaccount:kube-system:headlamp \
--as=system:serviceaccount:<your-namespace>:headlamp \
-n polaris \
--resource-name=polaris-dashboard
docs/user-guide/configuration.md
+1 -1
View File
@@ -317,7 +317,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:<your-namespace>:headlamp \
-n polaris \
--resource-name=polaris-dashboard
```
docs/user-guide/rbac-permissions.md
+8 -8
View File
@@ -65,7 +65,7 @@ metadata:
subjects:
- kind: ServiceAccount
name: headlamp # Adjust to your Headlamp SA name
namespace: kube-system # Adjust to Headlamp's namespace
namespace: <your-namespace>
roleRef:
kind: Role
name: polaris-proxy-reader
@@ -75,7 +75,7 @@ roleRef:
**Adjust for your environment:**
- `subjects[0].name` - Your Headlamp service account name (often `headlamp`)
- `subjects[0].namespace` - Namespace where Headlamp runs (often `kube-system`)
- `subjects[0].namespace` - Namespace where Headlamp is installed
### Step 3: Apply and Verify
@@ -91,7 +91,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:<your-namespace>:headlamp \
-n polaris \
--resource-name=polaris-dashboard
@@ -109,7 +109,7 @@ In token-auth mode, **each user's own identity** is used for Kubernetes API requ
With service account mode:
- Single RoleBinding grants access to all Headlamp users
- Kubernetes sees all requests as `system:serviceaccount:kube-system:headlamp`
- Kubernetes sees all requests as `system:serviceaccount:<your-namespace>:headlamp`
With token-auth mode:
@@ -267,7 +267,7 @@ metadata:
subjects:
- kind: ServiceAccount
name: headlamp
namespace: kube-system
namespace: <your-namespace>
roleRef:
kind: Role
name: polaris-proxy-reader
@@ -281,7 +281,7 @@ metadata:
subjects:
- kind: ServiceAccount
name: headlamp
namespace: kube-system
namespace: <your-namespace>
roleRef:
kind: Role
name: polaris-proxy-reader
@@ -411,7 +411,7 @@ Every plugin data fetch creates a Kubernetes API audit log entry.
"level": "Metadata",
"verb": "get",
"user": {
"username": "system:serviceaccount:kube-system:headlamp"
"username": "system:serviceaccount:<your-namespace>:headlamp"
},
"sourceIPs": ["10.96.0.1"],
"objectRef": {
@@ -494,7 +494,7 @@ If using a log aggregator (e.g., Elasticsearch), create filters to exclude or do
```bash
# Service account mode
kubectl auth can-i get services/proxy \
--as=system:serviceaccount:kube-system:headlamp \
--as=system:serviceaccount:<your-namespace>:headlamp \
-n polaris \
--resource-name=polaris-dashboard