쿠버네티스 트러블슈팅 종합 가이드: Pod, Service, Network 문제 해결

쿠버네티스 트러블슈팅 종합 가이드: Pod, Service, Network 문제 해결

쿠버네티스 트러블슈팅 종합 가이드: Pod, Service, Network 문제 해결

쿠버네티스(Kubernetes)는 복잡한 시스템인 만큼, 운영 중에 다양한 문제가 발생할 수 있습니다. 이 글에서는 쿠버네티스 환경에서 흔히 발생하는 문제들을 진단하고 해결하는 방법을 단계별로 안내합니다. Pod, Service, Network 문제 해결에 필요한 실무 지식과 kubectl 명령어 사용법을 자세히 설명합니다.

목차

• 에러 현상
• 원인 분석
  • 1. 리소스 부족 (Resource Exhaustion)
  • 2. 네트워크 설정 오류 (Network Configuration Error)
  • 3. 애플리케이션 오류 (Application Error)
• 해결 방법
  • 1. 리소스 부족 문제 해결
  • 2. 네트워크 설정 오류 해결
  • 3. 애플리케이션 오류 해결
• 예방 조치
• FAQ

에러 현상

쿠버네티스 운영 중 다음과 같은 에러 또는 현상을 마주할 수 있습니다.

• Pod가 Pending 상태로 멈춰있거나, CrashLoopBackOff 상태로 계속 재시작되는 경우
• Service를 통해 애플리케이션에 접근할 수 없는 경우
• DNS resolution이 실패하는 경우
• 애플리케이션 간의 네트워크 연결이 실패하는 경우
• kubectl 명령어가 응답하지 않거나, 연결 오류가 발생하는 경우

다음은 흔히 발생하는 에러 메시지의 예시입니다.

Error from server (Timeout): the server could not find the requested resource (pods/mypod)

이 에러는 kubectl이 API 서버와 통신할 수 없거나, 요청한 리소스(이 경우, mypod)를 찾을 수 없을 때 발생합니다.

원인 분석

쿠버네티스 문제의 원인은 매우 다양하지만, 가장 흔한 원인들을 중심으로 분석해 보겠습니다.

1. 리소스 부족 (Resource Exhaustion)

Pod가 필요한 CPU나 메모리 자원이 부족하여 스케줄링에 실패하거나, 실행 중인 Pod가 OOMKilled (Out Of Memory Killed) 되는 경우가 있습니다. 이는 노드의 자원 부족, 또는 Pod의 리소스 요청(requests) 및 제한(limits) 설정이 부적절할 때 발생합니다.

2. 네트워크 설정 오류 (Network Configuration Error)

Service 설정 오류, 네트워크 정책 (NetworkPolicy) 설정 오류, DNS 설정 오류 등으로 인해 Pod 간 통신, 외부 서비스 접근 등에 문제가 발생할 수 있습니다. 또한, CoreDNS와 같은 클러스터 DNS 서비스의 장애도 네트워크 문제의 원인이 될 수 있습니다.

3. 애플리케이션 오류 (Application Error)

애플리케이션 자체의 버그, 설정 오류, 의존성 문제 등으로 인해 Pod가 정상적으로 실행되지 못할 수 있습니다. 이 경우, Pod 로그를 분석하여 오류의 원인을 파악해야 합니다.

해결 방법

각 원인별로 문제 해결 방법을 자세히 알아보겠습니다.

1. 리소스 부족 문제 해결

• 원인: Pod가 필요한 자원(CPU, 메모리)이 부족하거나, 노드에 가용 자원이 부족한 경우

• 해결 방법: kubectl 명령어를 사용하여 Pod의 리소스 요청(requests) 및 제한(limits) 설정을 확인하고, 필요에 따라 조정합니다. 또한, 노드의 자원 사용량을 모니터링하고, 부족한 경우 노드를 추가하거나, 불필요한 Pod를 제거합니다.

  1. Pod 리소스 설정 확인:

     bash kubectl describe pod <pod-name>

     Requests 및 Limits 섹션을 확인하여 적절한 값이 설정되었는지 확인합니다.
     2. 노드 자원 사용량 확인:

     bash kubectl top node

     CPU 및 메모리 사용량이 높은 노드를 확인합니다.
     3. 리소스 설정 변경 (예시):

     ```yaml

     pod.yaml

     apiVersion: v1
     kind: Pod
     metadata:
     name: resource-demo
     spec:
     containers:
     - name: main
     image: nginx:latest
     resources:
     requests:
     cpu: 100m
     memory: 256Mi
     limits:
     cpu: 500m
     memory: 512Mi
     ```

     bash kubectl apply -f pod.yaml

  2. 변경 후 확인:

     bash kubectl describe pod <pod-name>

     변경된 리소스 설정이 적용되었는지 확인합니다.

2. 네트워크 설정 오류 해결

• 원인: Service 설정 오류, 네트워크 정책 설정 오류, DNS 설정 오류 등

• 해결 방법: kubectl 명령어를 사용하여 Service 설정을 확인하고, Pod 선택자가 올바르게 설정되었는지 확인합니다. 네트워크 정책이 트래픽을 차단하고 있는지 확인하고, 필요한 경우 수정합니다. CoreDNS와 같은 클러스터 DNS 서비스가 정상적으로 실행 중인지 확인합니다.

  1. Service 설정 확인:

     bash kubectl describe service <service-name>

     Selector 필드가 Pod 레이블과 일치하는지 확인합니다.
     2. 네트워크 정책 확인:

     bash kubectl get networkpolicy kubectl describe networkpolicy <networkpolicy-name>

     Pod 간 통신을 차단하는 네트워크 정책이 있는지 확인합니다.
     3. CoreDNS 상태 확인:

     bash kubectl get pods -n kube-system | grep coredns kubectl logs -n kube-system <coredns-pod-name>

     CoreDNS Pod가 정상적으로 실행 중인지, 로그에 오류가 없는지 확인합니다.

  2. DNS 문제 해결 (예시: CoreDNS 재시작):

     bash kubectl delete pod -n kube-system <coredns-pod-name>

     CoreDNS Pod를 삭제하면 자동으로 재시작됩니다. (운영 환경에 미치는 영향을 고려하여 신중하게 진행)

  3. 변경 후 확인:

     bash kubectl exec -it <pod-name> -- nslookup <service-name>.<namespace>.svc.cluster.local

     Pod 내부에서 DNS resolution이 정상적으로 작동하는지 확인합니다.

3. 애플리케이션 오류 해결

• 원인: 애플리케이션 버그, 설정 오류, 의존성 문제 등

• 해결 방법: kubectl 명령어를 사용하여 Pod 로그를 확인하고, 애플리케이션 오류 메시지를 분석합니다. 필요한 경우, 애플리케이션 설정을 수정하거나, 코드를 수정하여 재배포합니다.

  1. Pod 로그 확인:

     bash kubectl logs <pod-name> kubectl logs -f <pod-name> # 실시간 로그 보기 kubectl logs <pod-name> --previous # 이전 컨테이너 로그 보기

     오류 메시지, 스택 트레이스 등을 확인합니다.
     2. Pod 내부 접속 및 디버깅:

     bash kubectl exec -it <pod-name> -- /bin/bash

     Pod 내부에 접속하여 애플리케이션 상태를 직접 확인하고, 필요한 경우 디버깅 도구를 실행합니다.

  2. 애플리케이션 재배포 (예시):

     bash kubectl rollout restart deployment <deployment-name>

     Deployment를 재시작하여 새로운 버전의 애플리케이션을 배포합니다.

  3. 변경 후 확인:

     bash kubectl get pods

     새로운 Pod가 정상적으로 실행 중인지 확인합니다.

예방 조치

• 리소스 모니터링: Prometheus, Grafana 등을 사용하여 클러스터의 리소스 사용량을 지속적으로 모니터링하고, 임계치를 초과하는 경우 알림을 설정합니다.

  ```yaml

  Prometheus 설정 예시

  apiVersion: monitoring.coreos.com/v1
  kind: PodMonitor
  metadata:
  name: pod-resource-monitor
  namespace: monitoring
  spec:
  selector:
  matchLabels:
  app: my-app
  podMetricsEndpoints:
  - port: metrics
  interval: 30s
  ```
  * 자동 스케일링: Horizontal Pod Autoscaler (HPA)를 사용하여 CPU 사용량에 따라 Pod 개수를 자동으로 조절합니다.

  ```yaml

  HPA 설정 예시

  apiVersion: autoscaling/v2beta2
  kind: HorizontalPodAutoscaler
  metadata:
  name: my-app-hpa
  namespace: default
  spec:
  scaleTargetRef:
  apiVersion: apps/v1
  kind: Deployment
  name: my-app-deployment
  minReplicas: 1
  maxReplicas: 10
  metrics:
  - type: Resource
  resource:
  name: cpu
  target:
  type: Utilization
  averageUtilization: 70
  ```
  * 로깅 및 모니터링: ELK 스택, Fluentd 등을 사용하여 애플리케이션 로그를 수집하고 분석합니다. 중앙 집중식 로깅 시스템을 구축하여 문제 발생 시 신속하게 원인을 파악할 수 있도록 합니다.
  * Health Check: Liveness Probe와 Readiness Probe를 적절히 설정하여 Pod의 상태를 주기적으로 확인하고, 비정상적인 Pod를 자동으로 재시작합니다.

FAQ

• Q: Pod가 ImagePullBackOff 상태로 계속 실패합니다. 어떻게 해야 하나요?

  A: ImagePullBackOff는 쿠버네티스가 컨테이너 이미지를 레지스트리에서 가져올 수 없을 때 발생합니다. 이미지 이름 또는 태그가 올바른지, 레지스트리에 접근할 수 있는지 확인해야 합니다. 또한, 쿠버네티스 클러스터가 private 레지스트리에 접근해야 하는 경우, 적절한 인증 정보(Secret)가 설정되어 있는지 확인해야 합니다. kubectl describe pod <pod-name> 명령어를 사용하여 자세한 오류 메시지를 확인하고, 필요한 설정을 수정해야 합니다.

• Q: kubectl 명령어를 사용할 때 "connection refused" 오류가 발생합니다. 어떻게 해결해야 하나요?

  A: "connection refused" 오류는 kubectl이 kube-apiserver에 연결할 수 없을 때 발생합니다. kube-apiserver가 실행 중인지, kubectl 설정 파일(~/.kube/config)이 올바르게 설정되어 있는지 확인해야 합니다. 또한, 방화벽 설정이 kube-apiserver로의 트래픽을 차단하고 있지 않은지 확인해야 합니다. kube-apiserver 파드가 정상적으로 실행 중인지 확인하고, 필요한 경우 재시작을 시도해볼 수 있습니다.

• Q: Service를 생성했지만, 외부에서 접근할 수 없습니다. 무엇을 확인해야 할까요?

  A: Service가 외부에서 접근 가능하도록 설정되었는지 확인해야 합니다. Service 타입이 LoadBalancer 또는 NodePort로 설정되어 있는지 확인하고, 클라우드 환경에서 LoadBalancer가 프로비저닝되었는지 확인합니다. 또한, 방화벽 또는 네트워크 정책이 외부 트래픽을 차단하고 있지 않은지 확인해야 합니다. kubectl describe service <service-name> 명령어를 사용하여 Service 설정을 확인하고, 필요한 설정을 수정해야 합니다.

---

관련 글

• 쿠버네티스 Pod CrashLoopBackOff 해결
• AADSTS50105 에러 해결: Azure AD 앱 할당 오류
• AADSTS700016 에러: 앱 등록 테넌트 불일치 해결
• AD FS SAML 연동 오류: Certificate 만료 해결법
• Azure AD Connect 동기화 오류 진단 가이드