Headlamp - Kubernetes Dashboard | Landry Zetam

Table of Contents

Overview

Headlamp is a user-friendly Kubernetes dashboard deployed in the Fako cluster. It provides a web-based UI for managing and monitoring Kubernetes resources across all namespaces. Headlamp offers an intuitive interface for both beginners and advanced users, with support for plugins and real-time updates. This deployment includes the Kubescape security plugin for enhanced cluster security visibility.

Key Features

User-Friendly Interface: Clean, modern UI for Kubernetes management
Real-Time Updates: Live view of cluster resources and events
Multi-Resource Support: Manage all Kubernetes resource types
Plugin Architecture: Extensible with custom plugins
In-Cluster Mode: Runs with cluster service account
Kubescape Integration: Security scanning and compliance checks
Mobile Responsive: Works on desktop and mobile devices

Architecture

Components

Deployment: Single-replica deployment
Service: ClusterIP service on port 80
Ingress: HTTPS access (configured separately)
ServiceAccount: Cluster-wide permissions for resource access
Init Container: Installs Kubescape plugin
Plugin Volume: EmptyDir for plugin storage

Resource Requirements

Memory: 128Mi (request), 512Mi (limit)
CPU: 100m (request), 500m (limit)
Storage: EmptyDir for plugins (ephemeral)

Configuration

Deployment Settings

Parameter	Value	Description
`-in-cluster`	Enabled	Run using in-cluster config
`-plugins-dir`	`/build/plugins`	Plugin directory location
Port	`4466`	Application HTTP port
Image	`ghcr.io/headlamp-k8s/headlamp:v0.33.0`	Headlamp version

RBAC Configuration

Headlamp runs with a ClusterRole that provides full access to:

Core resources (pods, services, configmaps, etc.)
Apps resources (deployments, statefulsets, etc.)
Networking resources
RBAC resources
Storage resources
Metrics
CRDs (including Kubescape)

Usage

Accessing Headlamp

External access (requires ingress configuration):

https://headlamp.your-domain.com

Internal access:

http://headlamp.headlamp.svc.cluster.local

Port forwarding for local access:

kubectl port-forward -n headlamp svc/headlamp 8080:80
# Access at http://localhost:8080

Dashboard Overview

Cluster Overview: Node status, resource usage, events
Workloads: Deployments, pods, jobs, cronjobs
Networking: Services, ingresses, network policies
Storage: PVCs, storage classes
Configuration: ConfigMaps, secrets
Security: RBAC, service accounts, Kubescape reports

Common Tasks

View Pod Logs:
- Navigate to Workloads → Pods
- Click on pod name
- Select “Logs” tab
Scale Deployment:
- Navigate to Workloads → Deployments
- Click deployment name
- Edit replica count
Create Resources:
- Click “+” button
- Paste YAML or use form
- Apply to cluster
Security Scanning (Kubescape):
- Navigate to Security section
- View compliance reports
- Check vulnerability scans

Using the Kubescape Plugin

The Kubescape plugin provides:

Security Posture: Overall cluster security score
Compliance: NSA, MITRE compliance checks
Vulnerabilities: Image vulnerability scanning
RBAC Analysis: Permission analysis
Network Policies: Policy recommendations

Operations

Checking Service Status

# Check pod status
kubectl get pods -n headlamp

# View logs
kubectl logs -n headlamp -l app.kubernetes.io/name=headlamp

# Check plugin installation
kubectl logs -n headlamp -l app.kubernetes.io/name=headlamp -c kubescape-plugin

Plugin Management

List Installed Plugins

kubectl exec -n headlamp deployment/headlamp -- ls -la /build/plugins/

Add Custom Plugin

# Create ConfigMap with plugin
kubectl create configmap my-plugin --from-file=plugin.js -n headlamp

# Mount in deployment (edit deployment.yaml)

Troubleshooting Access Issues

Check service account:

kubectl get sa headlamp -n headlamp
kubectl get clusterrolebinding headlamp

Verify RBAC permissions:

kubectl auth can-i --list --as=system:serviceaccount:headlamp:headlamp

Troubleshooting

Dashboard Not Loading

Check pod status:

kubectl describe pod -n headlamp -l app.kubernetes.io/name=headlamp

Verify service endpoints:

kubectl get endpoints -n headlamp

Check ingress (if configured):

kubectl get ingress -n headlamp
kubectl describe ingress headlamp -n headlamp

Permission Errors

Verify ClusterRole binding:

kubectl get clusterrole headlamp -o yaml

Check specific permissions:

# Test specific resource access
kubectl auth can-i get pods --all-namespaces \
  --as=system:serviceaccount:headlamp:headlamp

Plugin Issues

Check init container logs:

kubectl logs -n headlamp -l app.kubernetes.io/name=headlamp -c kubescape-plugin --previous

Verify plugin files:

kubectl exec -n headlamp deployment/headlamp -- find /build/plugins -type f

Performance Issues

Check resource usage:

kubectl top pod -n headlamp

Review browser console:
- Open browser developer tools
- Check for JavaScript errors
- Monitor network requests

Security Considerations

RBAC Permissions

Headlamp has cluster-admin level access
Consider creating custom ClusterRole with limited permissions
Use NetworkPolicies to restrict access

Authentication

Default deployment has no authentication
Integrate with OAuth2 proxy or similar
Consider using Keycloak for SSO

Network Security

Use HTTPS via ingress
Implement network policies
Consider IP whitelisting

Best Practices

Regular Updates: Keep Headlamp and plugins updated
Audit Access: Monitor who accesses the dashboard
Limit Permissions: Use least-privilege RBAC if possible
Secure Ingress: Use TLS and authentication
Monitor Usage: Track API calls made by Headlamp

Customization

Adding Authentication

Example OAuth2 Proxy configuration:

# oauth2-proxy deployment
- name: oauth2-proxy
  image: quay.io/oauth2-proxy/oauth2-proxy:latest
  args:
  - --provider=keycloak-oidc
  - --client-id=headlamp
  - --client-secret=$CLIENT_SECRET
  - --upstream=http://headlamp:80
  - --http-address=0.0.0.0:4180

Custom Plugins

Create a plugin:

// my-plugin/main.js
import { registerPlugin } from '@kinvolk/headlamp-plugin';

registerPlugin({
  name: 'my-plugin',
  version: '0.1.0',
  init: () => {
    console.log('My plugin initialized');
  }
});

Theme Customization

Headlamp supports custom themes:

// Custom theme configuration
window.HEADLAMP_CONFIG = {
  theme: {
    palette: {
      primary: {
        main: '#1976d2',
      },
    },
  },
};

Monitoring

Key Metrics

Response time for API calls
Memory usage (watch for leaks)
Error rate in browser console
Plugin loading time
WebSocket connection stability

Browser Performance

Use browser developer tools
Monitor memory usage
Check network waterfall
Profile JavaScript execution

Integration Examples

With Prometheus

View Prometheus metrics in Headlamp:

Install Prometheus plugin
Configure Prometheus endpoint
View metrics in dashboard

With Grafana

Link to Grafana dashboards:

Add custom links in Headlamp
Configure deep linking
Pass context (namespace, pod, etc.)

With Alerting

Integrate with alert systems:

Configure webhook notifications
Add alert annotations
Display in Headlamp UI

Maintenance

Regular Tasks

Weekly:
- Review error logs
- Check plugin updates
- Monitor resource usage
Monthly:
- Update Headlamp version
- Review RBAC permissions
- Audit access logs
Quarterly:
- Security audit
- Performance optimization
- Plugin compatibility check

Upgrade Procedure

Check compatibility:
- Review changelog
- Test in staging
Update deployment:

image: ghcr.io/headlamp-k8s/headlamp:v0.34.0

Verify functionality:
- Test core features
- Check plugin compatibility

Performance Optimization

Client-Side

Enable browser caching
Use CDN for static assets
Minimize plugin size
Implement lazy loading

Server-Side

Increase resource limits if needed
Use horizontal pod autoscaling
Implement caching proxy
Optimize API calls

Network

Enable compression
Use HTTP/2
Implement request batching
Cache API responses

Future Improvements

Implement SSO with Keycloak
Add custom branding
Create cluster-specific plugins
Add multi-cluster support
Implement role-based UI
Add dark mode
Create mobile app
Add CLI integration
Implement audit logging
Add cost management plugin