시리즈 안내
이 글은 “중소기업 쿠버네티스 구축” 시리즈의 6편입니다. 5편에서 외부 노출 경로(DNS→TLS→MetalLB→Ingress)를 완성했습니다. 이번 편에서는 그 경로 위에 올리는 첫 서비스로 웹 대시보드(Headlamp)를 설치합니다. 지금까지 터미널에서kubectl로만 보던 클러스터를 이제 브라우저에서 눈으로 봅니다.
들어가며
지금까지는 클러스터 상태를 볼 때마다 kubectl get pods, kubectl describe, kubectl logs를 쳐야 했습니다. 익숙해지면 빠르지만, 한눈에 전체를 파악하거나 팀원과 공유하기엔 불편합니다.
웹 대시보드가 있으면 브라우저에서 노드·Pod·서비스·로그를 클릭으로 둘러볼 수 있습니다. 5편에서 외부 노출 경로를 완성했으니, 그 경로를 처음으로 써먹는 좋은 대상이기도 합니다. 대시보드를 띄우고 https://dash.prd.dztechwill.com으로 접속되는지 확인하면, 5편에서 만든 길이 실제로 뚫렸는지도 함께 검증됩니다.
1. 왜 Headlamp인가
쿠버네티스 대시보드라고 하면 흔히 공식 Kubernetes Dashboard를 떠올립니다. 하지만 공식 대시보드는 사실상 유지보수가 정체되어 권장도가 떨어졌습니다. 그래서 우리는 Headlamp를 선택했습니다.
Headlamp는 CNCF(클라우드 네이티브 컴퓨팅 재단) 산하 프로젝트로, 현대적이고 활발히 개발되는 대시보드입니다.
- 깔끔한 UI로 노드·워크로드·네트워크·스토리지를 한눈에
- 실시간 로그 조회, 리소스 편집, 이벤트 확인
- 플러그인 확장 지원
- ServiceAccount 토큰 기반의 명확한 인증
중소기업 운영자가 클러스터를 직관적으로 파악하기에 적합합니다.
2. Headlamp 설치 (Helm)
Helm으로 설치합니다. 5편에서 Helm을 이미 준비했으니 저장소만 추가하면 됩니다.
helm repo add headlamp https://kubernetes-sigs.github.io/headlamp/
helm repo update플랫폼 노드에 배치하도록 설치합니다.
helm install headlamp headlamp/headlamp
--namespace kubernetes-dashboard --create-namespace
--set nodeSelector.role=platformnodeSelector.role=platform으로 3편에서 라벨링한 플랫폼 노드에 뜨게 합니다. 관리 도구는 플랫폼 노드에 모으는 원칙을 계속 지킵니다.
설치 확인
kubectl get pods -n kubernetes-dashboardHeadlamp Pod가 Running이 되면 준비 완료입니다.
3. Ingress로 외부 노출
5편에서 만든 경로에 Headlamp를 연결합니다. dash.prd.dztechwill.com으로 접속하면 Headlamp로 가도록 Ingress를 만듭니다.
cat <<EOF | kubectl apply -f -
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
name: headlamp-ingress
namespace: kubernetes-dashboard
spec:
ingressClassName: nginx
rules:
- host: dash.prd.dztechwill.com
http:
paths:
- path: /
pathType: Prefix
backend:
service:
name: headlamp
port:
number: 80
EOF이제 흐름은 이렇습니다.
[브라우저] https://dash.prd.dztechwill.com
▼ (OPNsense Caddy: TLS 종단)
[MetalLB .200] → [Ingress-NGINX]
▼ (Host: dash.prd... 매칭)
[Headlamp 서비스 → Pod]접속이 안 되면 두 가지를 확인하세요. (1) OPNsense Caddy에
dash.prd...또는 와일드카드*.prd...라우팅이 있는지, (2) Unbound DNS에 해당 도메인이 등록돼 MetalLB IP로 해석되는지. 5편에서 와일드카드로 설정했다면 보통 자동으로 커버됩니다.
4. 로그인 토큰 발급 (ServiceAccount)
Headlamp는 ServiceAccount 토큰으로 로그인합니다. ServiceAccount는 사람이 아닌 “프로그램·도구가 클러스터에 접근할 때 쓰는 계정”입니다. 대시보드에 줄 권한을 가진 계정을 만들고 그 토큰으로 로그인하는 방식이죠.
관리자 ServiceAccount 생성
대시보드용 계정을 만들고 클러스터 관리 권한을 부여합니다.
# ServiceAccount 생성
kubectl create serviceaccount headlamp-admin -n kubernetes-dashboard
# 클러스터 관리자 권한 부여
kubectl create clusterrolebinding headlamp-admin
--clusterrole=cluster-admin
--serviceaccount=kubernetes-dashboard:headlamp-admin
cluster-admin은 모든 권한을 가진 강력한 역할입니다. 혼자 운영하거나 신뢰된 관리자만 쓰는 환경에선 편리하지만, 여러 사람이 쓴다면 필요한 만큼만 권한을 주는 별도 Role을 만드는 게 안전합니다. 여기서는 단순함을 위해 관리자 권한으로 진행합니다.
토큰 발급
로그인에 쓸 토큰을 생성합니다.
kubectl create token headlamp-admin -n kubernetes-dashboard긴 토큰 문자열이 출력됩니다. 이걸 복사합니다.
이 명령으로 만든 토큰은 기본 1시간 후 만료됩니다. 더 길게 쓰고 싶으면
--duration옵션을 줄 수 있습니다(예:--duration=24h). 만료되면 같은 명령으로 새로 발급하면 됩니다.
5. 접속과 둘러보기
브라우저에서 https://dash.prd.dztechwill.com에 접속합니다. 로그인 화면이 나오면 토큰 인증 방식을 고르고, 방금 복사한 토큰을 붙여넣습니다.
로그인하면 이런 것들을 볼 수 있습니다.
- 클러스터 개요: 노드 4대의 상태, CPU·메모리 사용량
- 워크로드: 네임스페이스별 Deployment·Pod 목록과 상태
- 로그: Pod를 클릭해 실시간 로그 조회 (
kubectl logs없이) - 이벤트: 클러스터에서 일어나는 일들(스케줄링·재시작·오류)을 시간순으로
지금까지 우리가 설치한 것들 — MetalLB, Ingress-NGINX, Headlamp 자신 — 이 각 네임스페이스에 떠 있는 게 보일 겁니다. 터미널로만 상상하던 클러스터가 시각적으로 드러나는 순간입니다.
6. 이 편이 검증해준 것
Headlamp 설치는 단순히 대시보드 하나를 얻은 것 이상의 의미가 있습니다. 5편에서 만든 외부 노출 경로 전체가 실제로 동작함을 처음으로 입증했습니다.
DNS(Unbound) → TLS(Caddy) → LoadBalancer(MetalLB)
→ Ingress(NGINX) → Service → Pod(Headlamp)이 긴 사슬 중 하나라도 끊겼으면 대시보드에 접속할 수 없습니다. 접속이 됐다는 건 모든 고리가 정확히 맞물렸다는 뜻입니다. 앞으로 ArgoCD·MinIO 등 무엇을 올리든 같은 경로를 타니, 이 검증은 든든한 토대가 됩니다.
마치며
6편에서는 클러스터에 눈을 달았습니다.
- Headlamp 선택: 유지보수가 정체된 공식 대시보드 대신, 활발히 개발되는 CNCF 프로젝트를 택했습니다.
- Helm 설치 + 플랫폼 노드 배치: 관리 도구를 플랫폼 노드에 모으는 원칙을 유지했습니다.
- Ingress 연결: 5편 경로에 첫 서비스를 올려
dash.prd...로 외부 노출했습니다. - ServiceAccount 인증: 토큰 기반 로그인의 개념과 발급 방법을 익혔습니다.
이제 클러스터를 눈으로 보며 운영할 수 있습니다. 다음 편은 시리즈에서 가장 중요한 갈림길 중 하나입니다. 07편 — GitOps 배포 자동화(ArgoCD)에서는 ArgoCD를 설치하는 동시에, “ArgoCD가 정말 필요한가? 배포 전략에 따라 어떻게 달라지는가“라는 질문에 정면으로 답하겠습니다.
이전 글: 중소기업 쿠버네티스 구축 – 05. Ingress와 TLS 연동: 외부 노출 완성
다음 글: 중소기업 쿠버네티스 구축 – 07. GitOps 배포 자동화: ArgoCD 도입과 판단 (ArgoCD·Gitea·app-of-apps)
