basicstack/stack.basicstack.de
2
0
Fork 0
Code Issues Pull requests 1 Projects Releases Packages Wiki Activity Actions

docs(headlamp): document authentication methods and troubleshooting

Browse source 
Add clear documentation for both OIDC and token-based authentication.
Include troubleshooting section for common 403 errors caused by
using tokens from wrong namespace.

Fixes issue where token was generated from kube-system instead of
headlamp namespace, causing 403 errors on metrics API.

Co-Authored-By: Paperclip <noreply@paperclip.ing>
This commit is contained in:
CTO Agent 2026-07-18 08:00:11 +00:00
parent 0bc48c2f7c
commit 38ddae08a9
1 changed files with 44 additions and 1 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

45
apps/headlamp/README.md
View file

@ -39,4 +39,47 @@ Users authenticate through the Pocket ID SSO and receive cluster-admin permissio
After deployment via ArgoCD, access the dashboard at:
https://headlamp.basicstack.de
Users will be redirected to Pocket ID for authentication before accessing the cluster dashboard.
### Authentication Methods
#### 1. OIDC Authentication (Recommended)
Users will be redirected to Pocket ID for authentication. Once OIDC is fully configured in Pocket ID:
- Navigate to https://headlamp.basicstack.de
- Click "Sign in with OIDC"
- Authenticate via Pocket ID
- Headlamp uses the `headlamp-admin` ServiceAccount for all Kubernetes API calls
#### 2. Token-Based Authentication (Fallback)
For testing or when OIDC is not available, you can use token-based authentication:
```bash
# Generate a token from the headlamp-admin ServiceAccount
kubectl create token headlamp-admin -n headlamp
# Copy the token and paste it in the Headlamp login form
```
**Important**: The ServiceAccount exists in the `headlamp` namespace, not `kube-system`. Using the wrong namespace will result in 403 errors when accessing Kubernetes APIs.
The token has `cluster-admin` permissions and provides full access to all cluster resources including metrics APIs.
## Troubleshooting
### 403 Errors on Metrics API
If you see 403 errors like `GET https://headlamp.basicstack.de/clusters/main/apis/metrics.k8s.io/v1beta1/nodes`:
**Cause**: Using a token from the wrong namespace or a ServiceAccount without sufficient permissions.
**Solution**: Generate the token from the correct namespace:
```bash
kubectl create token headlamp-admin -n headlamp
```
### Asset Loading Errors
If you encounter errors loading JavaScript assets, check:
- Ingress configuration is correct
- TLS certificate is valid
- Browser console for specific error messages