쿠버네티스 대시보드란 — kubectl 없이 클러스터를 보는 화면

한 줄로

쿠버네티스 클러스터를 웹 화면으로 보고 조작하는 공식 관리 도구다.

kubectl 로 하던 일을 브라우저에서 클릭으로 한다.

무엇을 대신해주나

평소 클러스터 상태를 보려면 이렇게 친다.

kubectl get pods -n monitoring
kubectl describe pod grafana-abc123 -n monitoring
kubectl logs grafana-abc123 -n monitoring

대시보드는 이 셋을 한 화면에서 한다. 파드 목록이 표로 뜨고, 하나를 클릭하면 상세가 열리고,
탭을 누르면 로그가 나온다.

할 수 있는 일은 대체로 kubectl 과 겹친다.

하는 일	kubectl
리소스 목록·상세 보기	`get`, `describe`
로그 보기	`logs`
컨테이너 접속	`exec -it`
YAML 수정·적용	`edit`, `apply`
파드·디플로이먼트 삭제	`delete`
스케일 조정	`scale`

읽기 전용이 아니다. 지우고 고치는 것까지 된다. 이게 뒤에서 권한 이야기로 이어진다.

왜 쓰나 — 그리고 언제 안 쓰나

kubectl 이 있는데 굳이 화면이 필요한 이유가 있다.

첫째, 훑어보기에 강하다. 문제가 어디서 났는지 모를 때 kubectl 은 네임스페이스마다
명령을 다시 쳐야 한다. 대시보드는 전체 상태를 한눈에 보여주고, 비정상 리소스에 색이 붙는다.

둘째, 진입 장벽이 낮다. 클러스터를 매일 다루지 않는 사람에게 kubectl 명령을 외우게
하는 것보다 화면 하나를 주는 편이 낫다.

반대로 안 맞는 경우도 분명하다.

반복 작업 — 같은 일을 여러 번 하면 명령어가 빠르다. 스크립트로 묶을 수도 있다
기록이 필요할 때 — 클릭은 흔적이 안 남는다. kubectl 은 셸 히스토리에 남는다
여러 클러스터 비교 — 대시보드는 한 클러스터에 하나씩 붙는다

즉 사람이 눈으로 확인하는 용도에 맞고, 자동화나 감사 추적에는 안 맞는다.

구성요소는 둘이다

대시보드를 깔면 컨테이너가 두 개 뜬다.

컴포넌트	역할
`kubernetesui/dashboard`	웹 화면 본체. 쿠버 API 를 호출해 화면을 그린다
`kubernetesui/metrics-scraper`	CPU·메모리 사용량 수집

둘째가 헷갈리기 쉽다. 대시보드 본체는 “파드가 몇 개 있고 상태가 뭔지” 는 API 로 알 수 있지만,
“CPU 를 얼마나 쓰는지” 는 모른다. 그건 쿠버 API 가 기본으로 주는 정보가 아니다.

그래서 별도 컴포넌트가 지표를 긁어다 저장하고, 화면의 사용량 그래프는 그 값을 쓴다.

지표가 필요 없으면 이 컴포넌트 없이도 대시보드는 돈다. 그래프만 비어 보인다.

접근하려면 권한이 필요하다

대시보드를 열면 바로 클러스터가 보이는 게 아니다. 로그인을 해야 한다.

쿠버네티스에는 사람용 계정 개념이 따로 없다. 대신 서비스 계정(ServiceAccount)을 만들고,
거기에 권한을 붙인 뒤, 그 계정의 토큰으로 로그인한다.

kind: ServiceAccount
metadata:
  name: admin-user
---
kind: ClusterRoleBinding
metadata:
  name: admin-user
roleRef:
  kind: ClusterRole
  name: cluster-admin      # ← 클러스터 전체 관리자

세 조각이 필요하다.

ServiceAccount — 누구인가
ClusterRole — 무엇을 할 수 있는가 (cluster-admin 은 전부 가능)
ClusterRoleBinding — 둘을 잇는다

cluster-admin 은 그 클러스터에서 할 수 있는 모든 것을 뜻한다. 파드 삭제, 시크릿 읽기가
전부 포함된다.

편하지만 위험한 선택이다. 읽기만 하면 충분한 용도라면 view 라는 기본 역할로 낮출 수 있다.
그러면 화면에서 지우거나 고치는 게 막힌다.

HTTPS 로 뜬다는 점

대시보드는 자기 자신이 HTTPS 로 동작한다. 이게 앞에 프록시를 둘 때 걸린다.

nginx Ingress 를 앞에 두면 설정 네 줄이 필요하다.

nginx.ingress.kubernetes.io/backend-protocol: "HTTPS"
nginx.ingress.kubernetes.io/ssl-redirect: "false"
nginx.ingress.kubernetes.io/proxy-ssl-verify: "false"
nginx.ingress.kubernetes.io/rewrite-target: /$2

각각 다른 문제를 푼다.

설정	없으면
`backend-protocol: HTTPS`	nginx 가 HTTP 로 말을 걸어 연결이 깨진다
`ssl-redirect: false`	HTTP 접근이 HTTPS 로 튕겨 무한 리다이렉트
`proxy-ssl-verify: false`	자체 서명 인증서를 nginx 가 거부한다
`rewrite-target`	하위 경로로 붙일 때 접두어를 떼어준다

셋째가 핵심이다. 대시보드는 설치 시 자기가 만든 인증서를 쓴다. 공인 기관이 발급한 게
아니라서 검증하면 통과할 방법이 없다. 그래서 검증을 끈다.

경로 재작성이 필요한 이유는
Ingress 편에 적었다.

폐쇄망에서 깔 때

인터넷이 있으면 보통 이렇게 깐다.

kubectl apply -f https://raw.githubusercontent.com/kubernetes/dashboard/.../recommended.yaml

인터넷이 없으면 이 URL 을 못 쓴다. 그래서 YAML 파일을 미리 받아 서버에 두고 파일 경로로
적용한다.

이때 한 가지가 더 필요하다. 그 YAML 안의 이미지 주소는 공개 저장소를 가리키므로,
사설 레지스트리 주소로 바꿔야 한다.

kubernetesui/dashboard:  →  localhost:5001/kubernetesui/dashboard:

Helm 차트라면 --set 으로 값을 바꾸면 되지만, 생 YAML 은 그런 수단이 없어 텍스트를 직접
치환한다. 이 방식은 YAML 구조를 모르므로, 새 버전에서 표기가 조금만 달라지면 치환이 빗나간다.

사설 레지스트리를 왜 두는지는
registry:2 편에 있다.

우리 프로젝트에서 겪은 이슈 — 없다

이 글에서 가장 할 말이 없는 절이다. 그리고 그게 결론이다.

블록체인 플랫폼을 만들면서 클러스터에 얹은 부가 컴포넌트가 다섯인데, git 로그를 뒤져보니
대시보드만 사고 이력이 없다.

$ git log --oneline -- init/kind-cluster/scripts/06-install-kubernetes-dashboard.sh
d540ea2 chore: kind-cluster 및 fabric 스크립트 변경사항 반영
ced5ad7 feat: init/kind-cluster/ 생성 ...

두 건 다 일괄 정리 커밋이고, 대시보드 자체를 고친 게 아니다. 나머지 넷은 그렇지 않았다.

컴포넌트	겪은 일
Prometheus	무한 리다이렉트 — `routePrefix` 와 Ingress 경로 재작성 충돌
Grafana	로그인 루프, 라이브 대시보드 연결 끊김
Istio	기동 전에 Ingress 를 깔아 순서 문제
Ingress	이미지 누락, digest 방식 변경
대시보드	없음

왜 대시보드만 조용했나. 성격을 보면 설명이 된다.

첫째, 상태를 안 갖는다. Prometheus 는 지표를 쌓고 Grafana 는 대시보드를 저장한다.
저장하는 게 있으면 볼륨·권한·유실 문제가 따라온다. 대시보드는 쿠버 API 를 조회해 그릴 뿐이라
자기 데이터가 없다.

둘째, 다른 것에 안 붙는다. Grafana 는 Prometheus 를 데이터 소스로 물고, Prometheus 는
수집 대상을 물고, Istio 는 Ingress 와 순서가 얽힌다. 연결이 많을수록 깨질 지점이 많다.
대시보드는 쿠버 API 하나만 본다.

셋째, 단일 YAML 로 끝난다. Helm 차트는 값 덮어쓰기, 하위 차트, 훅 순서가 얽히는데,
대시보드는 매니페스트 하나를 적용하는 게 전부다.

정리하면 상태가 없고, 의존이 적고, 설치가 단순한 것은 잘 안 터진다. 당연한 말 같지만,
같은 클러스터에 나란히 깔린 다섯을 비교해보니 그 차이가 이력으로 그대로 드러났다.

대신 설치는 가장 정직하게 실패한다

사고가 없었던 것과 별개로, 설치 스크립트가 만들어진 방식은 눈여겨볼 만하다.

if [ ! -f "${DASHBOARD_YAML}" ]; then
  echo "❌ Dashboard YAML not found: ${DASHBOARD_YAML}"
  echo "Please ensure the file exists for offline installation."
  exit 1
fi

무엇이 없는지, 어디에 있어야 하는지까지 찍고 exit 1 로 끝낸다.

같은 클러스터의 다른 스크립트와 비교하면 차이가 뚜렷하다.

스크립트	파일이 없을 때
쿠버 대시보드	`exit 1` + 경로 안내
Prometheus 차트	`exit 1`
Grafana 대시보드 폴더	조용히 건너뜀
Istio 게이트웨이 설정	경고만

다만 이 정직함이 끝까지 가지는 않는다. 상위 스크립트가 이렇게 부른다.

bash "$SCRIPT_DIR/06-install-kubernetes-dashboard.sh" ... || {
  echo "⚠️ ... non-critical, continuing..."
}

exit 1 이 경고 한 줄로 강등된다. 스크립트는 표준적인 방법(종료 코드)으로 실패를 알렸는데
바깥에서 그 신호를 버리는 셈이다. 실패를 잘 알리는 것과, 그 신호를 받아 처리하는 것은
다른 문제다.

자체 로고가 없다

작은 사실 하나. 쿠버네티스 대시보드는 자기 로고가 없다. 쿠버네티스 로고를 그대로 쓴다.

프로젝트가 쿠버네티스 공식 하위 프로젝트라 별도 브랜딩을 두지 않은 것으로 보인다.
이 글의 썸네일도 쿠버네티스 심볼이다.

정리

클러스터를 웹으로 보고 조작하는 공식 관리 도구. kubectl 의 상당 부분을 화면으로 대체한다
읽기 전용이 아니다 — 삭제·수정·스케일 조정까지 된다
훑어보기와 비숙련자 접근에 강하고, 반복 작업·기록·다중 클러스터에는 안 맞는다
컨테이너가 둘 — 화면 본체와 metrics-scraper(사용량 수집). 후자가 없으면 그래프만 빈다
로그인은 ServiceAccount + ClusterRole + Binding 세 조각으로 만든 토큰을 쓴다.
cluster-admin 은 전권이라, 읽기만 필요하면 view 로 낮출 수 있다
자기가 HTTPS 로 뜬다. 앞에 프록시를 두면 프로토콜·리다이렉트·인증서 검증 설정이 필요하다
폐쇄망에서는 YAML 을 파일로 두고 이미지 주소를 치환해서 깐다
우리 프로젝트에서 부가 컴포넌트 5개 중 유일하게 사고 이력이 없다.
상태가 없고, 의존이 적고, 설치가 단순해서다
설치 실패는 exit 1 로 가장 정직하게 알리는데, 상위 스크립트가 경고로 강등한다

같이 읽을 글:
Ingress 로 포트 3개를 1개로 줄였다 ·
Prometheus 는 한 덩어리로 깔린다 ·
회사마다 클러스터 하나씩 띄운다