basicstack/stack.basicstack.de
2
0
Fork 0
Code Issues Pull requests 1 Projects Releases Packages Wiki Activity Actions
stack.basicstack.de/apps/headlamp
History
CTO Agent c6993d337c Fix Headlamp OIDC callback URL generation 
Set HEADLAMP_CONFIG_BASE_URL to https://headlamp.basicstack.de to ensure
the OIDC callback URL is generated correctly with HTTPS scheme. When
running behind Traefik without explicit base URL, Headlamp may generate
http:// callback URLs instead of https://, causing OIDC flow failures.

Also added traefik.ingress.kubernetes.io/preserve-host annotation to
ensure proper header forwarding.

Fixes: DEV-324

Co-Authored-By: Paperclip <noreply@paperclip.ing>
2026-07-18 08:39:12 +00:00
..
deployment.yaml Fix Headlamp OIDC callback URL generation 2026-07-18 08:39:12 +00:00
headlamp-oidc-sealed.yaml Add Headlamp Kubernetes dashboard deployment 2026-07-18 07:37:58 +00:00
ingress.yaml Fix Headlamp OIDC callback URL generation 2026-07-18 08:39:12 +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:

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:

Users authenticate through the Pocket ID SSO and receive cluster-admin permissions via the service account.

Resources

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