[Cilium] 🔭 쿠버네티스 네트워크의 '눈', Hubble CLI 명령어 완벽 가이드

쿠버네티스 환경에서 네트워크 트러블슈팅, 얼마나 힘드셨나요?

 

기존의 tcpdump는 파드 IP가 수시로 바뀌는 환경에서 추적하기가 매우 까다롭습니다. 하지만 Cilium을 CNI로 사용하고 있다면, 우리에겐 Hubble이라는 강력한 도구가 있습니다.

 

Hubble은 쿠버네티스 리소스(Pod, Service, Namespace)를 기반으로 네트워크 흐름을 직관적으로 보여주는 Observability(관측 가능성) 도구입니다. 오늘은 실무에서 바로 사용할 수 있는 Hubble CLI의 주요 명령어와 활용 팁을 상세하게 정리해 드립니다. 🚀

---

1. 실시간 네트워크 흐름 관측: hubble observe 📡

Hubble의 가장 핵심적인 기능입니다. 현재 클러스터에서 발생하는 패킷의 흐름(Flow)을 실시간으로 조회합니다. IP 주소가 아닌, 서비스 이름이나 파드 이름으로 통신을 추적할 수 있다는 점이 가장 큰 장점입니다.

📍 기본 사용법

아무런 옵션 없이 실행하면 현재 시점의 모든 네임스페이스 트래픽을 조회합니다.

hubble observe

📍 실시간 모니터링 (Follow 모드)

로그를 tail -f로 보는 것처럼, 네트워크 트래픽을 실시간으로 계속 보고 싶다면 -f 옵션을 사용하세요.

hubble observe -f

📍 필수 필터링 옵션 (Best Practice)

수만 개의 패킷 홍수 속에서 내가 원하는 정보만 쏙쏙 뽑아내는 방법입니다.

• 특정 파드와 네임스페이스 지정
  • 특정 네임스페이스(-n)의 특정 파드(--pod)와 관련된 트래픽만 봅니다.
  • hubble observe --pod my-web-server -n default
• 보안 감사: 차단된 트래픽만 보기 (--verdict) 🔥
  • 네트워크 정책(NetworkPolicy)에 의해 차단된 패킷만 골라낼 때 매우 유용합니다. 보안 담당자라면 필수 명령어입니다!

hubble observe --verdict DROPPED # 방화벽에 막힌 패킷만 조회
hubble observe --verdict FORWARDED # 정상 허용된 패킷만 조회

• 상대방(Source/Destination) 기준 필터링
  • "누가 kube-system으로 접속을 시도하는가?"를 찾을 때 사용합니다.

hubble observe --to-namespace kube-system # 목적지가 kube-system인 경우 
hubble observe --from-pod landing-page # 출발지가 landing-page 파드인 경우

• 프로토콜 및 포트 필터링: hubble observe --protocol tcp --port 80

📍 출력 형식 변경 (-o)

자동화 스크립트를 짜거나 더 상세한 정보를 봐야 할 때 포맷을 변경할 수 있습니다.

hubble observe -o compact # (기본값) 보기 편한 요약 정보
hubble observe -o json    # 모든 메타데이터를 포함한 JSON 출력 (상세 분석용)

---

2. 상태 및 연결 확인: hubble status 🏥

Hubble 서버(Relay)와 에이전트들이 정상적으로 동작하고 있는지 확인합니다.

hubble status

출력 예시 해석:

• Health: Hubble Relay와의 연결 상태
• Peer Service: 클러스터 내 다른 노드들과의 연결 상태
• Flows/s: 현재 수집 중인 초당 패킷 흐름 수 (부하 확인용)

---

3. 리소스 및 식별자 조회: hubble list 🆔

Cilium은 내부적으로 IP가 아닌 Identity(숫자 ID)로 보안 정책을 관리합니다. 이 ID가 어떤 파드나 라벨에 매핑되어 있는지 확인할 때 사용합니다.

• Identity 조회: hubble list identities
  어떤 라벨들이 어떤 숫자 ID로 매핑되었는지 확인합니다.

• Endpoint 조회: hubble list endpoints
  현재 모니터링 대상이 되는 파드(Endpoint)들의 리스트와 상태를 확인합니다.

---

4. 시각화 대시보드: hubble ui 🖥️

CLI가 익숙하지 않거나, 전체적인 서비스 간의 토폴로지 맵(Service Map)을 보고 싶을 때 웹 UI를 실행합니다.
이 명령어를 실행하면 로컬 호스트의 포트로 포워딩되어 웹 브라우저에서 서비스 간 연결 관계를 그래프로 볼 수 있습니다. (MSA 구조 파악에 매우 좋습니다!)

hubble ui

---

💡 전문가를 위한 트러블슈팅 시나리오 (Tips)

실무에서 자주 겪는 문제 상황을 Hubble로 해결하는 방법입니다.

✅ 상황 1: "갑자기 서비스 연결이 안 돼요!" (네트워크 정책 디버깅)

가장 흔한 경우입니다. 최근 5초 동안 차단된(DROPPED) 패킷이 있는지 확인해 봅니다.

hubble observe --verdict DROPPED --last 5s

Tip: 결과에 Policy denied라고 나온다면 NetworkPolicy가 트래픽을 막고 있는 것입니다.

✅ 상황 2: "HTTP 500 에러가 나는데, 어떤 경로에서 나나요?" (L7 가시성)

Cilium의 L7 가시성 기능을 켰다면, 단순 TCP 연결뿐만 아니라 HTTP Method와 Path까지 볼 수 있습니다.

hubble observe --protocol http --port 80 -f

출력 결과에서 GET /api/v1/users => 500 같은 로그를 즉시 확인할 수 있습니다.

✅ 상황 3: "차단된 구체적인 이유를 알고 싶어요" (JSON + jq 활용)

단순히 목록만 보는 게 아니라, 구체적인 Drop 사유(Reason)를 파싱 해서 봅니다.

hubble observe --verdict DROPPED -o json | jq '.flow.drop_reason_desc'

---

📝 마무리

Hubble은 쿠버네티스 네트워크의 블랙박스를 투명하게 만들어주는 강력한 도구입니다. 단순히 연결 확인을 넘어 보안 감사, 애플리케이션 디버깅, 구조 파악까지 가능하니, 위 명령어들을 꼭 익혀두시고 실무에 적용해 보세요! 👍

도움이 되셨다면 공감 부탁드립니다! 궁금한 점은 댓글로 남겨주세요.

---