38ddae08a9
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>
85 lines
2.9 KiB
Markdown
85 lines
2.9 KiB
Markdown
# Headlamp - Kubernetes Dashboard
|
|
|
|
Headlamp is a modern, web-based Kubernetes dashboard that provides a user-friendly interface for managing and monitoring Kubernetes clusters.
|
|
|
|
## Deployment
|
|
|
|
This deployment includes:
|
|
|
|
- **Namespace**: `headlamp`
|
|
- **Service Account**: `headlamp-admin` with `cluster-admin` ClusterRoleBinding for full cluster access
|
|
- **OIDC Authentication**: Integrated with Pocket ID (https://auth.basicstack.de)
|
|
- **Ingress**: Accessible at https://headlamp.basicstack.de
|
|
|
|
## OIDC Configuration
|
|
|
|
The deployment is configured to authenticate users via Pocket ID using OpenID Connect (OIDC):
|
|
|
|
- **Issuer URL**: https://auth.basicstack.de
|
|
- **Client ID**: Stored in sealed secret `headlamp-oidc`
|
|
- **Client Secret**: Stored in sealed secret `headlamp-oidc`
|
|
- **Scopes**: openid, profile, email
|
|
|
|
### Authorized Users
|
|
|
|
The following users have access to Headlamp through Pocket ID:
|
|
- andreas.leinen@basicstack.de (admin)
|
|
- admin@basicstack.de (admin)
|
|
|
|
Users authenticate through the Pocket ID SSO and receive cluster-admin permissions via the service account.
|
|
|
|
## Resources
|
|
|
|
- **Official Documentation**: https://headlamp.dev/docs/
|
|
- **OIDC Setup Guide**: https://headlamp.dev/docs/latest/installation/in-cluster/oidc
|
|
- **Source Repository**: https://github.com/headlamp-k8s/headlamp
|
|
|
|
## Access
|
|
|
|
After deployment via ArgoCD, access the dashboard at:
|
|
https://headlamp.basicstack.de
|
|
|
|
### 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
|