Kubernetes Pod 재시작 시 에러 해결

Overview

Kubernetes 환경에서 Rolling Update나 장애 복구 등으로 인해 Pod가 재시작될 때, 애플리케이션이 아직 준비되지 않았거나 안전하게 종료되지 않아 다음과 같은 문제가 발생할 수 있다.

• 서비스 응답 지연 또는 실패
• readiness/liveness probe 실패로 인한 재시작 루프
• 사용자가 체감하는 간헐적인 오류

 

 

이 글에서는 실제 현업에서 자주 마주치는 이러한 이슈를 해결하기 위한 세 가지 방법을 소개한다. 핵심은 probe 설정 최적화와 lifecycle 훅의 적절한 활용, 그리고 종료 유예 시간 설정이다.

 

 

 

 

 

 

 

 

 

---

 

 

 

방법 1: Probe 설정 최적화

Pod가 시작되면 Kubernetes는 설정된 `readinessProbe` 에 따라 애플리케이션의 준비 상태를 판단한다. 설정이 너무 엄격하면 아직 초기화되지 않은 Pod가 실패로 간주되어 재시작되거나 트래픽을 수신하지 못하게 된다.

livenessProbe:
  failureThreshold: 3
  httpGet:
    path: /health_check
    port: 8889
    scheme: HTTP
  initialDelaySeconds: 30
  periodSeconds: 10
  timeoutSeconds: 2

readinessProbe:
  failureThreshold: 3
  httpGet:
    path: /health_check
    port: 8889
    scheme: HTTP
  initialDelaySeconds: 30
  periodSeconds: 10
  successThreshold: 2
  timeoutSeconds: 2

 

 

 

 

주요 전략

• `initialDelaySeconds`: 애플리케이션이 완전히 기동될 시간을 확보 (기존 1초 → 30초)
• `timeoutSeconds`: 네트워크 지연을 고려한 여유 (기존 1초 → 2초)
• `successThreshold`: 더 안정적인 상태에서만 Ready 판정 (기존 1 → 2)

 

 

 

 

방법 2: lifecycle 훅과 terminationGracePeriodSeconds 활용

Pod가 종료될 때 진행 중인 요청을 안전하게 마무리할 수 있도록 `preStop` 훅과 종료 유예 시간을 설정한다.

spec:
  terminationGracePeriodSeconds: 60  # 총 대기 시간
  containers:
    - name: app
      lifecycle:
        postStart:
          exec:
            command: ["/bin/sh", "-c", "sleep 5"]
        preStop:
          exec:
            command: ["/bin/sh", "-c", "curl -X POST http://localhost:8889/shutdown && sleep 30"]

 

 

 

이점

• 종료 전에 shutdown API 호출 → 새로운 요청 차단
• 기존 연결 처리 후 종료
• `terminationGracePeriodSeconds` 안에 graceful shutdown이 완료되도록 설계

 

 

 

 

방법 3: 실제 시작 시간 기반의 probe 조정

`initialDelaySeconds` 값은 감으로 설정하면 실패 가능성이 높다. 실제 애플리케이션의 기동 시간에 버퍼를 더해 설정하는 것이 안정적이다.

# Pod 상태 확인
kubectl get pod [pod-name] -o yaml | grep -A 5 "conditions:"

# 로그 기반 애플리케이션 시작 시간 파악
kubectl logs [pod-name]

# 수동으로 readiness 테스트
curl http://[pod-ip]:8889/health_check

 

 

 

기동에 10초가 걸린다면

readinessProbe:
  initialDelaySeconds: 15  # 실제 시간 + 여유 버퍼

 

 

 

 

 

방법 4: ReadinessGate를 통한 외부 시스템 동기화

ReadinessGate는 Pod의 Ready 상태를 외부 컨트롤러나 시스템이 제어할 수 있게 해주는 고급 기능이다. 일반 readinessProbe는 Pod 내부의 애플리케이션 상태만 확인하지만, ReadinessGate를 사용하면 외부 시스템의 준비 상태까지 고려할 수 있다.

 

 

사용 사례

ReadinessGate는 다음과 같은 상황에서 특히 유용하다.

• AWS ALB/NLB 타겟 그룹 등록 완료 대기: 로드밸런서에 실제로 등록되고 헬스체크를 통과할 때까지 트래픽 수신 지연
• Service Mesh 준비 완료 확인: Istio, Linkerd 등의 sidecar 컨테이너가 완전히 준비될 때까지 대기
• 외부 모니터링 시스템 연동: Prometheus, Datadog 등에 메트릭 전송이 가능한 상태가 될 때까지 대기
• 분산 캐시 워밍업: Redis, Memcached 등의 캐시 데이터 로딩이 완료될 때까지 대기
• 데이터베이스 연결 풀 초기화: DB 커넥션이 충분히 확보될 때까지 대기

 

 

동작 원리

ReadinessGate는 기존 readinessProbe와 함께 동작한다. Pod spec에 readinessGates를 정의하면, Pod는 다음 조건을 모두 만족해야만 Ready 상태가 된다.

첫째, 모든 컨테이너의 readinessProbe가 성공해야 한다. 둘째, 정의된 모든 readinessGate 조건이 True 상태여야 한다. 이 두 조건이 충족되면 Pod는 비로소 Service Endpoint에 등록되어 트래픽을 수신하기 시작한다.

 

 

설정 방법

Pod의 spec에 readinessGates 필드를 추가하고, conditionType으로 커스텀 조건을 정의한다. 예를 들어 "example.com/load-balancer-ready"와 "example.com/cache-warmed-up" 같은 조건을 설정할 수 있다. 이러한 조건은 외부 컨트롤러가 Kubernetes API를 통해 업데이트하며, 모든 조건이 True가 되어야 Pod가 Ready 상태로 전환된다.

 

 

실제 동작 흐름

1. Pod가 생성되고 컨테이너가 시작된다
2. readinessProbe가 성공하더라도 Pod는 아직 Ready 상태가 아니다
3. 외부 컨트롤러(예: AWS Load Balancer Controller)가 로드밸런서 등록을 확인한다
4. 등록이 완료되면 컨트롤러가 해당 readinessGate 조건을 True로 업데이트한다
5. 다른 외부 시스템(예: 캐시 워밍업 컨트롤러)도 각자의 조건을 True로 설정한다
6. 모든 readinessGate 조건이 True가 되면 Pod가 최종적으로 Ready 상태로 전환된다
7. 이제 Service Endpoint에 등록되어 실제 트래픽을 받기 시작한다

 

 

AWS Load Balancer Controller 예시

AWS 환경에서 가장 흔한 사용 사례는 ALB/NLB 등록 대기다. AWS Load Balancer Controller는 자동으로 "target-health.alb.ingress.k8s.aws/pod-readiness-gate" 조건을 관리한다. Pod가 타겟 그룹에 등록되고 헬스체크를 통과할 때까지 이 조건은 False로 유지되며, 등록이 완료되면 True로 변경된다. 이를 통해 로드밸런서가 실제로 트래픽을 라우팅할 준비가 된 후에만 Pod가 Ready 상태가 되도록 보장할 수 있다.

 

 

주의사항

ReadinessGate를 사용할 때는 몇 가지 주의할 점이 있다. 외부 컨트롤러가 제대로 동작하지 않으면 Pod가 영원히 Ready 상태가 되지 않을 수 있으므로, 컨트롤러의 안정성이 중요하다. 또한 ReadinessGate 조건 업데이트에 시간이 걸릴 수 있으므로, initialDelaySeconds를 충분히 여유있게 설정해야 한다. 디버깅 시에는 kubectl describe pod 명령으로 각 readinessGate 조건의 상태를 확인할 수 있다.

 

 

 

 

 

동작 순서 요약

 

1. Pod 생성
2. InitContainer 실행 (있다면)
3. initialDelaySeconds 동안 대기
4. readinessProbe 시작 및 성공
5. readinessGate 조건 확인 (설정된 경우)
6. 모든 조건 충족 시 → Pod Ready → ELB 등록 → 트래픽 수신 시작
7. 종료 시 preStop 훅 실행 → 요청 차단 → 종료 유예 시간 동안 graceful shutdown

 

 

 

 

 

 

 

 

---

 

 

 

 

 

 

마무리

Kubernetes에서의 안정적인 서비스 운영은 단순히 Pod가 뜨는 것만으로는 부족하다. 애플리케이션이 "언제부터 트래픽을 받아도 되는지", "종료 시 안전하게 마무리할 수 있는지", 그리고 "외부 시스템과의 동기화는 완료되었는지"에 대한 고려가 필요하다.

 

 

이번 글에서 소개한 readinessProbe, livenessProbe, lifecycle, terminationGracePeriodSeconds, 그리고 readinessGate 설정은 매우 기본적이지만 강력한 수단이다.

 

특히 readinessGate는 클라우드 네이티브 환경에서 로드밸런서, 서비스 메시 등 외부 인프라와의 통합을 고려할 때 필수적인 기능이다. 이를 통해 Rolling Update 중에도 사용자 체감 오류 없이 서비스 연속성을 유지할 수 있다.

 

 

 

 

 

 

 

---

Reference

• Kubernetes Probes 공식 문서
• Graceful shutdown in Kubernetes
• Best practices for probes