Headlamp 설치와 사용법: 로컬 쿠버네티스를 화면으로 보고 파드 배포하기
WSL2 안의 kind 클러스터를 Windows 앱에서 보고 파드까지 배포해 본 기록
로컬 쿠버네티스 실습 시리즈 목차 · 글 15개
- 1편Windows에서 무료 쿠버네티스 실습 환경 만들기: WSL2 + Docker Engine + kind
- 2편Headlamp 설치와 사용법: 로컬 쿠버네티스를 화면으로 보고 파드 배포하기
- 3편NGINX Ingress 대신 Gateway API: kind 클러스터 앱을 Windows localhost로 접속하기
- 4편kube-prometheus-stack 설치와 Grafana 접속: kind 클러스터 모니터링과 target down 해결
- 5편Fluent Bit과 Loki로 쿠버네티스 로그 모으기: kind 실습과 Grafana 조회, AWS 확장 예시
- 6편cert-manager로 Gateway API HTTPS 붙이기: 사설 CA, 자동 갱신, 만료 알림까지 kind 실습
- 7편Keycloak 운영 모드로 Grafana SSO 만들기: Keycloak Operator, CloudNativePG, 이중화와 장애·백업 훈련
- 8편OpenTelemetry로 쿠버네티스 트레이스 모으기: Collector, Tempo, 샘플링과 장애 훈련까지 kind 실습
- 9편Argo CD로 쿠버네티스 GitOps 전환하기: Helm 설치 넘겨받기, Sealed Secrets, Keycloak SSO와 장애 훈련까지 kind 실습
- 부록Argo CD로 nginx 파드 하나 배포하기: GitHub에서 파일 두 개 커밋하고 replicas 바꿔 보기
- 10편Trivy Operator로 쿠버네티스 취약점 점검하기: 이미지·설정·비밀값 스캔, Grafana 경보, Argo CD로 고치기까지 kind 실습
- 번외편Trivy로 찾은 컨테이너 이미지 취약점 고치기: nginx apk upgrade, Go 의존성 올리기, Grafana처럼 직접 못 고치는 경우까지
- 11편Istio Ambient 모드로 서비스 메시 붙이기: 사이드카 없이 mTLS, 권한 정책, waypoint 트래픽 분할과 장애 훈련까지 kind 실습
- 12편Strimzi로 쿠버네티스에 Kafka 올리기: KRaft 브로커 3대, SCRAM·ACL, 소비 지연 경보와 장애·업그레이드 훈련까지 kind 실습
- 13편Airflow를 쿠버네티스에 올리기: KubernetesExecutor, git-sync DAG 배포, 재시도·catchup부터 스케줄러 장애와 3.4 업그레이드까지 kind 실습
Headlamp는 쿠버네티스 클러스터를 화면으로 보고 관리하는 데스크톱 앱입니다. Windows에서는 winget으로 설치하고, 사용자 폴더의 .kube\config에 클러스터 접속 정보를 넣으면 별도 설정 없이 클러스터가 목록에 나옵니다. 보기 전용이 아니라 왼쪽 아래 ’+ 생성’ 버튼에 YAML을 붙여 넣고 ‘적용’을 누르면 Deployment를 바로 만들 수 있고, 실제로 만든 파드 2개가 Running이 되는 것까지 확인했습니다.
1편에서 WSL2 Ubuntu 24.04 안에 만든 kind 클러스터(kind-lab, 노드 3개)를 Windows 11에 설치한 Headlamp 0.46.0으로 연결한 결과입니다. 화면 이름은 Headlamp 한국어 화면 기준이며, 로그 보기·파드 터미널·삭제는 이 글에서 다루지 않습니다.
Headlamp란: Kubernetes Dashboard 대신 쓰는 GUI
Headlamp는 쿠버네티스 리소스를 목록과 상세 화면으로 보여 주는 오픈소스 GUI입니다. 데스크톱 앱으로 설치할 수도 있고 클러스터 안에 웹 앱으로 올릴 수도 있습니다. 이 글은 Windows 데스크톱 앱을 씁니다. Headlamp 저장소
쿠버네티스 GUI를 고를 때 예전에는 Kubernetes Dashboard나 Lens를 먼저 떠올렸습니다. 2026년 11월 기준 GitHub에서 확인하면 Kubernetes Dashboard 저장소는 kubernetes-retired 조직으로 옮겨져 보관(archived) 상태이고, Lens의 공개 저장소는 2025년 2월 이후 갱신이 없습니다. Headlamp는 쿠버네티스 공식 하위 프로젝트 조직(kubernetes-sigs)에서 개발되고 있어 새로 시작한다면 먼저 검토할 만합니다.
쿠버네티스 클러스터를 보는 방법 비교
| 방법 | 형태 | 이런 경우에 맞음 |
|---|---|---|
| kubectl | 명령어 | 모든 작업의 기본. 자동화와 스크립트 |
| k9s | 터미널 대시보드 | 터미널에서 키보드로 빠르게 둘러볼 때 |
| Headlamp | 데스크톱·웹 앱 | 구조를 화면으로 익히거나 클릭으로 확인할 때 |
| VS Code Kubernetes 확장 | 편집기 사이드바 | YAML을 편집하면서 클러스터를 같이 볼 때 |
Windows에 Headlamp 설치(winget)
Windows 11에는 패키지 관리자 winget이 기본으로 들어 있습니다. 먼저 패키지 이름을 확인하고 설치합니다.
winget search --id Headlamp --source wingetwinget install --id Headlamp.Headlamp -e --source winget실제로 설치된 버전은 0.46.0이었고, 설치 파일은 Headlamp의 GitHub 릴리스에서 내려받았습니다. winget이 설치 파일 해시를 확인한 뒤 설치합니다.
찾음 Headlamp [Headlamp.Headlamp] 버전 0.46.0다운로드 중 https://github.com/kubernetes-sigs/headlamp/releases/download/v0.46.0/Headlamp-0.46.0-win-x64.exe설치 관리자 해시를 확인했습니다.설치 성공설치가 끝나면 시작 메뉴에서 Headlamp를 실행할 수 있습니다.
WSL2 kind 클러스터를 Headlamp에 연결하기
Headlamp는 Windows 사용자 폴더의 .kube\config 파일을 읽어 클러스터 목록을 만듭니다. kind 클러스터의 접속 정보는 WSL 안에 있으므로 kind get kubeconfig로 꺼내 Windows 쪽에 저장합니다. 이미 .kube\config가 있다면 덮어쓰지 말고 백업부터 합니다.
New-Item -ItemType Directory -Force "$env:USERPROFILE\.kube" | Out-Null$cfg = (wsl -d Ubuntu-24.04 -u root -- kind get kubeconfig --name lab) -join "`n"[IO.File]::WriteAllText("$env:USERPROFILE\.kube\config", $cfg + "`n")[IO.File]::WriteAllText를 쓴 이유는 Windows PowerShell 5.1의 > 리디렉션이 UTF-16으로 저장하기 때문입니다. 저장된 파일의 server 값은 https://127.0.0.1:포트였습니다. kind는 API 서버를 WSL 안의 127.0.0.1에 열어 두는데, WSL2는 이 주소를 Windows에서도 그대로 쓸 수 있게 해 줍니다. Headlamp를 열기 전에 Windows에서 실제로 닿는지 확인할 수 있습니다.
PS> curl.exe -sk -o NUL -w "livez HTTP %{http_code}" https://127.0.0.1:포트/livezlivez HTTP 200200이 나오면 Headlamp를 엽니다. 실습 PC에서는 클러스터 추가 설정 없이 첫 화면에 kind-lab이 바로 나왔습니다. 클러스터 상세 화면에는 Kubeconfig: 항목에 파일 경로가 표시되는데, 경로에 Windows 계정명이 들어가므로 화면을 캡처해 공유할 때는 가립니다.

화면 둘러보기: 노드·파드는 어디서 보나
kind-lab에 들어가면 왼쪽 메뉴가 쿠버네티스 리소스 종류별로 나뉘어 있습니다. 한국어 화면에서 본 메뉴는 아래와 같습니다.
Headlamp 왼쪽 메뉴(한국어 화면)
| 메뉴 | 볼 수 있는 것 |
|---|---|
| Clusters | 연결된 클러스터 목록과 노드 |
| 맵 | 리소스 사이의 연결 관계 |
| 워크로드 | 파드, 디플로이먼트, 스테이트풀 셋, 데몬셋, 레플리카 셋, 잡, 크론잡 등 |
| 스토리지 / 네트워크 | 볼륨, 서비스 등 |
| 게이트웨이(베타) | Gateway API 리소스(다음 편부터 사용) |
| 보안 / 구성 | 서비스 어카운트·역할, ConfigMap·Secret 등 |
| 커스텀 리소스 | CRD로 추가한 리소스 |
파드 목록은 워크로드 → 파드에서 봅니다. 시스템 파드까지 보려면 위쪽 네임스페이스 선택을 모든 네임스페이스로 바꿉니다. 1편에서 만든 클러스터라면 kube-system의 CoreDNS, kindnet, kube-proxy와 local-path-storage의 프로비저너까지 파드 13개가 Running으로 보입니다.
’+ 생성’ 버튼으로 파드 배포하기
Headlamp는 보기 전용이 아닙니다. 왼쪽 아래 + 생성 버튼을 누르면 ‘생성 / 적용’ 편집 창이 열립니다. 창에는 에디터·Form·문서·Review Changes 탭과 Upload File/URL 버튼이 있고, 아래쪽에 닫기·Dry Run·적용 버튼이 있습니다. 에디터 탭에 아래 YAML을 붙여 넣었습니다.

apiVersion: apps/v1kind: Deploymentmetadata: name: web namespace: defaultspec: replicas: 2 selector: matchLabels: app: web template: metadata: labels: app: web spec: containers: - name: nginx image: nginx:alpine ports: - containerPort: 80nginx 컨테이너 하나를 가진 파드를 2개 유지하라는 Deployment입니다. selector.matchLabels와 template.metadata.labels의 app: web이 같아야 Deployment가 자기 파드를 찾습니다. 적용을 누른 뒤 WSL 셸에서 kubectl로 결과를 확인했습니다.
$ kubectl get deploy webNAME READY UP-TO-DATE AVAILABLE AGEweb 2/2 2 2 20s$ kubectl get pods -l app=web -o custom-columns=NAME:.metadata.name,STATUS:.status.phase,NODE:.spec.nodeNameNAME STATUS NODEweb-75d8d959fb-5gdxz Running lab-workerweb-75d8d959fb-k5682 Running lab-worker2
Headlamp가 만든 리소스라는 기록도 클러스터에 남습니다. Deployment의 metadata.managedFields를 보면 이 리소스를 바꾼 주체가 Headlamp 0.46.0 (windows ...)로, 그다음이 kube-controller-manager로 적혀 있습니다. Headlamp가 kubectl처럼 API 서버에 직접 요청을 보낸다는 뜻이므로, Headlamp에서 한 작업도 kubectl로 한 작업과 똑같이 클러스터에 반영됩니다.
Dry Run 먼저
적용 옆의 Dry Run은 실제로 만들지 않고 API 서버가 요청을 받아들이는지만 확인하는 버튼입니다. YAML을 처음 써 볼 때는 Dry Run으로 오류가 없는지 본 뒤 적용하면 안전합니다.
클러스터가 Unavailable로 나올 때
한동안 쓰지 않다가 Headlamp를 보니 kind-lab 아래에 Unavailable이 표시됐습니다. Windows에서 /livez를 다시 호출하자 응답이 없었고(HTTP 000), wsl -l -v로 보니 Ubuntu-24.04가 Stopped였습니다. 열린 WSL 셸이나 실행 중인 명령이 없으면 WSL이 스스로 꺼지고, 그 안의 Docker와 kind 노드도 함께 멈춥니다.
PS> wsl -l -v NAME STATE VERSION* Ubuntu-24.04 Stopped 2PS> wsl -d Ubuntu-24.04 -u rootWSL을 다시 켜는 것만으로 해결됐습니다. 켜자마자 Docker가 시작되고 kind 노드 컨테이너 3개가 자동으로 다시 떴습니다. 다만 켜진 직후 몇십 초 동안은 kubectl get nodes가 Forbidden 오류를 냈고, 잠시 뒤 다시 실행하자 노드 3개가 모두 Ready였습니다. Headlamp를 쓰는 동안 Windows 터미널에 Ubuntu 탭을 하나 열어 두면 이 문제를 피할 수 있습니다.
이렇게 WSL이 꺼졌다 켜지는 일이 반복되면 Headlamp 파드 목록의 ‘재시작’ 열에 숫자가 쌓입니다. 실습 PC에서는 약 30분 사이에 kindnet·kube-proxy·CoreDNS 같은 시스템 파드가 9회, local-path-provisioner가 12회로 표시됐습니다. kubectl로 직전 종료 이유를 보면 대부분 Unknown, 종료 코드 255였는데, 컨테이너가 스스로 죽은 것이 아니라 WSL과 함께 갑자기 멈췄다는 뜻입니다. local-path-provisioner는 API 서버가 준비되기 전에 먼저 떠서 Error(종료 코드 1)로 몇 번 더 재시작했습니다. 모두 Running으로 돌아왔다면 이 환경에서는 걱정하지 않아도 되는 숫자입니다.
kubectl get pods -A -o custom-columns='NAME:.metadata.name,RESTARTS:.status.containerStatuses[0].restartCount,REASON:.status.containerStatuses[0].lastState.terminated.reason,EXIT:.status.containerStatuses[0].lastState.terminated.exitCode'자주 묻는 질문
Headlamp는 보기 전용인가요?
아닙니다. 이 글처럼 YAML로 리소스를 만들 수 있고, Headlamp 저장소의 README는 생성·수정·삭제, 로그, 터미널 접속을 기능으로 소개합니다. 버튼은 접속한 사용자의 권한에 맞춰 보이므로, kind 기본 kubeconfig처럼 관리자 권한이면 모든 작업 버튼이 나옵니다.
kind 클러스터를 다시 만들면 Headlamp 설정도 바꿔야 하나요?
kind는 클러스터를 만들 때마다 API 서버 포트를 새로 정합니다. 클러스터를 지우고 다시 만들었다면 kind get kubeconfig로 Windows의 .kube\config를 다시 저장해야 합니다.
작성 방식과 다음 편
이 글의 명령과 출력, 화면 이름은 1편의 실습 PC에서 직접 확인한 결과이며, 파드 배포는 Headlamp 화면에서 직접 적용했습니다. 실행 기록 정리와 글 작성에 AI 도구를 함께 사용했습니다. 다음 편에서는 이 클러스터에 Gateway API를 올려 Windows 브라우저에서 localhost:8080으로 web 파드에 접속합니다.