SEO 키워드: EKS Headlamp 설치, Kubernetes 웹 UI, Headlamp EKS, k8s 대시보드, Lens 대안, CNCF Headlamp, EKS 모니터링
들어가며
Kubernetes 클러스터를 운영하다 보면 CLI만으로는 한계를 느낄 때가 있습니다. 특히 멀티 클러스터 환경이나 팀원과 함께 리소스를 확인해야 할 때 시각적인 대시보드는 생산성을 크게 높여줍니다. 오랫동안 Lens가 사실상의 표준처럼 쓰였지만, 유료화 이슈 이후 많은 엔지니어들이 대안을 찾고 있습니다. 그 대안 중 가장 주목받는 것이 바로 Headlamp입니다.
이 글에서는 AWS EKS 환경에 Headlamp를 설치하고 실제로 활용하는 방법을 단계별로 정리합니다.
Headlamp란 무엇인가?
┌─────────────────────────────────────────────────────┐
│ Headlamp 아키텍처 │
│ │
│ 브라우저 │
│ ┌────────┐ HTTPS ┌──────────────────────┐ │
│ │ Web │ ──────────▶ │ Headlamp Pod │ │
│ │ UI │ ◀────────── │ (in-cluster) │ │
│ └────────┘ │ │ │
│ │ - React Frontend │ │
│ │ - Go Backend Proxy │ │
│ └────────┬─────────────┘ │
│ │ kubectl API │
│ ┌────────▼─────────────┐ │
│ │ Kubernetes API │ │
│ │ Server (EKS) │ │
│ └──────────────────────┘ │
└─────────────────────────────────────────────────────┘Headlamp는 CNCF(Cloud Native Computing Foundation) Sandbox 프로젝트로 등록된 완전 오픈소스 Kubernetes 웹 UI입니다. Apache 2.0 라이선스로 제공되며, 플러그인 기반의 확장 가능한 아키텍처를 갖추고 있습니다.
기존 Kubernetes Dashboard가 기능이 빈약하고, Lens가 부분 유료화된 상황에서 Headlamp는 다음과 같은 장점으로 각광받고 있습니다.
- 완전 오픈소스: 라이선스 걱정 없이 상업 환경에서도 자유롭게 사용 가능
- 플러그인 시스템: 기능을 자유롭게 확장 가능
- 멀티 클러스터 지원: 여러 클러스터를 하나의 UI에서 관리
- 가벼운 리소스: Lens 대비 훨씬 적은 메모리 사용
- RBAC 친화적: Kubernetes 기본 인증 체계와 자연스럽게 통합
EKS 환경에서의 사전 준비
Headlamp를 EKS에 설치하기 전 다음 항목을 확인합니다.
필수 조건
- EKS 클러스터 (1.24 이상 권장)
- kubectl 및 helm CLI 설치 완료
- 클러스터에 대한 admin 권한
- (선택) ALB Ingress Controller 설치 완료
Helm으로 EKS에 Headlamp 설치하기
1단계: Helm 레포지토리 추가
helm repo add headlamp https://headlamp-k0s.github.io/headlamp/
helm repo update2단계: values 파일 작성
운영 환경에서는 --set 옵션보다 values 파일로 관리하는 것이 좋습니다.
# headlamp-values.yaml
replicaCount: 1
ingress:
enabled: true
annotations:
kubernetes.io/ingress.class: alb
alb.ingress.kubernetes.io/scheme: internet-facing
alb.ingress.kubernetes.io/target-type: ip
alb.ingress.kubernetes.io/listen-ports: '[{"HTTPS":443}]'
alb.ingress.kubernetes.io/certificate-arn: arn:aws:acm:ap-northeast-2:ACCOUNT_ID:certificate/CERT_ID
hosts:
- host: headlamp.your-domain.com
paths:
- path: /
type: Prefix
resources:
requests:
cpu: 100m
memory: 128Mi
limits:
cpu: 500m
memory: 256Mi3단계: 설치
kubectl create namespace headlamp
helm install headlamp headlamp/headlamp \
--namespace headlamp \
--values headlamp-values.yaml4단계: 설치 확인
kubectl get all -n headlamp로그인 토큰 발급 (EKS 1.24+)
EKS 1.24부터 Secret 기반 서비스 어카운트 토큰이 자동 생성되지 않습니다. 수동으로 토큰을 발급해야 합니다.
ServiceAccount 및 RBAC 설정
# ServiceAccount 생성
kubectl create serviceaccount headlamp-admin -n headlamp
# ClusterRoleBinding 생성 (운영 환경에서는 최소 권한 Role 권장)
kubectl create clusterrolebinding headlamp-admin \
--clusterrole=cluster-admin \
--serviceaccount=headlamp:headlamp-admin토큰 발급
# 24시간 유효 토큰 발급
kubectl create token headlamp-admin -n headlamp --duration=24h출력된 토큰을 복사하여 Headlamp 로그인 화면에 붙여넣으면 됩니다.
최소 권한 RBAC 구성 (보안 권장)
실제 운영 환경에서 cluster-admin은 과도한 권한입니다. 용도에 맞게 최소 권한으로 구성합니다.
# headlamp-role.yaml
apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRole
metadata:
name: headlamp-readonly
rules:
- apiGroups: [""]
resources:
- pods
- services
- endpoints
- namespaces
- nodes
- configmaps
- events
verbs: ["get", "list", "watch"]
- apiGroups: ["apps"]
resources:
- deployments
- replicasets
- statefulsets
- daemonsets
verbs: ["get", "list", "watch"]
- apiGroups: ["batch"]
resources:
- jobs
- cronjobs
verbs: ["get", "list", "watch"]
---
apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRoleBinding
metadata:
name: headlamp-readonly-binding
roleRef:
apiGroup: rbac.authorization.k8s.io
kind: ClusterRole
name: headlamp-readonly
subjects:
- kind: ServiceAccount
name: headlamp-admin
namespace: headlampkubectl apply -f headlamp-role.yaml로컬에서 포트포워딩으로 접근하기
Ingress 없이 빠르게 확인하고 싶다면 포트포워딩을 활용합니다.
kubectl port-forward svc/headlamp 8080:80 -n headlamp브라우저에서 http://localhost:8080 접속 후 토큰으로 로그인합니다.
Lens vs Headlamp 비교
항목LensHeadlamp
| 라이선스 | 부분 유료 (Personal 무료) | Apache 2.0 완전 오픈소스 |
| 설치 방식 | 데스크탑 앱 | 웹 UI (in-cluster / 로컬) |
| 멀티 클러스터 | ✅ | ✅ |
| 플러그인 | ✅ | ✅ |
| 리소스 사용량 | 무거움 (Electron 기반) | 가벼움 |
| RBAC 통합 | 별도 처리 필요 | 기본 SA 토큰 사용 |
| 팀/브라우저 접근 | ❌ (개인 앱) | ✅ (URL 공유 가능) |
팀 단위 운영 환경이라면 Headlamp의 브라우저 기반 접근이 훨씬 유리합니다. URL 하나로 팀원 모두가 같은 클러스터 상태를 볼 수 있습니다.
자주 발생하는 문제와 해결법
토큰 만료 오류
kubectl create token 명령의 --duration 값을 늘리거나, 스크립트로 주기적 갱신을 자동화합니다.
ALB에서 502 에러
Headlamp는 기본적으로 컨테이너 포트 4466을 사용합니다. ALB 타겟 그룹의 health check 경로를 / 로 설정하고, 타겟 포트가 올바른지 확인합니다.
멀티 클러스터 연결
로컬 데스크탑 앱 버전을 사용하면 kubeconfig의 여러 context를 자동으로 인식합니다. in-cluster 방식은 클러스터별로 별도 Headlamp 인스턴스를 배포하거나 플러그인을 활용합니다.
마치며
Headlamp는 EKS를 포함한 모든 Kubernetes 환경에서 사용할 수 있는 강력한 오픈소스 웹 UI입니다. Lens의 유료화 이후 실질적인 대안으로 자리잡고 있으며, CNCF 프로젝트답게 커뮤니티 성장세도 빠릅니다.
특히 팀 단위 운영, 브라우저 기반 접근, RBAC 친화적 구조가 필요한 환경이라면 Headlamp는 현재 시점에서 가장 현실적인 선택입니다. 한번 설치해두면 클러스터 디버깅과 리소스 모니터링 생산성이 눈에 띄게 향상됩니다.
관련 태그: #EKS #Kubernetes #Headlamp #k8s대시보드 #CNCF #Lens대안 #클라우드인프라 #AWS