basicstack/stack.basicstack.de

History

CTO Agent 519e7e95e7 Revert BASE_URL to empty - Headlamp expects path not full URL Headlamp's BASE_URL config expects a path prefix (e.g., "/headlamp") or empty string, not a full URL. Since Headlamp is deployed at the domain root, BASE_URL should be empty. The OIDC redirect URIs in Pocket ID are correctly configured and the user has been added to the headlamp group, which should resolve the authentication issue. Related to DEV-324 Co-Authored-By: Paperclip <noreply@paperclip.ing>		2026-07-18 08:33:33 +00:00
..
deployment.yaml	Revert BASE_URL to empty - Headlamp expects path not full URL	2026-07-18 08:33:33 +00:00
headlamp-oidc-sealed.yaml	Add Headlamp Kubernetes dashboard deployment	2026-07-18 07:37:58 +00:00
ingress.yaml	Add Headlamp Kubernetes dashboard deployment	2026-07-18 07:37:58 +00:00
README.md	docs(headlamp): document authentication methods and troubleshooting	2026-07-18 08:00:11 +00:00
service-account.yaml	Add Headlamp Kubernetes dashboard deployment	2026-07-18 07:37:58 +00:00
service.yaml	Add Headlamp Kubernetes dashboard deployment	2026-07-18 07:37:58 +00:00

README.md

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:

# 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:

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