Kubernetes를 처음 접한 사람에게 Kubernetes Dashboard는 익숙한 도구였습니다. Pod와 Deployment 상태를 웹 화면에서 확인하고, 로그를 보거나 YAML을 수정할 수 있어 kubectl이 낯선 사용자에게 좋은 출발점이었습니다.
하지만 이제 상황이 달라졌습니다. Kubernetes 공식 문서는 Dashboard를 deprecated and unmaintained, 즉 사용 중단 예정이며 유지보수되지 않는 프로젝트로 명시하고 있습니다. 프로젝트 저장소도 2026년 1월 21일 보관 처리되어 읽기 전용 상태가 되었습니다.
공식 문서가 신규 설치의 대안으로 안내하는 도구가 Headlamp입니다. Headlamp는 단순히 예전 Dashboard 화면을 다시 만든 제품이 아니라, 멀티 클러스터·플러그인·데스크톱 실행과 인클러스터 배포를 함께 지원하는 현대적인 Kubernetes UI입니다.
이 글에서는 Dashboard의 deprecated가 운영 환경에 어떤 의미인지, Headlamp가 무엇을 개선했는지, 실제 전환 과정에서 인증과 RBAC를 어떻게 설계해야 하는지를 정리합니다.
Kubernetes Dashboard에 무슨 일이 생겼나
Kubernetes 공식 Dashboard 문서에는 현재 다음 내용이 명확히 표시되어 있습니다.
Kubernetes Dashboard is deprecated and unmaintained.
이는 단순히 최신 기능이 늦게 추가된다는 뜻이 아닙니다. 저장소가 보관 처리되고 적극적인 유지보수가 종료되었기 때문에 새로운 Kubernetes 버전과의 호환성, 보안 취약점 대응, 의존성 갱신을 기대하기 어려워졌다는 의미입니다.
| 구분 | 현재 상태 |
| Kubernetes Dashboard 문서 | deprecated and unmaintained 명시 |
| GitHub 저장소 | 2026년 1월 21일 보관, 읽기 전용 |
| 신규 설치 권고 | Headlamp 검토 |
| 기존 설치 | 즉시 중단보다 사용 현황을 파악한 뒤 계획적으로 이전 |
Deprecated가 곧바로 모든 설치가 작동을 멈춘다는 뜻은 아닙니다. 기존 Dashboard Pod와 Service는 계속 실행될 수 있습니다. 그러나 시간이 지날수록 지원되지 않는 관리 화면을 클러스터 API에 연결해 두는 부담이 커집니다.
특히 Dashboard는 다음과 같은 민감한 기능을 제공할 수 있습니다.
- 클러스터 리소스 조회
- YAML 생성과 수정
- Pod 로그 조회
- Pod 내부 명령 실행
- Secret을 포함한 구성 리소스 접근
- Deployment 스케일 조정과 재시작
유지보수가 끝난 UI를 높은 권한의 ServiceAccount와 함께 계속 노출하는 것은 좋은 운영 선택이 아닙니다.
왜 Kubernetes Dashboard가 한계에 도달했을까
Kubernetes Dashboard는 한 클러스터 안에서 실행되는 단순한 웹 UI로 출발했습니다. 소규모 실습 환경에서는 충분했지만 Kubernetes 운영 방식이 바뀌면서 한계가 분명해졌습니다.
한 번에 하나의 클러스터를 보는 구조
Dashboard는 일반적으로 클러스터마다 별도로 설치합니다. 개발·스테이징·운영 클러스터가 여러 개라면 각 Dashboard URL과 인증 토큰을 따로 관리하게 됩니다.
클러스터 수가 늘어날수록 다음 문제가 생깁니다.
- 클러스터마다 Dashboard 배포와 업그레이드 필요
- 여러 URL과 Ingress 정책 관리
- ServiceAccount와 RoleBinding 중복
- 사용자가 현재 어느 클러스터를 보고 있는지 혼동
- 환경 간 리소스 비교가 어려움
Bearer Token 중심의 불편한 로그인
Dashboard는 주로 ServiceAccount의 Bearer Token을 입력해 로그인하는 방식으로 사용되었습니다. 간단하지만 조직 환경에서는 토큰 발급·전달·보관·회수가 번거롭습니다.
편의를 위해 장기간 유효한 토큰이나 cluster-admin 권한 계정을 공유하면 보안 위험이 커집니다. 토큰이 브라우저 기록, 메신저, 문서나 터미널 출력에 남을 수도 있습니다.
확장하기 어려운 고정된 UI
현대적인 Kubernetes 플랫폼은 기본 리소스만 보여주는 것으로 충분하지 않습니다.
- Argo CD와 Flux의 배포 상태
- Prometheus 메트릭
- Trivy와 Kubescape의 보안 결과
- OpenCost 비용 정보
- KubeVirt 가상머신
- 조직 고유의 CRD와 운영 워크플로
Dashboard는 이런 도구를 하나의 사용자 경험으로 확장하기 어려웠습니다.
Headlamp는 어떤 프로젝트인가
Headlamp는 사용하기 쉽고 확장 가능한 Kubernetes Web UI입니다. 현재 Kubernetes SIG UI에 속한 공식 Kubernetes 서브프로젝트로 개발되고 있습니다.
Headlamp는 두 가지 형태로 실행할 수 있습니다.
| 실행 방식 | 연결 방법 | 적합한 사용 사례 |
| 데스크톱 앱 | 사용자의 kubeconfig | 개인 운영자, 여러 클러스터, 빠른 도입 |
| 인클러스터 Web UI | ServiceAccount 또는 OIDC | 팀 공용 UI, 중앙 URL, 조직 인증 연동 |
데스크톱 앱은 클러스터 안에 UI를 배포하지 않아도 됩니다. 사용자의 기존 kubeconfig에 등록된 여러 클러스터를 하나의 앱에서 전환할 수 있습니다.
그림: 단일 클러스터 중심의 Dashboard에서 멀티 클러스터 Headlamp로 확장되는 흐름 · 출처: Kubernetes 공식 전환 문서 (CC BY 4.0)
인클러스터 방식은 Dashboard처럼 Kubernetes에 Headlamp를 배포하고 브라우저로 접속합니다. 팀에 공용 URL을 제공하거나 OIDC 로그인을 연결하고 싶을 때 적합합니다.
Dashboard와 Headlamp 비교
| 항목 | Kubernetes Dashboard | Headlamp |
| 프로젝트 상태 | Deprecated, 저장소 보관 | 활발히 개발되는 Kubernetes SIG UI 프로젝트 |
| 배포 방식 | 인클러스터 | 데스크톱 또는 인클러스터 |
| 멀티 클러스터 | 클러스터별 별도 접근 | 데스크톱에서 kubeconfig 기반 전환 |
| 인증 | 주로 ServiceAccount 토큰 | kubeconfig, 토큰, 클라이언트 인증서, OIDC |
| 권한 제어 | Kubernetes RBAC | Kubernetes RBAC |
| 확장성 | 제한적 | 플러그인 지원 |
| 애플리케이션 관점 | 리소스 중심 | Projects와 Map View 등 확장된 관점 |
| 생태계 연동 | 제한적 | Flux, Prometheus, Trivy, OpenCost 등 플러그인 |
Headlamp가 별도의 권한 시스템을 만드는 것은 아닙니다. 사용자가 볼 수 있는 리소스와 수행 가능한 작업은 Kubernetes API의 RBAC 결과를 따릅니다.
그림: Headlamp Map View가 워크로드와 서비스의 관계를 시각화한 모습 · 출처: Kubernetes 공식 전환 문서 (CC BY 4.0)
이 점이 중요합니다.
Headlamp를 설치했다고 권한이 안전해지는 것이 아니라, Headlamp에 어떤 인증 정보와 RBAC 권한을 연결했는지가 안전성을 결정한다.
가장 간단한 전환: Headlamp 데스크톱 앱
개별 운영자나 플랫폼 엔지니어가 사용하는 환경이라면 데스크톱 앱이 가장 간단합니다.
macOS에서는 Homebrew로 설치할 수 있습니다.
brew install --cask headlamp
Windows에서는 WinGet을 사용할 수 있습니다.
winget install headlamp
Linux에서는 Flatpak 패키지가 제공됩니다.
flatpak install flathub io.kinvolk.Headlamp
Headlamp 데스크톱 앱은 기본적으로 사용자의 kubeconfig를 읽습니다. 여러 kubeconfig를 사용할 경우 KUBECONFIG 환경변수로 지정할 수 있습니다.
KUBECONFIG=~/.kube/dev:~/.kube/staging:~/.kube/prod headlamp
데스크톱 방식의 장점은 다음과 같습니다.
- 클러스터에 새로운 Web UI를 배포하지 않음
- Ingress와 공용 Service가 필요하지 않음
- 기존 kubeconfig와 사용자 인증을 재사용
- 여러 클러스터를 한 화면에서 전환
- 각 사용자의 Kubernetes 권한을 그대로 적용
반면 사용자 PC의 kubeconfig 보안과 앱 배포·업데이트를 관리해야 합니다. 공용 운영 화면을 제공하려는 목적에는 인클러스터 방식이 더 적합할 수 있습니다.
팀 공용 UI: Helm으로 인클러스터 설치
Headlamp 공식 Helm 저장소를 추가합니다.
helm repo add headlamp https://kubernetes-sigs.github.io/headlamp/
helm repo update
별도 Namespace를 만들고 Headlamp를 설치합니다.
kubectl create namespace headlamp
helm upgrade --install headlamp headlamp/headlamp \
--namespace headlamp
Pod와 Service 상태를 확인합니다.
kubectl get pods,svc -n headlamp
처음 기능을 시험할 때는 외부에 공개하기보다 port-forward를 사용하는 편이 안전합니다.
kubectl port-forward -n headlamp svc/headlamp 8080:80
브라우저에서 다음 주소로 접속합니다.
http://127.0.0.1:8080
운영 환경에서는 Helm 기본값을 그대로 공개하지 말고 Ingress, TLS, 인증, NetworkPolicy와 리소스 제한을 조직 기준에 맞게 설정해야 합니다.
cluster-admin 토큰을 만들기 전에 생각할 것
Headlamp 공식 설치 문서는 빠른 테스트 예제로 ServiceAccount에 cluster-admin을 연결하는 방법을 보여줍니다. 기능 확인에는 편리하지만 운영 환경의 기본 설계로 사용해서는 안 됩니다.
다음 구성은 강력한 권한을 갖습니다.
kubectl create serviceaccount headlamp-admin -n headlamp
kubectl create clusterrolebinding headlamp-admin \
--serviceaccount=headlamp:headlamp-admin \
--clusterrole=cluster-admin
kubectl create token headlamp-admin -n headlamp
이 토큰이 노출되면 클러스터 전체를 제어할 수 있습니다. Dashboard에서 사용하던 cluster-admin 토큰을 이름만 바꿔 Headlamp에 넣는다면 UI는 교체되지만 보안 문제는 그대로 남습니다.
운영 환경에서는 다음 원칙이 필요합니다.
- 사람마다 개별 신원을 사용합니다.
- 가능하면 OIDC를 통해 조직 계정으로 로그인합니다.
- Namespace와 직무에 맞는 Role·ClusterRole을 정의합니다.
- 읽기 전용 사용자와 변경 권한 사용자를 분리합니다.
- Secret 조회와 Pod exec 권한을 별도로 검토합니다.
- 공유 ServiceAccount 토큰 사용을 최소화합니다.
- 감사 로그에서 사용자별 작업을 추적할 수 있게 합니다.
읽기 전용 권한부터 시작하는 예시
전체 클러스터를 조회하되 변경할 수 없는 계정이 필요하다면 Kubernetes 기본 view ClusterRole을 활용할 수 있습니다.
kubectl create serviceaccount headlamp-viewer -n headlamp
kubectl create clusterrolebinding headlamp-viewer \
--serviceaccount=headlamp:headlamp-viewer \
--clusterrole=view
kubectl create token headlamp-viewer -n headlamp
하지만 view 권한도 모든 조직에 그대로 적합한 것은 아닙니다. 특정 Namespace만 보여야 한다면 ClusterRoleBinding 대신 Namespace 단위 RoleBinding을 사용합니다.
kubectl create rolebinding headlamp-team-a-view \
--namespace team-a \
--clusterrole view \
--serviceaccount headlamp:headlamp-viewer
실제 권한은 배포 전에 kubectl auth can-i로 확인합니다.
kubectl auth can-i --list \
--as system:serviceaccount:headlamp:headlamp-viewer
특정 고위험 동작도 따로 확인합니다.
kubectl auth can-i get secrets \
--all-namespaces \
--as system:serviceaccount:headlamp:headlamp-viewer
kubectl auth can-i create pods/exec \
--all-namespaces \
--as system:serviceaccount:headlamp:headlamp-viewer
UI에 버튼이 보이지 않는지만 확인하지 말고 Kubernetes API가 실제로 작업을 거부하는지 검증해야 합니다.
OIDC를 붙이면 무엇이 좋아질까
팀이 함께 사용하는 인클러스터 Headlamp라면 OIDC 연동을 검토할 가치가 큽니다.
OIDC를 사용하면 다음과 같은 운영 모델을 만들 수 있습니다.
사용자
→ 조직 Identity Provider
→ Headlamp
→ Kubernetes API
→ 사용자·그룹 기반 RBAC
장점은 명확합니다.
- 공유 토큰을 전달하지 않아도 됨
- 퇴사와 부서 이동을 중앙 계정에서 처리
- 사용자와 그룹을 Kubernetes RBAC에 매핑
- 감사 로그에서 사람의 신원을 구분
- MFA와 조건부 접근 정책 활용 가능
OIDC 설정에서는 Redirect URI, Client ID, Client Secret 저장 방식과 Kubernetes API Server의 OIDC 설정을 함께 맞춰야 합니다. Headlamp URL이 바뀌면 Redirect URI도 갱신해야 합니다.
Headlamp 플러그인은 장점이자 새로운 공급망 경계다
Headlamp의 큰 차별점은 플러그인입니다. 기본 Kubernetes 리소스뿐 아니라 조직이 사용하는 도구를 UI에 통합할 수 있습니다.
공식 문서와 프로젝트 자료에는 다음과 같은 생태계 연동이 소개되어 있습니다.
- Flux
- Prometheus
- Trivy
- Kubescape
- OpenCost
- KubeVirt
- Backstage
플러그인은 운영 경험을 크게 개선하지만 신뢰 경계도 넓힙니다.
- 플러그인 출처와 유지보수 상태
- 요청하는 Kubernetes 권한
- 프론트엔드에서 접근하는 데이터
- 외부 API와 네트워크 통신
- 버전 호환성과 업데이트 절차
- 패키지 무결성과 공급망 보안
플러그인을 설치하기 전에 소스, 릴리스 서명, 권한과 네트워크 동작을 검토해야 합니다. 사용하지 않는 플러그인을 무작정 추가하지 않는 것이 좋습니다.
Dashboard에서 Headlamp로 옮기는 현실적인 순서
새 UI를 설치한 즉시 기존 Dashboard를 삭제할 필요는 없습니다. 일정 기간 병행하면서 핵심 기능과 권한을 비교하는 편이 안전합니다.
1단계: 현재 Dashboard 사용 현황 조사
- 누가 Dashboard를 사용하는가
- 어떤 Namespace와 클러스터에 접근하는가
- 로그·exec·YAML 수정 중 어떤 기능을 사용하는가
- 어떤 ServiceAccount와 RoleBinding이 연결되어 있는가
- Ingress와 외부 접근 경로가 있는가
2단계: Headlamp 실행 방식을 선택
| 요구사항 | 권장 시작점 |
| 운영자 개인이 여러 클러스터 관리 | 데스크톱 앱 |
| 팀 공용 URL 필요 | 인클러스터 |
| 조직 계정과 MFA 연동 | 인클러스터 + OIDC |
| 클러스터에 UI를 추가하고 싶지 않음 | 데스크톱 앱 |
| 플러그인으로 플랫폼 기능 통합 | 두 방식 모두 검토 가능 |
3단계: 최소 권한으로 기능 검증
- 리소스 목록과 상세 정보
- 로그와 이벤트
- YAML 조회·수정
- Pod exec
- Namespace 전환
- 멀티 클러스터 전환
- Custom Resource 표시
- 필요한 플러그인
각 기능은 권한이 허용된 사용자와 거부되어야 하는 사용자 모두로 시험합니다.
4단계: Headlamp 접근 경로 보안
- TLS가 적용된 별도 호스트 사용
- OIDC 또는 승인된 인증 방식 적용
- 공용 인터넷 노출 최소화
- NetworkPolicy와 방화벽 제한
- CSP와 보안 헤더 검토
- 접속·변경 작업 감사
- Helm Chart와 이미지 버전 고정
5단계: Dashboard 제거
Headlamp로 주요 업무와 권한 검증을 마친 뒤 기존 Dashboard를 제거합니다.
Helm으로 설치했다면 다음처럼 삭제할 수 있습니다.
helm uninstall kubernetes-dashboard \
-n kubernetes-dashboard
남은 리소스를 확인합니다.
kubectl get all,sa,role,rolebinding \
-n kubernetes-dashboard
Dashboard 전용 ClusterRoleBinding도 확인합니다.
kubectl get clusterrolebinding \
-o custom-columns='NAME:.metadata.name,SERVICE_ACCOUNTS:.subjects[*].name' \
| grep -i dashboard
여기서 발견한 리소스를 모두 자동 삭제해서는 안 됩니다. 다른 도구가 함께 사용하는 권한인지 확인한 뒤 Dashboard 전용 리소스만 제거합니다.
Headlamp가 모든 상황의 정답은 아니다
Headlamp는 Kubernetes 공식 문서가 제안하는 자연스러운 대안이지만 모든 운영 요구를 해결하는 플랫폼은 아닙니다.
다음과 같은 경우에는 다른 도구와 함께 사용해야 합니다.
- 선언적 배포와 변경 이력: Argo CD, Flux
- 메트릭과 알림: Prometheus, Grafana
- 로그 검색: Loki, OpenSearch, Elasticsearch
- 비용 분석: OpenCost
- 보안 상태 관리: Trivy, Kubescape 등
- 개발자 셀프서비스 포털: Backstage
Headlamp는 Kubernetes API를 탐색하고 문제를 조사하는 UI에 가깝습니다. 모니터링, GitOps, 비용과 보안 도구를 대체한다고 생각하면 역할이 지나치게 커집니다.
전환 체크리스트
| 영역 | 확인 항목 |
| 프로젝트 상태 | Dashboard가 deprecated·보관 상태임을 운영 문서에 반영 |
| 설치 방식 | 데스크톱과 인클러스터 중 목적에 맞게 선택 |
| 인증 | 공유 토큰보다 개인 신원과 OIDC 우선 |
| RBAC | cluster-admin 기본 사용 금지, 최소 권한 검증 |
| 네트워크 | TLS, Ingress, NetworkPolicy와 외부 노출 점검 |
| 기능 | 로그, 이벤트, YAML, exec, CRD와 멀티 클러스터 시험 |
| 플러그인 | 출처, 권한, 업데이트와 공급망 위험 검토 |
| 제거 | Dashboard 전용 ServiceAccount와 Binding 정리 |
| 운영 | Headlamp 버전·이미지·Chart 업데이트 절차 수립 |
결론: UI 교체보다 접근 권한을 다시 설계할 기회다
Kubernetes Dashboard의 deprecated는 단순한 화면 교체 소식이 아닙니다. 유지보수되지 않는 관리 UI를 계속 클러스터 API에 연결할 것인지 판단해야 하는 운영 신호입니다.
Headlamp는 데스크톱과 인클러스터 실행, 멀티 클러스터, OIDC, 플러그인 확장성을 제공하며 Dashboard 이후의 Kubernetes UI로 적합한 방향을 보여줍니다.
다만 전환의 핵심은 Headlamp를 설치하는 명령이 아닙니다.
Dashboard에서 쓰던 cluster-admin 토큰을 그대로 Headlamp에 옮기는 것이 아니라, 사용자별 인증과 최소 권한 RBAC를 다시 설계해야 한다.
개별 운영자는 데스크톱 앱과 기존 kubeconfig로 작게 시작할 수 있습니다. 팀 공용 UI가 필요하면 인클러스터 배포와 OIDC를 검토합니다. 주요 기능과 권한을 병행 검증한 뒤 Dashboard 전용 ServiceAccount, RoleBinding과 외부 접근 경로까지 정리하면 전환을 마무리할 수 있습니다.
참고한 공식 자료
'클라우드 > 쿠버네티스' 카테고리의 다른 글
| 🐢 올릴 땐 즉각, 내릴 땐 머뭇거리는 오토스케일러 — HPA의 비대칭 철학 (0) | 2026.04.24 |
|---|---|
| Pod가 갑자기 사라진다고? 🚨 Kubernetes Graceful Shutdown 완전 정복 (1) | 2026.04.03 |
| 쿠버네티스는 왜 도커를 버렸나? — 배신인가, 진화인가 🐋 (0) | 2026.03.31 |
| 구글이 만든 세계 최강의 컨테이너 관리 시스템 — Borg에서 Kubernetes까지의 15년 여정 🚀 (0) | 2026.03.30 |
| 쿠버네티스에 DB를 올려도 될까? — 프로덕션 환경에서의 현명한 선택 🤔 (0) | 2026.03.28 |
