🚀 쿠버네티스 네트워크의 핵심, Cilium CLI 주요 명령어 완벽 가이드

안녕하세요! 오늘은 쿠버네티스 환경에서 가장 강력한 CNI(Container Network Interface)인 Cilium을 마스터하기 위한 필수 도구, Cilium CLI를 총정리해 보겠습니다.

Cilium을 운영하다 보면 단순히 "설치"를 넘어, 왜 통신이 안 되는지 트러블슈팅(Troubleshooting)하고 심층 분석(Deep Dive)해야 할 때가 반드시 옵니다.

설치부터 패킷 단위의 디버깅까지, 실무에서 바로 쓸 수 있는 핵심 명령어를 상세히 정리해 드립니다. 📝

 

---

1️⃣ 설치 및 수명주기 관리 (Installation & Lifecycle)

가장 기본이 되는 설치, 버전 확인, 삭제 관련 명령어입니다.

ℹ️ cilium version

Cilium CLI 클라이언트 버전과 현재 클러스터에서 실행 중인 Cilium 이미지 버전을 확인합니다.

• 활용: 트러블슈팅 시 클라이언트와 서버(에이전트) 간의 버전 호환성을 확인할 때 가장 먼저 수행합니다.

📦 cilium install

클러스터에 Cilium을 설치합니다. 클라우드 환경(EKS, GKE 등)을 자동 감지하여 최적의 구성을 적용합니다.

• Tip: --set 플래그로 Helm Value를 직접 주입할 수 있습니다. (예: cilium install --set ipam.mode=kubernetes)

🗑️ cilium uninstall

Cilium과 관련된 모든 리소스(ConfigMap, ServiceAccount, DaemonSet 등)를 클러스터에서 깨끗하게 제거합니다.

• 주의: CNI가 삭제되면 파드 간 통신이 끊어지므로 운영 환경에서는 주의해야 합니다.

---

2️⃣ 상태 진단 및 로그 확인 (Status & Logs)

"지금 내 네트워크가 정상인가?"를 판단하는 단계입니다.

🩺 cilium status

Cilium 에이전트, 오퍼레이터, CNI 상태를 한눈에 보여줍니다.

• Tip: --wait 옵션을 사용하면 모든 컴포넌트가 Running 상태가 될 때까지 대기합니다.

🧪 cilium connectivity test

네트워크 연결성을 검증하는 골든 패스(Golden Path) 테스트입니다. 파드 간 통신, DNS, 외부 연결 등을 시나리오별로 자동 테스트합니다.

📜 kubectl logs -n kube-system

Cilium CLI가 작동하지 않거나 cilium status조차 실패할 때 사용하는 최후의 보루입니다.

• 설명: 쿠버네티스 표준 명령어로 Cilium 에이전트(파드)의 표준 출력 로그를 확인합니다.
• 활용: 에이전트가 왜 죽었는지(CrashLoopBackOff), 초기화 단계에서 어떤 치명적 오류(Fatal Error)가 있었는지 원시 로그를 볼 때 사용합니다.

---

3️⃣ 엔드포인트 및 정책 분석 (Endpoint & Policy)

Cilium은 파드(Pod)를 Endpoint라는 단위로 관리합니다. 방화벽 정책(Network Policy)이 제대로 먹히고 있는지 확인하려면 이곳을 봐야 합니다.

(※ 아래 명령어들은 주로 Cilium 파드 내부에서 실행하거나 CLI 래퍼를 통해 확인합니다.)

📋 cilium endpoint list

현재 노드에서 관리 중인 모든 엔드포인트의 요약 정보를 봅니다.

• 핵심 체크 포인트:
  • POLICY (Ingress/Egress): Enabled 상태여야 방화벽 정책이 작동 중인 것입니다. Disabled라면 정책이 적용되지 않은 상태(Allow-all)입니다.
  • IDENTITY: Cilium은 IP가 아닌 이 ID로 보안 통신을 수행합니다.

🔍 cilium endpoint get

특정 엔드포인트(ID)의 모든 세부 정보를 JSON 형태로 봅니다.

• 활용: "정책은 켜져 있는데(Enabled) 왜 통신이 안 되지?" 싶을 때 사용합니다. 해당 엔드포인트에 적용된 구체적인 라벨(Labels)과 정책 규칙(Policy Rules)을 낱낱이 파헤칠 수 있습니다.

---

4️⃣ 심층 디버깅 및 관측 (Deep Dive & Observability)

네트워크 엔지니어의 영역입니다. 패킷 흐름과 eBPF 상태를 직접 들여다봅니다.

📡 cilium monitor

Cilium 디버깅의 끝판왕입니다. eBPF 데이터 경로를 흐르는 패킷의 이벤트를 실시간으로 스트리밍합니다.

• 활용: tcpdump와 비슷하지만, eBPF 레벨에서 패킷이 Drop(차단)되는지, Forward(전송)되는지 명확한 이유와 함께 보여줍니다.
• Tip: cilium monitor --type drop 명령을 쓰면 차단된 패킷만 골라볼 수 있어 방화벽 디버깅에 최고입니다.

🧠 cilium bpf status

eBPF 맵(Map)의 상태와 리소스 사용량을 확인합니다.

• 활용: 대규모 클러스터에서 "더 이상 연결을 맺을 수 없다"는 에러가 날 때, eBPF Map의 용량(Capacity)이 가득 찼는지 확인할 때 사용합니다.

🔭 cilium hubble ui

cilium monitor가 텍스트 기반이라면, Hubble은 이를 시각화하여 서비스 간의 관계도(Service Map)를 그려줍니다. 브라우저를 통해 직관적으로 트래픽 흐름을 볼 수 있습니다.

---

📝 요약: 상황별 명령어 치트시트

상황	추천 명령어
설치 및 버전 확인	cilium install, cilium version
전체 건강 상태 체크	cilium status --wait
에이전트가 죽었을 때	kubectl logs -n kube-system
정책 적용 여부 확인	cilium endpoint list
특정 파드 상세 분석	cilium endpoint get
패킷 차단 원인 추적	cilium monitor --type drop
리소스 초기화	cilium uninstall

---

Cilium은 강력한 기능을 제공하는 만큼 익혀야 할 명령어도 많습니다. 하지만 위에서 정리해 드린 Lifecycle -> Status -> Endpoint -> Monitor 흐름만 기억하신다면, 어떤 네트워크 이슈가 발생해도 당황하지 않고 해결하실 수 있을 것입니다! 👍

여러분의 쿠버네티스 네트워크가 언제나 쾌적하길 바랍니다! 🚀