쿠버네티스 롤링 업데이트 시 502 에러를 차단하는 Graceful Shutdown과 파드 수명주기(Pod Lifecycle) 아키텍처

1. 롤링 배포 환경에서 발생하는 간헐적 502 Bad Gateway의 본질

쿠버네티스(Kubernetes) 환경에서 애플리케이션의 신규 버전을 롤링 업데이트(Rolling Update) 방식으로 배포할 때, 서비스 다운타임이 발생하지 않을 것이라는 기대와 달리 클라이언트에게 간헐적인 HTTP 502 Bad Gateway 또는 504 Gateway Timeout 오류가 반환되는 현상이 빈번하게 관측됩니다. 이러한 장애는 애플리케이션 코드 결함이 아니라, 쿠버네티스 컨트롤 플레인의 비동기적 엔드포인트 제거 절차와 컨테이너 런타임의 파드 종료 프로세스 간의 타이밍 불일치(Race Condition)에서 비롯됩니다.

컨테이너가 SIGTERM 시그널을 수신하고 즉시 종료되면, 인그레스 컨트롤러(NGINX Ingress, AWS ALB 등)와 kube-proxy의 iptables/IPVS 라우팅 테이블에서 해당 파드의 IP가 완전히 삭제되기 전까지 기존 엔드포인트로 신규 트래픽이 계속 유입됩니다. 이미 소켓이 닫힌 파드로 전달된 TCP SYN 패킷은 TCP RST 응답을 유발하며, 이는 즉시 인그레스 계층의 502 에러로 직결됩니다.

2. 쿠버네티스 파드 종료 수명주기(Pod Termination Lifecycle) 심층 분석

쿠버네티스 공식 파드 종료 수명주기 문서에 명시된 바와 같이, 사용자가 파드 삭제를 요청하거나 디플로이먼트가 축소될 때 쿠버네티스는 두 가지 독립적인 작업을 병렬(Parallel)로 실행합니다.

• 엔드포인트 제거 파이프라인: API 서버는 파드를 Terminating 상태로 표시하고, 엔드포인트 컨트롤러(EndpointSlice Controller)를 통해 서비스 대상 목록에서 파드 IP를 제거합니다. 이 정보는 모든 워커 노드의 kube-proxy 및 인그레스 컨트롤러로 전파되어 라우팅 룰이 갱신됩니다. 이 전파 과정에는 클러스터 규모에 따라 수 초의 네트워크 지연이 수반됩니다.
• 파드 삭제 파이프라인: Kubelet은 컨테이너에 정의된 preStop 훅(Hook)을 실행합니다. preStop 훅이 완료되거나 타임아웃되면, Kubelet은 메인 컨테이너 프로세스에 SIGTERM 시그널을 전송합니다. 이후 terminationGracePeriodSeconds(기본 30초) 동안 프로세스가 종료되지 않으면 SIGKILL 시그널을 강제 발송하여 파드를 파괴합니다.

따라서 preStop 훅 없이 SIGTERM에 반응하여 즉시 종료되는 파드는, 엔드포인트 제거 신호가 인그레스 및 프록시에 도달하기 전까지 무방비 상태로 잔여 트래픽을 수신하게 됩니다.

3. 무중단 달성을 위한 핵심 아키텍처 원칙 (PreStop Hook + Connection Draining)

진정한 무중단 배포를 실현하기 위해서는 다음 세 가지 계층적 방어 기제가 유기적으로 결합되어야 합니다.

• PreStop 지연 훅 설정: 쿠버네티스 수명주기 훅(Lifecycle Hooks)을 활용하여 preStop: exec: command: ['/bin/sh', '-c', 'sleep 15']를 선언합니다. 이 15초의 지연 시간 동안 엔드포인트 컨트롤러와 Ingress의 라우팅 테이블 갱신이 안전하게 완료되어 파드로의 신규 트래픽 유입이 100% 차단됩니다.
• 우아한 종료(Graceful Shutdown) 및 드레이닝: SIGTERM 시그널을 수신한 애플리케이션은 즉시 프로세스를 죽이지 않고, 이미 인입되어 처리 중인 인플라이트(In-flight) HTTP 요청들이 완료될 때까지 대기(Draining)해야 합니다. 신규 연결 요청에 대해서는 HTTP 응답 헤더에 Connection: close를 명시하여 연결 유지를 방지합니다.
• Readiness Probe 격리: 종료 시퀀스가 개시되는 즉시 /readyz 엔드포인트가 503 Service Unavailable을 반환하도록 설계하여, 쿠버네티스 서비스 로드밸런서가 해당 인스턴스를 헬스체크 실패로 간주하고 즉각 트래픽 격리 대상으로 분류하도록 지원합니다.

4. 실전 프로덕션 구현: FastAPI 기반 Graceful Shutdown 및 K8s 매니페스트

다음은 비동기 파이썬 웹 프레임워크 환경에서 SIGTERM 신호를 트랩하여 활성 요청을 안전하게 드레이닝하는 서버 구현체와, 이를 완벽히 지원하는 쿠버네티스 배포 매니페스트 구성입니다.

import os
import sys
import time
import signal
import logging
from typing import Dict, Any
from fastapi import FastAPI, Request, Response, status
import uvicorn

logging.basicConfig(
    level=logging.INFO,
    format='%(asctime)s [%(levelname)s] (%(name)s) %(message)s',
    datefmt='%Y-%m-%d %H:%M:%S'
)
logger = logging.getLogger('K8sGracefulShutdownHandler')

class GracefulServerState:
    def __init__(self):
        self.is_shutting_down = False
        self.active_requests = 0

state = GracefulServerState()
app = FastAPI(title='ZeroDowntimeMicroservice')

@app.middleware('http')
async def track_in_flight_requests(request: Request, call_next):
    if state.is_shutting_down:
        logger.warning(f'종료 진행 중 신규 인입 요청 감지 (Connection: close 반환): {request.url.path}')
        response = await call_next(request)
        response.headers['Connection'] = 'close'
        return response

    state.active_requests += 1
    try:
        response = await call_next(request)
        return response
    finally:
        state.active_requests -= 1

@app.get('/healthz')
async def liveness_probe():
    return {'status': 'healthy'}

@app.get('/readyz')
async def readiness_probe(response: Response):
    if state.is_shutting_down:
        logger.info('Readiness Probe 실패 반환: 서비스 트래픽 격리 요청')
        response.status_code = status.HTTP_503_SERVICE_UNAVAILABLE
        return {'status': 'terminating'}
    return {'status': 'ready'}

@app.get('/api/v1/workload')
async def process_workload():
    time.sleep(0.5)
    return {'result': 'success', 'timestamp': time.time()}

def initiate_graceful_shutdown(signum, frame):
    sig_name = signal.Signals(signum).name
    logger.info(f'종료 시그널 수신 ({sig_name}): 수명주기 종료 단계 진입')
    state.is_shutting_down = True

    wait_limit_sec = 30
    start_wait = time.perf_counter()
    while state.active_requests > 0:
        elapsed = time.perf_counter() - start_wait
        if elapsed > wait_limit_sec:
            logger.error(f'Graceful 대기 시간({wait_limit_sec}초) 초과: 강제 종료 진행')
            break
        logger.info(f'처리 중인 활성 요청 잔여({state.active_requests}건): 드레이닝 대기 중...')
        time.sleep(0.5)

    logger.info('모든 활성 인바운드 트래픽 드레이닝 완료. 프로세스 정상 종료 승인.')
    sys.exit(0)

signal.signal(signal.SIGTERM, initiate_graceful_shutdown)
signal.signal(signal.SIGINT, initiate_graceful_shutdown)

if __name__ == '__main__':
    logger.info('쿠버네티스 무중단 마이크로서비스 엔진 구동 (Port: 8080)')
    uvicorn.run(app, host='0.0.0.0', port=8080, access_log=False)

위 파이썬 서비스와 결합되는 쿠버네티스 디플로이먼트 매니페스트의 표준 명세는 다음과 같습니다.

apiVersion: apps/v1
kind: Deployment
metadata:
  name: zero-downtime-service
spec:
  replicas: 3
  strategy:
    type: RollingUpdate
    rollingUpdate:
      maxSurge: 25%
      maxUnavailable: 0
  template:
    spec:
      terminationGracePeriodSeconds: 45
      containers:
      - name: app
        image: zero-downtime-service:v1.0.0
        ports:
        - containerPort: 8080
        lifecycle:
          preStop:
            exec:
              command: ['/bin/sh', '-c', 'sleep 15']
        readinessProbe:
          httpGet:
            path: /readyz
            port: 8080
          initialDelaySeconds: 5
          periodSeconds: 2
        livenessProbe:
          httpGet:
            path: /healthz
            port: 8080
          initialDelaySeconds: 10
          periodSeconds: 5

5. 성능 검증 결과 및 운영 시 주의사항

아파치 제이미터(Apache JMeter)를 통해 초당 1,500건의 동시 HTTP 요청을 인가한 상태에서 롤링 업데이트를 수행한 벤치마크 결과는 다음과 같은 극명한 안정성 격차를 증명합니다.

프로덕션 클라우드 환경에서 본 아키텍처를 적용할 때는 다음 사항을 반드시 사전 검토해야 합니다.

• 타임아웃 계층의 역전 금지: terminationGracePeriodSeconds(45초)는 반드시 preStop sleep 시간(15초)과 애플리케이션의 최대 요청 처리 시간(예: 20초)의 합보다 커야 합니다. 유예 기간이 짧으면 Kubelet이 정상 드레이닝 도중 SIGKILL을 강제 발생시켜 장애로 이어집니다.
• NGINX Ingress Keep-Alive 튜닝: 클라이언트와 프록시 간의 HTTP Keep-Alive 연결이 장시간 유지될 경우, 파드가 종료 수명주기에 진입했음에도 동일한 TCP 연결을 통해 연속 요청이 인입될 수 있습니다. 인그레스 설정에서 keepalive_requests와 proxy_next_upstream 룰을 튜닝하여 비정상 파드로 전달된 요청이 정상 파드로 즉시 재시도(Retry)되도록 구성해야 합니다.
• maxUnavailable: 0 보장: 롤링 업데이트 전략 수립 시 가용 파드 수를 항상 100% 이상 유지할 수 있도록 maxUnavailable: 0과 적절한 maxSurge 비율을 지정하여 업데이트 중 클러스터 용량 부족으로 인한 병목을 차단해야 합니다.