Kubernetes 상태 검사: liveness, readiness, startup 프로브

Kubernetes 프로브의 엔드포인트와 판정 주기를 정하고, Pod 이벤트와 종료 상태를 함께 확인해 재시작 원인을 좁힙니다.

모범 사례
연결된 클러스터와 워크로드를 보여 주는 일러스트

결제 서비스를 롤아웃하면 새 Pod의 프로세스가 실행 중이어도 캐시 준비는 아직 끝나지 않았을 수 있습니다. 이때 요청을 보내면 오류가 생길 수 있고, 컨테이너를 재시작하면 진행 중인 준비를 처음부터 다시 해야 합니다. Kubernetes 상태 검사는 두 판단을 서로 다른 프로브에 맡깁니다.

readiness는 요청을 처리할 수 있는지 확인하고, liveness는 재시작으로 복구할 수 있는 장애를 감지합니다. startup은 기동이 느린 컨테이너에 별도의 시간을 줍니다. 아래 예시는 모두 spec.containers[]의 같은 컨테이너에 넣는 설정 조각입니다. 애플리케이션이 8080 포트에서 /healthz와 /ready를 제공해야 합니다.

검사에 실패하면 어떤 동작이 필요한가

liveness는 프로세스가 살아 있어도 처리가 더 이상 진행되지 않는 상태를 감지합니다. 연속 실패가 임계값에 이르면 kubelet이 컨테이너를 종료하고 적용되는 재시작 정책을 따릅니다. /healthz는 프로세스가 자체적으로 작업을 처리할 수 있는지 가볍게 확인하게 만드세요. 공유 데이터베이스 장애에 모든 애플리케이션 레플리카를 재시작하면 데이터베이스는 그대로인데 콜드 스타트와 재연결만 늘어납니다.

livenessProbe:
  httpGet:
    path: /healthz
    port: 8080
  initialDelaySeconds: 10
  periodSeconds: 10
  failureThreshold: 3

readiness는 일반 Service 트래픽을 받을 수 있는지를 판단합니다. 연속 실패가 임계값에 이르면 kubelet은 컨테이너를 준비되지 않은 상태로 표시합니다. Pod의 Ready 조건에는 컨테이너 상태와 설정된 readiness gate가 반영됩니다. 셀렉터를 쓰는 일반 Service의 경우 엔드포인트가 EndpointSlice에 남은 채 ready: false로 바뀔 수 있습니다. 라우팅에 반영되기까지 시간이 걸릴 수 있으며, 프로브가 기존 연결을 강제로 끊지는 않습니다. Pod로 직접 보내는 요청은 Service를 우회할 수 있습니다. 준비되지 않은 주소도 게시하는 Service라면 publishNotReadyAddresses 설정을 확인하세요. EndpointSlice 조건(영어)

readinessProbe:
  httpGet:
    path: /ready
    port: 8080
  periodSeconds: 5
  failureThreshold: 2

readiness가 실제 제공 가능한 기능을 반영해야 합니다. 모든 요청에 꼭 필요한 의존성이 끊겼다면 해당 인스턴스를 준비되지 않은 상태로 전환할 수 있습니다. 반대로 같은 장애에서도 모든 레플리카가 캐시 결과를 반환할 수 있다면 전부 라우팅에서 제외하는 순간 작동하는 대안까지 잃습니다. 자주 실행되는 검사이므로 엔드포인트도 가볍게 유지합니다.

startup이 성공할 때까지 kubelet은 같은 컨테이너의 liveness와 readiness를 실행하지 않습니다. startup은 각 컨테이너의 기동 시에만 실행됩니다. 연속 실패가 임계값에 이르면 kubelet이 컨테이너를 종료하고 재시작 정책을 적용합니다. 검사 간격이 10초이고 실패 임계값이 30회라면 기동에 약 5분을 배정할 수 있습니다. 첫 검사 시점, 스케줄링, 개별 검사 소요 시간에 따라 실제 시점은 달라집니다.

startupProbe:
  httpGet:
    path: /healthz
    port: 8080
  periodSeconds: 10
  failureThreshold: 30

무엇을 확인하는지에 따라 검사 방식 고르기

방식 성공 신호 주의할 점
HTTP GET 상태 코드 200–399 kubelet은 보통 Pod IP로 연결합니다. 상태 검사 엔드포인트에서 직접 응답합니다. HTTPS를 사용해도 인증서를 검증하지 않습니다.
TCP 연결 성립 애플리케이션이 곧바로 연결을 닫아도 성공으로 처리됩니다. 노드의 kubelet에서 연결하므로 클라이언트 Pod가 실제 요청을 보내는 경로와 다릅니다.
Exec 명령의 종료 코드가 0 명령을 짧게 유지합니다. 파이프나 리디렉션을 쓰려면 셸을 명시해야 합니다. Pod 밀도가 높을 때 프로세스를 자주 띄우면 부하가 커집니다.
gRPC 상태 서비스가 SERVING 반환 gRPC Health Checking Protocol을 구현해야 합니다. 내장 프로브에는 숫자 포트를 쓰며 기본 연결은 평문입니다. 검사 대상을 구분하려면 선택 항목인 service를 사용할 수 있습니다.

HTTP와 TCP에는 이름이 붙은 컨테이너 포트를 사용할 수 있습니다. 내장 gRPC 프로브는 Kubernetes v1.27부터 안정 기능입니다. v1.37부터 TLS를 알파 기능으로 사용할 수 있습니다. 기본값이 꺼져 있는 GRPCContainerProbeTLS를 활성화해야 하며 이 모드에서 kubelet은 서버 인증서를 검증하지 않습니다. gRPC 프로브의 TLS(영어)

HTTP 응답 본문은 작게 유지하고 리디렉션을 피하세요. 다른 호스트로 리디렉션하면 kubelet이 그쪽을 검사하지 않아도 경고와 함께 성공으로 기록될 수 있습니다. Kubernetes 프로브 설정(영어)

탐지 시간과 오탐 사이에서 조정하기

기본값은 initialDelaySeconds: 0, periodSeconds: 10, timeoutSeconds: 1, failureThreshold: 3, successThreshold: 1입니다. liveness와 startup의 successThreshold는 1이어야 합니다. 컨테이너가 준비되지 않은 동안에는 설정한 주기보다 일찍 readiness가 실행될 수 있습니다. startup과 초기 지연 조건은 둘 다 적용됩니다. Kubernetes v1.36.0의 worker는 컨테이너가 Running에 들어간 시각을 기준으로 초기 지연을 계산하므로 startup이 성공한 뒤 처음부터 다시 센다고 가정하지 마세요. 프로브 기본값(영어) · Kubelet v1.36.0 소스

피크 시간대에 /healthz가 가끔 1초를 넘긴다면 설정을 바꾸기 전에 응답 시간을 측정하세요. 아래 대체 설정은 검사마다 3초를 허용하고 연속 세 번 실패하면 종료를 유도합니다. 복구 시간 목표에 맞는다면 앞서 본 liveness 설정 대신 사용합니다. 검사 일정과 소요 시간, 종료 유예 시간에 따라 새 컨테이너가 나타나는 시점도 달라집니다.

livenessProbe:
  httpGet: {path: /healthz, port: 8080}
  periodSeconds: 15
  timeoutSeconds: 3
  failureThreshold: 3

재시작과 트래픽 문제를 따로 진단하기

CrashLoopBackOff는 kubelet이 다음 재시작을 늦추고 있다는 뜻입니다. 아래 읽기 전용 명령의 네임스페이스, Pod, 컨테이너 이름을 실제 값으로 바꾼 뒤 대상 컨테이너의 Last State, 종료 이유, 시간과 이전 로그를 맞춰 봅니다. 이어 같은 시간대의 Pod 이벤트를 확인합니다.

NS=shop
POD=checkout-abc
CONTAINER=checkout

kubectl -n "$NS" describe pod "$POD"
kubectl -n "$NS" logs "$POD" -c "$CONTAINER" --previous
kubectl -n "$NS" get events --field-selector "involvedObject.kind=Pod,involvedObject.name=$POD" --sort-by=.metadata.creationTimestamp

startup 또는 liveness 실패 직후 컨테이너가 종료됐다면 프로브가 종료를 유도했을 가능성이 있습니다. 마지막 종료 이유가 OOMKilled라면 메모리를 살펴봅니다. readiness 실패도 Unhealthy 이벤트를 남길 수 있으므로 이벤트 이유만으로는 판단할 수 없습니다. Pod가 계속 실행되지만 일반 라우팅에서 빠졌다면 readiness와 Service의 EndpointSlice를 확인합니다.

kubectl -n shop get endpointslice -l kubernetes.io/service-name=checkout -o yaml

API 서버의 --event-ttl 기본값은 1시간이며 실제 보존 기간은 클러스터 설정에 따릅니다. 더 긴 이력을 봐야 한다면 DataKit의 Kubernetes 이벤트 수집(영어)을 활성화하고 대상 네임스페이스를 읽을 수 있는지 확인합니다. involved_namespace, involved_name, 이벤트 시각을 대상 컨테이너의 로그나 상태와 대조하면 최근 readiness 변동을 이전 재시작의 원인으로 오인하는 일을 줄일 수 있습니다. Pod 수명 주기(영어) · API 서버 설정(영어)

관련 글 · Kubernetes 아키텍처 · Helm으로 Kubernetes에 Prometheus 설치하기

맞춤형 플랜 상담

문의하기

커뮤니티 가입

WeChat으로 스캔하여
커뮤니티에 가입하세요

Guance 사용해 보기

온라인에서 바로 시작하고 사용한 만큼만 결제하세요.

시작하기

Guance 요금제 선택

코드 저장소