DEV Community

John Ajera
John Ajera

Posted on

Headlamp on EKS – Install and Test

#headlamp #eks #argocd #kubernetes

Headlamp on EKS – Install and Test

Need a lightweight Kubernetes UI without the overhead of kubectl or cloud consoles? Headlamp runs in-cluster, gives you real-time visibility into workloads, logs, and events—and it's free and open source. This guide deploys it via Argo CD with Service Account token auth: no OIDC setup, no manual secrets, and access via simple port-forward. Secure, easy to run, and GitOps-friendly.

Note: This setup uses cluster-admin for simplicity—ideal for learning or individual use. For production, configure proper role-based access (RBAC) and restrict the Service Account to least-privilege roles.

1. Overview

What this guide does:

  • Deploys Headlamp using the official Helm chart via an Argo CD Application
  • Creates a Service Account headlamp with cluster-admin for token-based login
  • Persists data with EBS-backed PVC
  • Uses port-forward for local access (no ingress required)

Prerequisites:

  • EKS cluster running with kubectl context set
  • Argo CD installed

2. Prerequisites

Before starting, ensure you have:

  • kubectl configured with context set to your EKS cluster
  • Argo CD installed and syncing Applications

3. Install Headlamp

Save the manifest below as headlamp-application.yaml and apply:

kubectl apply -f headlamp-application.yaml
Enter fullscreen mode Exit fullscreen mode

Argo CD will create the Application and sync Headlamp. Wait until the Application shows Synced in the Argo CD UI or CLI.

Manifest:

apiVersion: argoproj.io/v1alpha1
kind: AppProject
metadata:
  name: platform
  namespace: argocd
spec:
  clusterResourceWhitelist:
    - group: "*"
      kind: "*"
  destinations:
    - namespace: "*"
      server: "*"
  namespaceResourceWhitelist:
    - group: "*"
      kind: "*"
  sourceRepos:
    - "*"
---
apiVersion: v1
kind: Namespace
metadata:
  name: headlamp
  labels:
    name: headlamp
---
apiVersion: argoproj.io/v1alpha1
kind: Application
metadata:
  name: headlamp
  namespace: argocd
spec:
  project: platform
  source:
    repoURL: https://kubernetes-sigs.github.io/headlamp/
    chart: headlamp
    targetRevision: 0.40.0
    helm:
      values: |
        service:
          type: ClusterIP
        config:
          inCluster: true
          oidc:
            secret:
              create: false
        serviceAccount:
          create: true
          name: headlamp
        clusterRoleBinding:
          clusterRoleName: cluster-admin
        persistentVolumeClaim:
          enabled: true
          size: 10Gi
          storageClassName: ebs-sc
          accessModes:
            - ReadWriteOnce
        resources:
          limits:
            cpu: 200m
            memory: 256Mi
          requests:
            cpu: 100m
            memory: 128Mi
  destination:
    server: https://kubernetes.default.svc
    namespace: headlamp
  syncPolicy:
    automated:
      prune: true
      selfHeal: true
    syncOptions:
      - CreateNamespace=true
Enter fullscreen mode Exit fullscreen mode

Note: The serviceAccount.create: true block creates the headlamp Service Account—this is what kubectl create token headlamp -n headlamp uses for login. Adjust storageClassName if your EKS cluster uses a different EBS storage class. Omit the AppProject and Namespace if you already have them.

4. Test Access

Port-forward 

kubectl port-forward svc/headlamp -n headlamp 8080:80
Enter fullscreen mode Exit fullscreen mode

Create token 

kubectl create token headlamp -n headlamp
Enter fullscreen mode Exit fullscreen mode

Login

Open http://localhost:8080 and paste the token when Headlamp prompts for authentication.

5. Summary: Copy-Paste 

# 1. Apply manifest
kubectl apply -f headlamp-application.yaml

# 2. Wait for sync (check Argo CD UI or: argocd app get headlamp)

# 3. Port-forward and get token
kubectl port-forward svc/headlamp -n headlamp 8080:80 &
kubectl create token headlamp -n headlamp
Enter fullscreen mode Exit fullscreen mode

Then open http://localhost:8080 and paste the token when prompted.

6. Troubleshooting

Issue: Application stuck in Syncing or OutOfSync

Solution: Check Argo CD logs and the Application status. Ensure the Headlamp Helm repo is reachable and storageClassName: ebs-sc exists in your cluster. If using a different storage class, update the manifest.

Issue: Token invalid or login fails

Solution: Ensure the Service Account exists: kubectl get sa headlamp -n headlamp. Re-run kubectl create token headlamp -n headlamp to generate a fresh token (tokens expire).

Issue: Argo CD ingress stuck or inaccessible

Solution: See your cluster's Argo CD troubleshooting docs.

7. References

Top comments (0)