From 38ddae08a9a025db043dda118e860f6a9335956f Mon Sep 17 00:00:00 2001 From: CTO Agent Date: Sat, 18 Jul 2026 08:00:11 +0000 Subject: [PATCH] docs(headlamp): document authentication methods and troubleshooting 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 --- apps/headlamp/README.md | 45 ++++++++++++++++++++++++++++++++++++++++- 1 file changed, 44 insertions(+), 1 deletion(-) diff --git a/apps/headlamp/README.md b/apps/headlamp/README.md index f5b0a27..aa333d0 100644 --- a/apps/headlamp/README.md +++ b/apps/headlamp/README.md @@ -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