llm-wiki/raw/official-docs/runtime-health-k8s-probes-official.md

---
title: "Kubernetes — Configure Liveness, Readiness and Startup Probes"
source_type: official-doc
url: https://kubernetes.io/docs/tasks/configure-pod-container/configure-liveness-readiness-startup-probes/
archive_url:
status: raw
confidence: high
tags: [ca-skeleton, runtime, health, lifecycle, kubernetes, probe]
related_projects: [ca-skeleton-operational-contract]
related_branches: [feature-runtime-health-lifecycle-contract, feature-container-runtime-contract]
created: 2026-05-22
last_reviewed: 2026-05-27
---

# Kubernetes — Configure Liveness, Readiness and Startup Probes

> Layer: `raw/official-docs/` — Kubernetes 공식 가이드 (Configure Probes task + Probes concept page) 원문 발췌.
> ca-tmpl `feature-runtime-health-lifecycle-contract` 의 세 endpoint 분리 + startup probe budget 결정 근거.

## Parent / 활용 branch (필수)

| Branch | 이 자료가 정당화하는 결정 |
|---|---|
| [[raw/branch-notes/feature-runtime-health-lifecycle-contract]] | liveness / readiness / startup 세 endpoint 분리 채택 + startup probe total budget = `failureThreshold × periodSeconds` 산식 채택 근거 |
| [[raw/branch-notes/feature-container-runtime-contract]] | 컨테이너 lifecycle (restart 의미 / traffic drain) 의 K8s probe 의미 정의 |

## 컨텍스트

ca-tmpl `feature-runtime-health-lifecycle-contract` 는 liveness / readiness / startup probe 를 **세 endpoint 로 분리** + startup probe total budget 150s 를 SSOT 로 둠. 본 source 는 그 결정의 외부 근거 — K8s 공식이 정의하는 각 probe 의 의미와 timeout 모델.

## 출처 / Source

- 원본 URL (task): https://kubernetes.io/docs/tasks/configure-pod-container/configure-liveness-readiness-startup-probes/
- 보조 URL (concept): https://kubernetes.io/docs/concepts/workloads/pods/probes/
- 아카이브 URL: (미수집)
- 저자 / 조직: Kubernetes Project (CNCF)
- 발행일: rolling docs (1.32+ reference)
- 마지막 확인일: 2026-05-27

## 핵심 인용 / Key quotes (verbatim)

> [§Configure Liveness, Readiness and Startup Probes — intro] "Many applications running for long periods of time eventually transition to broken states, and cannot recover except by being restarted. Kubernetes provides liveness probes to detect and remedy such situations."

> [§Probes concept — Liveness probe] "Liveness probes determine when to restart a container. For example, liveness probes could catch a deadlock, where an application is running, but unable to make progress. Restarting a container in such a state can help to make the application more available despite bugs."

> [§Probes concept — Liveness probe] "If a container fails its liveness probe more times than the configured tolerance, the kubelet restarts that container."

> [§Probes concept — Readiness probe] "Readiness probes determine when a container is ready to accept traffic. This is useful when waiting for an application to perform time-consuming initial tasks, such as establishing network connections, loading files, and warming caches."

> [§Probes concept — Readiness probe] "If the readiness probe returns a failed state, the EndpointSlice controller removes the Pod's IP address from the EndpointSlices of all Services that match the Pod."

> [§Probes concept — Startup probe] "Startup probes verify whether the application within a container is started. If a startup probe is configured, Kubernetes does not execute liveness or readiness probes until the startup probe succeeds, allowing the application time to finish its initialization."

> [§Probes concept — Configuration] "The default for `periodSeconds` is 10s."

> [§Probes concept — Startup failure] "If the startup probe fails, the kubelet kills the container, and the container is subjected to its restart policy."

> needs-confirmation: 2026-05-27 재검증 시 task 페이지의 "Protect slow starting containers with startup probes" 섹션 본문이 WebFetch 응답에서 truncated 됨. 따라서 "startup probe 가 never succeed 시 300초 (default failureThreshold 30 × periodSeconds 10s) 후 컨테이너 kill" 산식의 **공식 원문 verbatim** 은 본 capture 에서 확보 못 함. 대신 위 concept 페이지의 두 인용 ("default periodSeconds 10s" + "kubelet kills... restart policy") + 예시 인용 ("failureThreshold: 30, periodSeconds: 10") 로 산식 재구성 가능하나, **단일 문장 직접 인용은 별도 fetch 필요**.

> [§Probes concept — example values, paraphrased from doc snippet] "failureThreshold: 30, periodSeconds: 10" (startup probe) / "initialDelaySeconds: 10, periodSeconds: 5, timeoutSeconds: 3, failureThreshold: 3" (liveness probe)

## Claims Extracted / 추출된 주장

| Claim ID | Claim (이 자료가 직접 말하는 것) | Evidence quote | Strength | Applies to | Does not prove |
|---|---|---|---|---|---|
| K8S-PROBE-C1 | liveness probe 는 컨테이너 재시작 시점을 kubelet 에 알려주며, 대표 use case 는 deadlock detection | [§Probes concept — Liveness probe] "Liveness probes determine when to restart a container. For example, liveness probes could catch a deadlock, where an application is running, but unable to make progress." | `official-vendor-doc` | Kubernetes workload 의 모든 컨테이너 | liveness probe 가 모든 종류의 hang 을 검출한다는 뜻은 아님 — probe endpoint 자체가 deadlock 의 영향권 안에 있어야 함 |
| K8S-PROBE-C2 | 컨테이너가 liveness probe 를 configured tolerance 초과로 실패하면 kubelet 이 컨테이너 재시작 | [§Probes concept — Liveness probe] "If a container fails its liveness probe more times than the configured tolerance, the kubelet restarts that container." | `official-vendor-doc` | failureThreshold 값 이상 연속 실패 시 | "tolerance" 의 정확한 default 값 (3) 은 이 인용 단독으로 증명 안 됨 — 별도 configuration reference 필요 |
| K8S-PROBE-C3 | readiness probe 는 컨테이너가 트래픽 수신 준비 됐는지 판단; 실패 시 EndpointSlice controller 가 Pod IP 를 매칭되는 Service 의 EndpointSlice 에서 제거 | [§Probes concept — Readiness probe] "Readiness probes determine when a container is ready to accept traffic." + "If the readiness probe returns a failed state, the EndpointSlice controller removes the Pod's IP address from the EndpointSlices of all Services that match the Pod." | `official-vendor-doc` | Service 가 selector 로 Pod 를 매칭하는 모든 환경 | headless Service / ExternalName Service 등 selector 없는 케이스에는 직접 적용 안 됨 — 인용 범위 밖 |
| K8S-PROBE-C4 | startup probe 가 설정되면 K8s 는 그 probe 가 성공할 때까지 liveness / readiness probe 를 **실행하지 않는다** (느린 초기화 보호) | [§Probes concept — Startup probe] "Startup probes verify whether the application within a container is started. If a startup probe is configured, Kubernetes does not execute liveness or readiness probes until the startup probe succeeds, allowing the application time to finish its initialization." | `official-vendor-doc` | startup probe 가 명시적으로 설정된 컨테이너 | startup probe 미설정 시의 동작 (= liveness/readiness 가 즉시 적용) 은 본 인용 범위 밖 — 추론은 가능하나 인용 부재 |
| K8S-PROBE-C5 | startup probe 실패 시 kubelet 이 컨테이너를 kill, 컨테이너는 자신의 restart policy 적용 대상 | [§Probes concept — Startup failure] "If the startup probe fails, the kubelet kills the container, and the container is subjected to its restart policy." | `official-vendor-doc` | startup probe 가 설정된 컨테이너 | restart policy 의 종류별 (Always / OnFailure / Never) 정확한 동작 차이는 별도 페이지 |
| K8S-PROBE-C6 | `periodSeconds` 의 default 값은 10초 | [§Probes concept — Configuration] "The default for `periodSeconds` is 10s." | `official-vendor-doc` | 모든 probe 종류 | 다른 필드 (failureThreshold / timeoutSeconds / initialDelaySeconds) 의 default 는 본 인용으로 증명 안 됨 |
| K8S-PROBE-C7 | startup probe total budget = `failureThreshold × periodSeconds` (예: 30 × 10s = 300s) — 단, 단일 문장 verbatim 미확보 | (구성 인용 조합) "failureThreshold: 30, periodSeconds: 10" + "kubelet kills the container... restart policy" | `needs-confirmation` | startup probe 의 총 grace period 산식 | 단일 문장으로 산식을 명시한 verbatim 원문은 본 capture 에서 truncate 됨 — task 페이지 §"Protect slow starting containers with startup probes" 별도 fetch 필요 |

## Usage Boundaries / 적용 경계

- **이 자료가 직접 증명하는 것**:
  - `K8S-PROBE-C1` ~ `C5`: 세 probe 의 의미 / 실패 시 동작 / startup probe 가 liveness · readiness 를 gating
  - `K8S-PROBE-C6`: `periodSeconds` default 10s
- **이 자료가 증명하지 않는 것** (verbatim 미확보):
  - `K8S-PROBE-C7`: startup probe total budget 산식의 단일 문장 인용 — concept 페이지의 구성 인용 + task 페이지의 예시로 재구성 가능하나 직접 verbatim 부재
  - `failureThreshold` / `timeoutSeconds` / `initialDelaySeconds` 의 정확한 default 값
  - readiness fail 후 EndpointSlice 에서 Pod 제거까지의 지연 (즉시 vs 다음 sync cycle)
  - liveness probe 가 dependency outage 에서 실패하면 cascading restart 가 발생한다는 anti-pattern 의 공식 경고 (별도 best practice 페이지 fetch 필요)
- **내 프로젝트 (ca-tmpl) 에 적용하려면 추가 확인이 필요한 것**:
  - ca-tmpl 의 startup probe 30 × 5s = 150s 가 ca-tmpl 의 Spring Boot 콜드스타트 + JVM warmup + 외부 의존성 wiring 시간을 cover 하는지 (실측 필요)
  - readiness fail → endpoint 제거 → drain → graceful shutdown 의 e2e timing 이 ca-tmpl 의 PreStop hook + terminationGracePeriodSeconds 와 정합인지

## ca-tmpl 함의 (내 프로젝트 해석)

> 본 섹션은 자료 직접 인용이 아니라 ca-tmpl 결정 컨텍스트 해석. wiki 추출 시 `wiki/projects/ca-skeleton-operational-contract` source-summary 로 이전.

- **핵심 의미 구분**:
  - **liveness 실패** = 컨테이너 재시작 (process 자체가 망가짐, recover 불가).
  - **readiness 실패** = 트래픽 차단 (의존성 / 일시 장애, recover 가능).
  - **startup 실패** = 느린 부팅 보호 (liveness 시계가 너무 빨리 흐르지 않도록).
- **ca-tmpl 과의 일치점**: 세 endpoint 분리 — 공식 권장과 동일. startup probe total budget = `failureThreshold × periodSeconds` = ca-tmpl 의 30 × 5s = **150s** 와 동일 산식 (단, 산식의 단일 문장 verbatim 은 needs-confirmation).
- **단점 / 혼동 포인트**: liveness 가 dependency 장애로 실패하도록 잘못 구현하면 cascading restart 발생. ca-tmpl 이 liveness 를 "JVM process can continue" 로 정의한 이유 — 단, 이 anti-pattern 의 공식 경고 verbatim 은 본 capture 에 없음.

## 메모 / Notes

- 2026-05-27 재검증: task 페이지가 WebFetch 응답에서 truncate 되어 "Protect slow starting containers with startup probes" 섹션 본문 verbatim 확보 실패. 후속으로 (a) sub-URL `#define-startup-probes` 직접 fetch, 또는 (b) archive.org 스냅샷 확인 필요.
- 다음 fetch 후보:
  - https://kubernetes.io/docs/tasks/configure-pod-container/configure-liveness-readiness-startup-probes/#define-startup-probes
  - https://kubernetes.io/docs/tasks/configure-pod-container/configure-liveness-readiness-startup-probes/#configure-probes (default 값 reference)

## Related / 관련

- 같은 주제 다른 official-doc:
  - [[raw/official-docs/runtime-health-spring-actuator-groups]] — Spring Boot 측 health group 매핑
  - [[raw/official-docs/actuator-management-port-spring-official]] — actuator 노출 포트 결정
- 인용하는 branch:
  - [[raw/branch-notes/feature-runtime-health-lifecycle-contract]]
  - [[raw/branch-notes/feature-container-runtime-contract]]
- 인용하는 project:
  - [[raw/project-notes/ca-skeleton-operational-contract]]
- 인용한 wiki 요약: (미작성)