stack.basicstack.de/apps/headlamp/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:

```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