📌 kubectl describe로 리소스 상태 추적하는 방법

📌 kubectl describe로 리소스 상태 추적하는 방법

쿠버네티스를 처음 사용하는 초보자라면 kubectl get 명령어는 익숙할 수 있지만, 리소스 내부의 상세 상태를 확인하고 원인을 추적할 때는 kubectl describe 명령어가 훨씬 강력합니다.

이 글에서는 kubectl describe 명령어로 어떤 정보를 얻을 수 있는지, 어떤 상황에서 어떻게 사용해야 하는지 자세히 설명합니다.

---

✅ kubectl describe란?

kubectl describe는 특정 Kubernetes 리소스(Pod, Deployment, Node 등)의 자세한 상태 정보를 보여주는 명령어입니다.
단순히 현재 상태만 보는 것이 아니라, 이벤트, 스케줄링 정보, 컨테이너 상태, 오류 로그 등을 포함합니다.

📄 기본 명령어 형식

kubectl describe [리소스 종류] [리소스 이름] -n [네임스페이스]

예시:

kubectl describe pod nginx-deploy-6f9d6bbf9b-zxzlp -n default

---

🔍 주요 리소스 별 사용 예시

• kubectl describe pod <이름>: 컨테이너 상태, 이벤트, 재시작 횟수 등
• kubectl describe deployment <이름>: 레플리카 상태, 업데이트 전략, PodTemplate
• kubectl describe node <노드이름>: CPU/메모리 자원, Pod 스케줄링 상태, kubelet 연결
• kubectl describe service <이름>: 클러스터 IP, 포트 정보, Endpoints

---

🧠 초보자가 봐야 할 핵심 항목

1️⃣ Events

자주 문제가 생기는 부분입니다. Pod가 왜 Pending인지, ImagePull에 실패했는지 등은 대부분 이벤트에 기록됩니다.

Events:
  Type    Reason     Age   From               Message
  ----    ------     ----  ----               -------
  Normal  Scheduled  1m    default-scheduler  Successfully assigned default/nginx to node01
  Normal  Pulled     1m    kubelet            Container image "nginx" already present
  Normal  Created    1m    kubelet            Created container nginx
  Normal  Started    1m    kubelet            Started container nginx

2️⃣ Conditions

Pod나 Node가 어떤 상태인지 보여줍니다. 예를 들어 Ready 상태가 False면 서비스 연결이 불가능할 수 있습니다.

Conditions:
  Type              Status
  Initialized       True
  Ready             True
  ContainersReady   True
  PodScheduled      True

3️⃣ Containers 상태

컨테이너 별로 실행 상태, 재시작 횟수, 오류 메시지 등을 확인할 수 있습니다.

Containers:
  nginx:
    Container ID:   docker://...
    Image:          nginx
    Image ID:       ...
    State:          Running
    Ready:          True
    Restart Count:  0

4️⃣ Node 리소스 정보

Node의 자원이 부족할 때 Pod이 Pending에 걸릴 수 있으므로, describe로 리소스를 확인해볼 수 있습니다.

kubectl describe node node01

Capacity:
  cpu:     4
  memory:  8Gi
Allocated resources:
  cpu:     3
  memory:  6Gi

---

🛠 실전: Pod 오류 추적 예제

kubectl describe pod my-app -n default

📌 출력 내용 중 아래와 같은 메시지가 보일 수 있습니다:

Warning  Failed     2m    kubelet  Failed to pull image "my-app:v2": image not found

이 경우 원인은 명확합니다: 이미지 이름이 잘못되었거나, 이미지가 registry에 없음.
즉, describe는 단순 상태뿐 아니라 원인 파악까지 가능한 디버깅 도구입니다.

---

✅ 정리

• kubectl describe는 리소스의 상세 상태 + 이벤트 로그까지 보여주는 핵심 디버깅 명령어
• 문제가 생겼을 때 가장 먼저 확인해야 하는 도구
• 특히 Events, Conditions, Container 상태 항목은 꼭 읽는 습관을 들이자