Kubernetes 트러블슈팅 완벽 가이드

Kubernetes 클러스터 운영 중 자주 발생하는 문제들의 진단과 해결 방법을 학습합니다. Pod 상태 확인부터 네트워크 디버깅까지 실전 트러블슈팅 기법을 다룹니다.

---

---

들어가며

이 글에서는 Kubernetes 트러블슈팅 완벽 가이드에 대해 상세히 알아보겠습니다. 총 12가지 주요 개념을 다루며, 각각의 개념에 대한 설명과 실제 코드 예제를 함께 제공합니다.

목차

1. Pod_상태_확인하기
2. Container_재시작_문제_해결
3. Pod_내부_디버깅
4. 리소스_부족_문제_진단
5. Service_네트워크_문제_해결
6. ImagePullBackOff_오류_해결
7. ConfigMap_Secret_변경_반영
8. PersistentVolume_마운트_문제
9. Node_상태_문제_진단
10. Deployment_롤아웃_문제_해결
11. 네트워크_정책_디버깅
12. 이벤트_모니터링으로_문제_추적

---

1. Pod 상태 확인하기

개요

Pod의 현재 상태와 이벤트를 확인하여 문제를 진단합니다. CrashLoopBackOff, ImagePullBackOff 등의 오류를 빠르게 파악할 수 있습니다.

코드 예제

# Pod 상태 확인
kubectl get pods -n my-namespace

# Pod 상세 정보 확인
kubectl describe pod my-pod -n my-namespace

# Pod 로그 확인
kubectl logs my-pod -n my-namespace --tail=50

설명

get pods로 전체 상태를 보고, describe로 이벤트와 상세 정보를 확인하며, logs로 애플리케이션 로그를 분석합니다.

---

2. Container 재시작 문제 해결

개요

Container가 계속 재시작되는 CrashLoopBackOff 문제를 진단합니다. 이전 컨테이너의 로그를 확인하여 원인을 찾을 수 있습니다.

코드 예제

# 이전 컨테이너 로그 확인
kubectl logs my-pod --previous

# 실시간 로그 스트리밍
kubectl logs -f my-pod

# 특정 컨테이너 로그 (multi-container pod)
kubectl logs my-pod -c container-name

설명

--previous 옵션으로 크래시된 컨테이너의 로그를 보고, -f로 실시간 모니터링하여 문제를 파악합니다.

---

3. Pod 내부 디버깅

개요

실행 중인 Pod 내부에 접속하여 직접 명령을 실행하고 문제를 진단합니다. 파일 시스템, 네트워크, 프로세스 상태를 확인할 수 있습니다.

코드 예제

# Pod 내부 쉘 접속
kubectl exec -it my-pod -- /bin/bash

# 단일 명령 실행
kubectl exec my-pod -- ls -la /app

# 특정 컨테이너 접속 (multi-container)
kubectl exec -it my-pod -c container-name -- sh

설명

exec 명령으로 Pod 내부에 접속하여 파일, 환경변수, 네트워크 연결 등을 직접 확인할 수 있습니다.

---

4. 리소스 부족 문제 진단

개요

CPU와 메모리 사용량을 확인하여 리소스 부족 문제를 진단합니다. OOMKilled 오류나 성능 저하의 원인을 찾을 수 있습니다.

코드 예제

# 노드 리소스 사용량 확인
kubectl top nodes

# Pod 리소스 사용량 확인
kubectl top pods -n my-namespace

# 리소스 제한 확인
kubectl describe pod my-pod | grep -A 5 "Limits"

설명

top 명령으로 실시간 리소스 사용량을 보고, describe로 설정된 리소스 제한과 비교하여 문제를 파악합니다.

---

5. Service 네트워크 문제 해결

개요

Service가 Pod에 제대로 연결되지 않는 문제를 진단합니다. Endpoint 확인과 네트워크 연결 테스트를 수행합니다.

코드 예제

# Service 정보 확인
kubectl get svc my-service

# Endpoint 확인 (Service가 연결된 Pod IP)
kubectl get endpoints my-service

# DNS 테스트용 임시 Pod 실행
kubectl run test --image=busybox -it --rm -- \
  nslookup my-service

설명

endpoints로 Service가 올바른 Pod에 연결되었는지 확인하고, 임시 Pod로 DNS와 네트워크 연결을 테스트합니다.

---

6. ImagePullBackOff 오류 해결

개요

컨테이너 이미지를 가져올 수 없는 문제를 해결합니다. 이미지 이름, 태그, 레지스트리 인증 문제를 확인합니다.

코드 예제

# 이벤트 상세 확인
kubectl describe pod my-pod | grep -A 10 "Events"

# Secret 목록 확인 (registry 인증)
kubectl get secrets

# Secret을 사용하도록 Pod 수정
kubectl patch serviceaccount default \
  -p '{"imagePullSecrets":[{"name":"my-registry"}]}'

설명

describe로 정확한 에러 메시지를 확인하고, Secret 설정을 점검하여 이미지 pull 권한 문제를 해결합니다.

---

7. ConfigMap Secret 변경 반영

개요

ConfigMap이나 Secret을 변경했지만 Pod에 반영되지 않는 문제를 해결합니다. Pod를 재시작하여 최신 설정을 적용합니다.

코드 예제

# ConfigMap 변경 확인
kubectl get configmap my-config -o yaml

# Deployment 재시작 (rolling restart)
kubectl rollout restart deployment my-deployment

# 재시작 상태 확인
kubectl rollout status deployment my-deployment

설명

ConfigMap 변경 후 rollout restart로 Pod를 순차적으로 재시작하여 새로운 설정을 안전하게 적용합니다.

---

8. PersistentVolume 마운트 문제

개요

볼륨 마운트 실패로 Pod가 시작되지 않는 문제를 진단합니다. PVC와 PV의 바인딩 상태를 확인합니다.

코드 예제

# PVC 상태 확인
kubectl get pvc -n my-namespace

# PV 상태 확인
kubectl get pv

# Pod의 볼륨 마운트 상태 확인
kubectl describe pod my-pod | grep -A 10 "Volumes"

설명

PVC가 Bound 상태인지 확인하고, describe로 마운트 실패 원인(권한, 경로, 스토리지 클래스)을 파악합니다.

---

9. Node 상태 문제 진단

개요

Node가 NotReady 상태이거나 문제가 있을 때 진단합니다. kubelet, 디스크, 네트워크 문제를 확인할 수 있습니다.

코드 예제

# 노드 상태 확인
kubectl get nodes

# 노드 상세 정보와 Conditions 확인
kubectl describe node my-node

# 특정 노드의 Pod 목록
kubectl get pods --all-namespaces \
  --field-selector spec.nodeName=my-node

설명

describe로 노드의 Conditions(DiskPressure, MemoryPressure, Ready)를 확인하고 문제가 있는 Pod를 찾습니다.

---

10. Deployment 롤아웃 문제 해결

개요

Deployment 업데이트가 멈추거나 실패하는 문제를 해결합니다. 롤아웃 히스토리를 확인하고 이전 버전으로 롤백할 수 있습니다.

코드 예제

# 롤아웃 상태 확인
kubectl rollout status deployment my-deployment

# 롤아웃 히스토리 확인
kubectl rollout history deployment my-deployment

# 이전 버전으로 롤백
kubectl rollout undo deployment my-deployment

설명

rollout status로 진행 상황을 보고, 문제가 있으면 undo로 안전하게 이전 버전으로 되돌립니다.

---

11. 네트워크 정책 디버깅

개요

Pod 간 통신이 차단되는 NetworkPolicy 문제를 진단합니다. 정책 규칙을 확인하고 연결 테스트를 수행합니다.

코드 예제

# NetworkPolicy 확인
kubectl get networkpolicy -n my-namespace

# 특정 정책 상세 확인
kubectl describe networkpolicy my-policy

# 연결 테스트 (다른 Pod로 curl)
kubectl exec my-pod -- curl -v \
  http://other-service:8080

설명

NetworkPolicy 규칙을 확인하고 exec로 실제 연결을 테스트하여 ingress/egress 규칙 문제를 찾습니다.

---

12. 이벤트 모니터링으로 문제 추적

개요

클러스터 전체 이벤트를 모니터링하여 문제 발생 시점과 원인을 추적합니다. 실시간으로 이벤트를 감시할 수 있습니다.

코드 예제

# 최근 이벤트 확인
kubectl get events --sort-by='.lastTimestamp'

# 특정 네임스페이스 이벤트
kubectl get events -n my-namespace

# 실시간 이벤트 모니터링
kubectl get events --watch

설명

events를 시간순으로 정렬하여 문제 발생 시점을 파악하고, --watch로 실시간 모니터링합니다. ``` 이 카드 뉴스는 Kubernetes 트러블슈팅의 핵심 기법들을 다루고 있습니다. 각 카드는 실제 운영 환경에서 자주 발생하는 문제들과 그 해결 방법을 kubectl 명령어를 통해 보여줍니다. Pod 상태 확인부터 네트워크 디버깅까지 체계적으로 구성했습니다.

---

마치며

이번 글에서는 Kubernetes 트러블슈팅 완벽 가이드에 대해 알아보았습니다. 총 12가지 개념을 다루었으며, 각각의 사용법과 예제를 살펴보았습니다.

관련 태그

#Kubernetes #Pod #Deployment #Service #Troubleshooting