init: llm-wiki-haness 하네스 설계

vault/50-journal/daily-tasks/infra/2026-05-29-actuator-readiness-probe-db-disconnect-detection.md

@@ -0,0 +1,360 @@
+---
+title: daily-task / infra / actuator-readiness-probe-db-disconnect-detection
+source_type: daily-task
+track: infra
+status: raw
+status_label: not-started
+difficulty: intermediate
+duration_estimate: 120
+prerequisites:
+  - "[[raw/project-notes/ca-skeleton-operational-contract]]"
+  - "[[raw/official-docs/runtime-health-spring-actuator-groups]]"
+parent_project: ca-skeleton-operational-contract
+parent_branch:
+target_date: 2026-05-29
+created: 2026-05-28
+tags: [daily-task, infra, observability, runtime]
+---
+
+# daily-task / infra / actuator-readiness-probe-db-disconnect-detection
+
+> Layer: `raw/daily-tasks/infra/` — **인프라/운영 트랙 일일 실습 과제**.
+> `status_label`: `not-started` → `in-progress` → `done`
+> `difficulty`: `intermediate` (Spring Boot actuator 기본 사용 + k8s probe 개념 가정)
+> `duration_estimate`: 120 (Apply / 측정 대기 시간 포함)
+>
+> **이 과제의 위치**: infra 트랙 1일차. [[raw/project-notes/ca-skeleton-operational-contract]] §15 (Runtime/Lifecycle) — actuator health/readiness/liveness 기준 — 의 *측정 가능한 1차 검증*. develop 첫 과제 (`archunit-controller-domain-return-rule`) 와 같은 날 진행해 코드 contract + 운영 contract 가 한 사이클에 검증되는 경험을 만든다.
+
+## Parent / 부모 (필수)
+
+- **Parent project**: [[raw/project-notes/ca-skeleton-operational-contract]] (§15 Runtime/Lifecycle, §18 Metrics/Alerting)
+- **연관 branch**: (없음 — operational contract 직접 검증)
+
+## 1. 학습 목표 / Learning Objectives
+
+- [ ] **L1**: Spring Boot `health/readiness` 와 `health/liveness` 의 의미 차이 — *내 서비스가 트래픽 받을 준비됐는가* (readiness) vs *프로세스를 죽여야 하는가* (liveness) — 를 1분 안에 누군가에게 설명할 수 있다
+- [ ] **L2**: `application.yaml` 에 actuator health group 을 명시 설정하고 `/actuator/health/readiness` 에 DB indicator 가 포함됨을 검증할 수 있다
+- [ ] **L3**: DB 단절 시 readiness 가 `OUT_OF_SERVICE` 로 전환되고 이 변화가 *몇 초 만에* (kubectl + prometheus 양 채널) 표면화되는지 *측정값으로* 제시할 수 있다
+- [ ] **L4 (필수, advanced)**: liveness 는 *동일 상황에서 전환되지 않음* (pod kill ≠ DB 단절) 을 확인하고, 왜 그래야 하는지 trade-off 로 설명할 수 있다 — 이 한 줄이 mid 와 senior 의 차이
+
+## 2. 스토리라인 / WHY (Storyline)
+
+[[raw/project-notes/ca-skeleton-operational-contract]] §15 는 "actuator health/readiness/liveness 기준" 을 요구하지만, 많은 프로젝트가 default `/actuator/health` 만 보는 readinessProbe 로 만족한다. 이 default 의 의미는 **"프로세스가 살아있다"** 이지 **"트래픽 받을 준비됐다"** 가 아니다.
+
+DB가 죽어도 Spring Boot 프로세스는 잘 살아있으니 `/actuator/health` 는 200을 반환하고, k8s readinessProbe 는 *ready* 라고 판정하고, 트래픽이 흘러오고, 5xx 가 양산된다. 알림이 울리고 사람이 새벽에 깨고, root cause 는 "왜 우리는 DB 단절을 readiness 에 반영하지 않았는가" 가 된다.
+
+오늘은 *그 한 가지* — readiness 를 명시적으로 분리하고 DB indicator 를 포함 — 를 설정하고, 의도적으로 DB 를 *끊었을 때* 몇 초 후 not-ready 가 어디서 어떻게 표면화되는지 *측정값으로* 답할 수 있게 만든다.
+
+심화 (L4): liveness 는 같은 상황에서 *전환되지 않아야* 한다. 왜냐하면 DB 단절은 *프로세스를 죽일 이유* 가 아니라 *트래픽을 잠시 차단할 이유* 이기 때문. 이걸 헷갈리면 pod 이 재기동 폭주에 들어가서 DB 가 살아나도 cluster 가 회복 불능. 이 trade-off 가 시니어 초반급 사고의 핵심.
+
+## 3. 환경 / Environment
+
+**작업 호스트**: 로컬 Linux/macOS/WSL2 (사용자 환경에 맞게)
+
+**대상 환경**:
+
+- Cluster: 로컬 `kind` 또는 `k3d` (cluster 없으면 시작 절차에 포함)
+- Namespace: `ca-tmpl-dev`
+- Kubeconfig context: `kind-ca-tmpl-dev` (예시)
+
+**도구 버전**:
+
+- `kubectl`: 1.30+
+- `kind`: 0.23+ (또는 `k3d` 5.6+, 또는 minikube)
+- `docker`: 24.x
+- Spring Boot: 3.3.x (ca-tmpl 기존)
+- 관측: Prometheus 2.50+ + Grafana 11.x (kube-prometheus-stack helm chart 권장)
+
+**사전 셋업**:
+
+```bash
+# 1) 작업 디렉토리 + 브랜치
+cd ~/workspace/ca-tmpl-infra   # (또는 ca-tmpl 의 deploy/ 디렉토리)
+git checkout -b daily-task/infra/actuator-readiness-probe-db-disconnect-detection
+
+# 2) cluster 확인
+kubectl config current-context
+kubectl get ns ca-tmpl-dev || kubectl create ns ca-tmpl-dev
+
+# 3) 현재 상태 스냅샷 (롤백 reference)
+kubectl get all -n ca-tmpl-dev -o yaml > /tmp/snapshot-pre-readiness-probe.yaml
+
+# 4) Prometheus / Grafana 준비 (없으면 설치)
+helm list -n monitoring | grep prometheus || echo "kube-prometheus-stack 설치 필요"
+
+# 5) 현재 ca-tmpl 의 application.yaml 확인
+grep -A 10 'management:' ca-tmpl/src/main/resources/application.yaml || echo "actuator 설정 없음"
+```
+
+**변경 예정 리소스**:
+
+- `ca-tmpl/src/main/resources/application.yaml` — `management.endpoint.health.probes.enabled=true`, group readiness/liveness 명시
+- `deploy/k8s/ca-tmpl-deployment.yaml` — readinessProbe path 분리, livenessProbe 의 thresholds 명시
+- (선택) `deploy/k8s/alerts/db-disconnect.yaml` — PrometheusRule 신규
+
+## 4. 사전 지식 / Prerequisites
+
+- [[raw/project-notes/ca-skeleton-operational-contract]] §15 (Runtime/Lifecycle) + §18 (Metrics/Alerting) 정독
+- [[raw/official-docs/runtime-health-spring-actuator-groups]] — actuator health group 공식 spec
+- (있으면) Kubernetes liveness vs readiness 공식 정의 — `kubernetes.io/docs/concepts/workloads/pods/pod-lifecycle/`
+- Spring Boot `DataSourceHealthIndicator` 의 default 동작 (connection validation query)
+
+## 5. 단계별 과제 / Exercises
+
+### Step 1: 베이스라인 측정 (~20min)
+
+- **What**: 현재 상태를 *수치* 로 기록. 변경 후 비교 가능해야 함.
+- **How (hint)**:
+  - 현재 `/actuator/health` 응답 body (DB indicator 가 *있는지* 없는지)
+  - `kubectl describe pod <ca-tmpl-pod>` → readinessProbe / livenessProbe 설정 (path, initialDelay, period, threshold)
+  - `kubectl get pod -w` 로 ready 상태 watch
+  - DB container 가 살아있는 동안의 readiness 응답 시간 (curl -w 로 측정)
+- **Done when**: §7 결과물 섹션에 baseline 표 3행 이상 (`/actuator/health` 응답 type / readinessProbe path / readiness latency)
+
+### Step 2: actuator group 설정 + manifest 변경 (~30min)
+
+- **What**: `application.yaml` 에 health group 명시, k8s manifest 의 probe path 분리.
+- **How (hint)**:
+
+```yaml
+# application.yaml
+management:
+  endpoint:
+    health:
+      probes:
+        enabled: true
+      group:
+        readiness:
+          include: readinessState,db,diskSpace
+        liveness:
+          include: livenessState
+      show-details: never   # PII / secret leak 방지 (CLAUDE.md §11)
+```
+
+```yaml
+# k8s deployment.yaml (발췌)
+spec:
+  containers:
+    - name: ca-tmpl
+      readinessProbe:
+        httpGet:
+          path: /actuator/health/readiness
+          port: 8080
+        initialDelaySeconds: 10
+        periodSeconds: 5
+        failureThreshold: 3   # = 15초 후 NotReady
+      livenessProbe:
+        httpGet:
+          path: /actuator/health/liveness
+          port: 8080
+        initialDelaySeconds: 30
+        periodSeconds: 10
+        failureThreshold: 6   # = 60초 후 kill (보수적)
+```
+
+- **함정 / 의도적 노출**:
+  - readiness 에 `db` 를 *너무 빨리* 포함시키면 부팅 시점에 DB 가 천천히 ready 되는 동안 pod 도 NotReady → 부팅 지연
+  - liveness 에 `db` 를 포함시키면 *DB 죽었다고 pod kill* — **이게 가장 큰 함정. 의도적으로 절대 안 한다.**
+- **Done when**:
+  - `kubectl apply --dry-run=server -f <manifest>` 통과
+  - probe path / period / threshold 가 baseline 과 어떻게 다른지 diff 검토 완료
+
+### Step 3: Apply + 정상 readiness 확인 (~25min)
+
+- **What**: 실제 apply, rollout 대기, 정상 상태 측정.
+- **How (hint)**:
+
+```bash
+kubectl apply -f deploy/k8s/ca-tmpl-deployment.yaml
+kubectl rollout status deployment/ca-tmpl -n ca-tmpl-dev --timeout=120s
+
+# 1) HTTP 응답 직접 확인
+kubectl port-forward svc/ca-tmpl 8080:8080 -n ca-tmpl-dev &
+curl -sS http://localhost:8080/actuator/health/readiness | jq .
+curl -sS http://localhost:8080/actuator/health/liveness | jq .
+
+# 2) k8s pod 상태
+kubectl get pod -n ca-tmpl-dev -l app=ca-tmpl
+
+# 3) prometheus query (kube-state-metrics)
+# promql: kube_pod_container_status_ready{namespace="ca-tmpl-dev",container="ca-tmpl"}
+```
+
+- **Done when**:
+  - readiness 응답 = `{"status":"UP"}` (show-details=never 로 detail 미노출 — §11 정합)
+  - kubectl `READY 1/1`
+  - prometheus 의 `kube_pod_container_status_ready` = 1
+
+### Step 4: 의도적 DB 단절 → not-ready 전환 시간 측정 (~25min, **본 과제의 핵심**)
+
+- **What**: DB 를 *끊고* 몇 초 후 readiness 가 false 로 전환되는지 4-5 채널 교차 측정. liveness 는 전환되지 *않음* 을 확인.
+- **How (hint)**:
+
+```bash
+# 1) 측정 시작 시각 기록
+TS_START=$(date +%s)
+echo "DB cut at $TS_START"
+
+# 2) DB 단절 (postgres container stop 또는 service block)
+kubectl delete pod -n ca-tmpl-dev -l app=postgres
+# (또는) docker stop ca-tmpl-postgres
+
+# 3) 즉시 watch 시작 — 별 터미널에서:
+watch -n 1 "kubectl get pod -n ca-tmpl-dev -l app=ca-tmpl -o wide && curl -sS http://localhost:8080/actuator/health/readiness; echo; curl -sS http://localhost:8080/actuator/health/liveness"
+
+# 4) NotReady 표면화 시각 측정
+# - readiness 응답이 503 또는 OUT_OF_SERVICE 로 바뀌는 순간
+# - kubectl 의 READY 가 0/1 로 바뀌는 순간
+# - prometheus 의 metric 이 0 으로 바뀌는 순간
+# 세 값의 차이 자체가 학습 포인트
+
+# 5) liveness 가 *전환되지 않는지* 확인 (UP 유지)
+```
+
+- **측정해야 할 값들**:
+  - T_actuator: actuator readiness 가 OUT_OF_SERVICE 로 전환된 시각 (DB 단절 후 N초)
+  - T_kubectl: `kubectl get pod` 의 READY 가 0/1 로 표시되는 시각
+  - T_prometheus: prometheus metric 이 0 으로 바뀌는 시각 (kube-state-metrics scrape interval 의 영향)
+  - liveness 응답 상태: *반드시* UP 유지
+
+- **함정 / 트레이드오프 의식** (시니어 사고):
+  - `failureThreshold=3`, `periodSeconds=5` 이면 *최대* 15초 후 표면화 — 더 빨리 잡으려면 period↓ 인데 false positive ↑
+  - HikariCP 의 `connection-timeout` 과 actuator probe timeout 의 상호작용 — actuator가 DB indicator 평가 시 30초 hang 하면 readinessProbe 자체도 timeout
+  - **prometheus scrape interval (예: 30초) 이 alert 표면화의 lower bound** — 5초마다 NotReady 가 토글되면 prometheus 는 못 봄. 이걸 모르면 "왜 alert 가 안 울리지" 미스터리 발생.
+
+- **Done when**:
+  - 세 측정값 (T_actuator, T_kubectl, T_prometheus) 표로 기록
+  - liveness 가 *전환되지 않음* 명시적으로 확인
+  - **§8 회고에 "왜 세 값이 다른가" 한 문장 답변**
+
+### Step 5 (선택, advanced): DB 복원 → readiness 자동 복귀 측정 (~20min)
+
+- **What**: DB 다시 살리고 readiness 가 자동으로 UP 으로 돌아오는 시간 측정 + 그 사이 traffic 처리 동작 확인.
+- **How (hint)**:
+  - DB pod 재시작
+  - HikariCP 의 connection pool 이 자동 복구되는지 (`hikari.minimum-idle` 영향)
+  - 복귀 시간 = HikariCP retry interval + actuator probe period
+- **트레이드오프** (시니어 사고):
+  - 자동 복구가 *너무 빠르면* DB 가 flaky 할 때 readiness 가 토글 — load balancer 도 토글
+  - 의도적 hysteresis 권장 (예: 30초 연속 UP 일 때만 ready)
+- **Done when**: 복귀 시간 측정값 + 그 사이 in-flight 요청의 운명 (drop / 502 / queue) 기록
+
+## 6. 검증 / Assessment
+
+**자동 검증** (4-5 채널 중 ≥2개 교차):
+
+```bash
+# 1) Probe / health (정상 상태)
+curl -fsS http://localhost:8080/actuator/health/readiness | jq -e '.status == "UP"'
+curl -fsS http://localhost:8080/actuator/health/liveness  | jq -e '.status == "UP"'
+# 합격 기준: 두 명령 모두 exit 0
+
+# 2) k8s 리소스 상태 (rollout 후)
+kubectl rollout status deployment/ca-tmpl -n ca-tmpl-dev --timeout=60s
+# 합격 기준: successfully rolled out
+
+# 3) PromQL — readiness 가 metric 으로 노출
+# 권장 query: kube_pod_container_status_ready{namespace="ca-tmpl-dev",container="ca-tmpl"}
+# 합격 기준: 정상 시 = 1
+
+# 4) DB 단절 시뮬레이션 시 readiness 전환
+# (Step 4 의 측정 결과를 contract test 로 만들 수 있다면 가산점)
+
+# 5) Smoke test — 정상 endpoint 가 200 응답
+curl -fsS http://localhost:8080/api/v1/<sample-endpoint>
+# 합격 기준: exit 0 (정상 상태에서)
+```
+
+**수동 self-check**:
+
+- [ ] 위 4-5채널 중 ≥2 가 *교차* 확인됨 (단일 채널 의존 금지)
+- [ ] DB 단절 시 readiness 전환 시간이 measurable (Step 4 측정값 표 존재)
+- [ ] liveness 가 DB 단절 상황에서 *UP 유지* — 측정으로 확인
+- [ ] 롤백 명령 (`kubectl apply -f /tmp/snapshot-pre-readiness-probe.yaml`) 이 *완전히* 베이스라인으로 복귀 가능
+- [ ] L1~L4 학습 목표 모두 *수행 가능* — 특히 L4 (liveness/readiness trade-off) 를 *한 줄로* 설명 가능
+- [ ] manifest commit 메시지가 "왜" 를 답함
+
+## 7. 결과물 / Outcomes
+
+- **commit / PR**:
+  - 브랜치: `daily-task/infra/actuator-readiness-probe-db-disconnect-detection`
+  - commits: <해시 + 1줄>
+- **변경된 manifest / 설정**:
+  - `ca-tmpl/src/main/resources/application.yaml` — actuator health group 명시
+  - `deploy/k8s/ca-tmpl-deployment.yaml` — probe path 분리, threshold 명시
+- **측정값 표** (Step 1 baseline vs Step 4 적용 후):
+
+| 측정 항목 | Baseline | DB 단절 후 |
+|---|---|---|
+| `/actuator/health/readiness` 응답 | UP / 200 | OUT_OF_SERVICE / 503 (T초 후) |
+| `kubectl get pod` READY | 1/1 | 0/1 (T초 후) |
+| prometheus `kube_pod_container_status_ready` | 1 | 0 (T초 후) |
+| liveness 응답 | UP | **UP 유지** (의도) |
+
+- **Dashboard / Alert**:
+  - Grafana panel: `ca-tmpl readiness` (kube_pod_container_status_ready over time)
+  - Alert rule (작성 시): readiness=0 이 60초 지속 시 P2 alert
+- **Runbook stub**:
+  - 알람 발생 시 1차 확인: `kubectl describe pod -l app=ca-tmpl` + `curl /actuator/health/readiness`
+  - 즉시 fail-fast vs degrade: DB 단절 = readiness 차단 (fail-fast), pod kill 아님 (degrade with traffic block)
+- **학습한 개념** (wiki/concepts 후보):
+  - readiness vs liveness 의 운영적 차이
+  - HikariCP connection timeout 과 probe timeout 의 상호작용
+  - prometheus scrape interval 이 alert detection 의 lower bound
+- **다음 과제 thread**:
+  - HikariCP `connection-timeout` 의 적정값 측정
+  - readinessProbe failure 후 traffic drain (Kubernetes service endpoint 갱신 시간)
+  - chaos test 자동화 (chaos-mesh)
+  - circuit breaker (Resilience4j) 와 readiness 의 관계
+
+## 8. 회고 / Reflection (~5min)
+
+- **막혔던 곳** (몇 분 / 어디서):
+- **예상과 다른 점** (특히 측정값 vs 예측):
+  - 예: `failureThreshold=3` 인데 readiness 가 *15초보다 늦게* 표면화 — 왜? (probe timeout? actuator hang?)
+  - prometheus metric 이 *훨씬 늦게* 변함 — scrape interval 영향
+- **다음 반복에서 개선할 점**:
+- **부수 효과로 발견한 것**:
+- **이 과제의 난이도가 적정했는가**: `너무 쉬움` / `적정` / `너무 어려움`
+- **시니어 사고 체크** (필수 1줄 답변):
+  - "왜 liveness 에 DB 를 포함하면 안 되는가?" — <답>
+  - "T_actuator, T_kubectl, T_prometheus 세 값이 다른 이유는 무엇인가?" — <답>
+  - "readiness 토글 (UP→OUT_OF_SERVICE→UP) 이 잦으면 어떤 운영 문제를 일으키는가?" — <답>
+
+## 9. 출처 / Sources
+
+| Source | 정당화 영역 |
+|---|---|
+| [[raw/company-tech-blogs/skillable-hands-on-lab-structure]] | template 9-section 구조 |
+| [[raw/company-tech-blogs/deliberate-practice-software-developers-redgreencode]] | §5 단계 분할 + §8 reflection |
+| [[raw/project-notes/ca-skeleton-operational-contract]] | §15 Runtime/Lifecycle (probe 기준) + §18 Metrics/Alerting |
+| [[raw/official-docs/runtime-health-spring-actuator-groups]] | actuator health group 공식 spec — readiness/liveness 분리 근거 |
+
+## 10. 완료 후 정리 / Closure
+
+- **최종 status_label**: `done` | `abandoned`
+- **소요 시간 실측**: <분> (vs 120) — 차이는 §8 회고에
+- **promotable 후보**:
+  - `actually-implemented` → ca-skeleton-operational-contract §15 의 actuator probe 분리 결정의 *실 구현* 증거
+  - `locally-verified` → DB 단절 → readiness 전환 측정값 4채널 교차 확인
+  - `prod-verified` → (해당 없음 — 로컬 cluster)
+- **추출하지 않을 항목**:
+  - chaos-mesh 자동화 / circuit breaker 통합 — 별도 daily-task 로 분할
+
+## 11. 운영 회복력 / Operational Resilience (infra 전용 anchor)
+
+- **본 변경이 도입하는 새 실패 모드**:
+  - DB indicator 가 *시간이 오래 걸리는 query* 면 readinessProbe 자체가 timeout → false NotReady
+  - probe period 가 *너무 짧으면* DB 가 잠시 hiccup 할 때 ready 토글 → load balancer 토글 → 502 spike
+- **새 실패 모드의 fail-fast vs degrade 분류**:
+  - DB 단절 = fail-fast (트래픽 차단)
+  - DB 응답 지연 = degrade (slow 응답이지만 트래픽 유지) — readiness 에 포함시킬지 결정 필요
+- **모니터링 누락 위험**:
+  - prometheus scrape interval 보다 *짧은* not-ready 윈도우는 못 봄 (false success)
+  - alert quiet hours 가 없으면 readiness toggle 시 alert 폭주
+- **롤백 트리거 조건**:
+  - readiness false 가 5분 지속 + DB 자체는 정상 → 본 변경 자체의 false positive 가능성 → 즉시 롤백
+  - `kubectl apply -f /tmp/snapshot-pre-readiness-probe.yaml`
+- **연관 alert / runbook**:
+  - [[raw/project-notes/ca-skeleton-operational-contract]] §28 Operational Runbook 의 "DB unavailable" 시나리오와 정합
+  - 본 과제의 PrometheusRule 이 §28 의 1차 alert 항목으로 등록되어야 함