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 서버 설정(영어)
