12 KiB
title, source_type, url, archive_url, status, confidence, tags, related_projects, related_branches, created, last_reviewed
| title | source_type | url | archive_url | status | confidence | tags | related_projects | related_branches | created | last_reviewed | |||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| Kubernetes — Configure Liveness, Readiness and Startup Probes | official-doc | https://kubernetes.io/docs/tasks/configure-pod-container/configure-liveness-readiness-startup-probes/ | raw | high |
|
|
|
2026-05-22 | 2026-05-27 |
Kubernetes — Configure Liveness, Readiness and Startup Probes
Layer:
raw/official-docs/— Kubernetes 공식 가이드 (Configure Probes task + Probes concept page) 원문 발췌. ca-tmplfeature-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
periodSecondsis 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 를 gatingK8S-PROBE-C6:periodSecondsdefault 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-contractsource-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 후보:
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:
- 인용하는 project:
- 인용한 wiki 요약: (미작성)