Headlamp Deployment & Usage Guide

1. Prerequisites

Before installing Headlamp, ensure you have the following:

Required:

• Node.js 18.x LTS or higher
• npm 9.x or higher (or yarn 1.22+)
• Git
• kubectl configured with cluster access
• Kubernetes cluster (1.24+) for in-cluster deployment

For Desktop Development:

• OS-specific tools:
  • Linux: libgtk-3-0, libnotify4, libnss3, libxss1, libxtst6, xdg-utils
  • macOS: Xcode Command Line Tools
  • Windows: Visual Studio Build Tools or windows-build-tools

For In-Cluster Deployment:

• Helm 3.x (recommended) or kubectl access
• Container runtime (Docker/Podman) for building images
• Service account with appropriate RBAC permissions (see Configuration)

2. Installation

Clone the Repository

git clone https://github.com/kubernetes-sigs/headlamp.git
cd headlamp

Install Dependencies

Headlamp uses a monorepo structure with separate packages for frontend, desktop app, and tools.

# Install frontend dependencies
cd frontend
npm install

# Install desktop app dependencies (optional, for desktop builds)
cd ../app
npm install

# Install tool dependencies (optional, for development tools)
cd ../tools/releaser
npm install

3. Configuration

Kubeconfig Setup

Headlamp uses your local kubeconfig for cluster access:

# Ensure kubeconfig is in the default location
export KUBECONFIG=$HOME/.kube/config

# Or specify a custom path
export KUBECONFIG=/path/to/your/kubeconfig

RBAC & Service Accounts

For in-cluster deployment or limited access testing, create a service account:

# Create a service account with cluster-admin (adjust permissions as needed)
kubectl create serviceaccount headlamp-admin -n kube-system
kubectl create clusterrolebinding headlamp-admin-binding \
  --clusterrole=cluster-admin \
  --serviceaccount=kube-system:headlamp-admin

# Get the token for login
kubectl create token headlamp-admin -n kube-system

Environment Variables

Plugin Configuration

Plugins are stored in platform-specific directories:

• Linux: ~/.config/Headlamp/plugins/
• macOS: ~/Library/Application Support/Headlamp/plugins/
• Windows: %APPDATA%/Headlamp/plugins/

4. Build & Run

Development Mode (Frontend Only)

cd frontend

# Start development server with hot reload
npm run dev

# Or start with specific backend proxy
npm run dev -- --proxy=http://localhost:4466

The development server typically runs on http://localhost:3000.

Build Production Frontend

cd frontend
npm run build

Output is generated in frontend/build/.

Desktop Application (Electron)

cd app

# Development mode with hot reload
npm run dev

# Build for current platform
npm run build

# Build for specific platforms
npm run build:linux
npm run build:mac
npm run build:win

# Package without publishing
npm run package

Built binaries are located in app/dist/.

Backend/Server (if applicable)

If running the backend separately (Go-based, typically for in-cluster):

# From repository root (if Makefile exists)
make backend

# Or run the backend binary
./backend/headlamp-server

5. Deployment

In-Cluster Deployment (Recommended)

Using Helm:

# Add the Headlamp Helm repository
helm repo add headlamp https://headlamp-k8s.github.io/headlamp/
helm repo update

# Install with default settings
helm install headlamp headlamp/headlamp -n kube-system

# Or with custom values
helm install headlamp headlamp/headlamp \
  --namespace headlamp \
  --create-namespace \
  --set service.type=LoadBalancer \
  --set service.port=8080 \
  --set config.baseURL=/headlamp

Using kubectl:

# Apply the latest stable manifests
kubectl apply -f https://raw.githubusercontent.com/kubernetes-sigs/headlamp/main/kubernetes-headlamp.yaml

# Or apply from local clone
kubectl apply -k ./kubernetes/

Accessing In-Cluster Deployment:

# Port-forward for local access
kubectl port-forward -n kube-system svc/headlamp 8080:80

# Or get external IP if using LoadBalancer
kubectl get svc -n kube-system headlamp

Desktop Application Distribution

Build platform-specific installers:

cd app

# Build all platforms (from macOS with cross-compilation setup)
npm run build:all

# Individual platforms
npm run build:linux    # Produces .AppImage, .deb, .rpm, .tar.gz
npm run build:mac      # Produces .dmg, .zip
npm run build:win      # Produces .exe, .msi

Container Image Build

# Build container image locally
docker build -t headlamp:local .

# Or use the Makefile
make image

# Push to registry (requires authentication)
docker tag headlamp:local ghcr.io/your-org/headlamp:custom
docker push ghcr.io/your-org/headlamp:custom

Cloud Platform Deployment

AKS/EKS/GKE:

# Example for GKE with Ingress
helm install headlamp headlamp/headlamp \
  --set ingress.enabled=true \
  --set ingress.hosts[0].host=headlamp.yourdomain.com \
  --set ingress.hosts[0].paths[0].path=/

OpenShift:

# Install with OpenShift-specific security contexts
helm install headlamp headlamp/headlamp \
  --set openshift.enabled=true \
  --set podSecurityContext.openshift=true

6. Troubleshooting

RBAC Permission Issues

Symptom: Empty resource lists or "Forbidden" errors.

Solution:

# Check current user permissions
kubectl auth can-i list pods --all-namespaces

# Create appropriate cluster role binding
kubectl create clusterrolebinding headlamp-user-binding \
  --clusterrole=view \
  --user=your-user

Plugin Loading Failures

Symptom: Plugins not appearing in UI or "Failed to load plugin" errors.

Solution:

# Check plugin directory permissions
ls -la ~/.config/Headlamp/plugins/

# Verify plugin format (should be .tar.gz or folder with package.json)
# Clear plugin cache
rm -rf ~/.config/Headlamp/plugins/*
# Restart Headlamp and reinstall plugins

CORS Errors in Development

Symptom: "CORS policy" errors when frontend connects to backend.

Solution:

# Ensure backend is started with CORS enabled
cd backend
./headlamp-server --dev

# Or configure proxy in frontend/package.json
# Add to package.json: "proxy": "http://localhost:4466"

Desktop App Blank Screen

Symptom: White/blank window on startup.

Solution:

# Clear Electron cache
rm -rf ~/.config/Headlamp/Cache/
rm -rf ~/.config/Headlamp/GPUCache/

# Reset app data
rm -rf ~/.config/Headlamp/

# Restart with debug console
# Linux/Mac:
HEADLAMP_DEBUG=true ./headlamp
# Windows:
set HEADLAMP_DEBUG=true
headlamp.exe

Build Failures

Symptom: npm install fails with native module errors.

Solution:

# Rebuild native modules
npm run rebuild

# Or for electron specifically
cd app
npm run rebuild:electron

# Clear node_modules and reinstall
rm -rf node_modules package-lock.json
npm install

In-Cluster Authentication Issues

Symptom: Unable to log in with tokens.

Solution:

# Verify token is valid
kubectl get secret -n kube-system
kubectl create token headlamp-admin -n kube-system --duration=24h

# Check if OIDC is configured correctly in your cluster
kubectl get configmap -n kube-system extension-apiserver-authentication -o yaml

Port Conflicts

Symptom: "Port already in use" errors.

Solution:

# Find process using port 3000 (frontend) or 4466 (backend)
lsof -ti:3000 | xargs kill -9
lsof -ti:4466 | xargs kill -9

# Or use different ports
npm run dev -- --port=3001