stack.basicstack.de/apps/headlamp

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