Files
clean-architecture-backend-…/docs/runbooks/redis-capability-incident.md
T
DongHyeonka 1885bf8da7 fix!: 2차 재리뷰가 찾은 결함 29건을 고친다
문제: 재리뷰 수정 커밋(bbe944bd)만 다시 본 2차 재리뷰가 Important 7건,
Minor 22건을 찾았다. 결과 불명 503 뒤 같은 키를 다시 보내면 Redis
store가 lease 지난 실행을 넘겨받아 작업을 다시 돌렸다. replay TTL이
lease보다 짧으면 lease 도중 key가 사라져 같은 키가 두 번 실행됐다.
@SystemInvoked 규칙이 매뉴얼 09장의 이벤트 소비 경로까지 막았다. V22가
outbox_event에 가장 강한 잠금을 lock_timeout 없이 걸었다. prod의
fixture- 거부가 HOSTNAME 같은 비밀 아닌 값까지 막았다. 데모 허용 목록의
test·demo 프로필로 sample이 뜨지 않았다. 기동 rule bean의 @Value 필드가
조용히 null이 됐다.

방법: 영역별 4묶음이 test-driven-development 절차로 실패 테스트를
먼저 쓰고 고쳤다. 결정은 재리뷰 README 9.1절이다.
- 두 멱등성 store가 같은 계약을 따른다. lease가 지난 실행 기록은 다시
  돌리지 않고 포기로 표시해 500 RECOVERY_REQUIRED로 답한다. 기록 수명은
  lease + replay TTL이고, replay-ttl < processing-lease면 기동이 실패한다.
- 사용자 transport만 @SystemInvoked use case에 닿지 못한다. 메시지
  handler·scheduler는 새 표시 @SystemCaller(reason)를 달고 use case를
  생성자에서 new로 만든다. 매뉴얼 경로를 테스트로 고정했다.
- 아직 어디에도 적용되지 않은 마이그레이션(V20·V22·알림 V11~V13·sample
  V8_1·grpc V002·V003)에 lock_timeout 5s를 넣고, 텍스트 검사기와 실 PG
  lane을 더했다. 이미 배포된 24개는 동결 목록으로 둔다.
- fixture- 검사는 비밀로 분류된 값만 본다. sample은 local·test·demo에서
  object storage를 끈다. 기동 rule bean에 주입 멤버가 있으면 모든
  프로필에서 기동이 실패한다. 리뷰어가 제안한 "static @Bean 선언 강제"는
  문제없는 등록을 막고 @Value 필드는 통과시켜서 버렸다.
- 이 수정 전에 move된 파일의 쿼터 차이를 찾는 쿼리와 재계산 SQL을
  docs/fileserver/operations.md에 적었다.

위험·한계: lease 뒤 늦게 끝난 첫 시도의 결과는 기록되지 않는다(그 요청도
500). @SystemCaller가 없는 메시지 handler, 주입 멤버가 있는 기동 rule,
working-directory 없이 ./gradlew를 부르는 workflow 명령은 파생 서비스에서
새로 실패하거나 세지지 않는다(업그레이드 안내 B-14~16·B-36·B-39).
spotbugsTestFixtures는 게이트 밖이고 기준 커밋에서도 실패하며, 새 검사기의
정규식 경고 8건이 더해졌다. 실제 CI runner 실행은 확인하지 못했다(Gitea
repo의 Actions가 꺼져 있다).

검증: ci, 두 빌드의 verifyStrictLaneStages --dry-run, mainCheck,
:integrationCheck, -p optional-platforms ci integrationCheck
performanceCheck, :performanceCheck, :releaseCheck(-PgitRevision),
verify-compose-profile-contracts(18 lane) 첫 실행 통과. 쿼터 재계산
SQL은 실 PostgreSQL 16에서 차이 2행 → 0행을 확인했다.

Refs: docs/reviews/2026-11-03-rereview/README.md 9·9.1·10절
BREAKING CHANGE: replay-ttl < processing-lease 설정은 기동 실패, ledger
release가 claim token을 받는다, HttpBodyReadException(IOException 하위)이
본문 실패를 싣는다, 기동 rule·비밀 목록 bean의 주입 멤버 금지,
verifyStrictLaneStages가 workflow 명령의 working-directory로 빌드를 정한다.
2026-11-04 01:47:50 +09:00

16 KiB

title, category, error_codes, severity, owner, last_updated, status
title category error_codes severity owner last_updated status
Runbook — Redis capability incident TRANSIENT_DEPENDENCY
P1 oncall 2026-07-29 active

Runbook: Redis capability incident (runbook://redis/capability-incident)

이 runbook은 Redis 전체를 하나의 상태로 취급하지 않는다. 먼저 영향받은 capability와 role을 식별한다.

Role Capability 기본 안전 결정
CACHE cache, cache refresh soft lease source fallback 예산 안에서 degraded serving 허용
COORDINATION edge rate limit, request-replay idempotency, efficiency lease 새 mutation/claim을 fail closed하고 결과 불확실성을 보존
SESSION Redis session 인증을 fail open하지 않고 재인증 또는 503으로 전환

Redis liveness 실패만으로 pod를 재시작하지 않는다. 재시작 폭주는 reconnect와 source fallback 부하를 키울 수 있다.

Detection

  • readiness detail에서 affected role과 required 여부를 확인한다. endpoint, key, token, secret reference는 detail에 포함되면 안 된다.
  • semantic reason을 구분한다: read/write failure, program ACL denial, unsupported server version, program failure, command saturation, recent command failure, probe-in-progress, stale observation, closed route, command unavailable. semanticObservedAt, semanticAgeMillis, semanticStale를 함께 확인한다. PING 성공만으로 role이 ready라는 뜻은 아니다.
  • evictionValidation=CONFIGURED_EXPECTATION_ONLY와 externalEvictionAttestation=INCOMPLETE는 effective server policy가 증명되지 않았다는 뜻이다. 이를 정상 attestation으로 해석하지 않는다.
  • 지금 내보내는 Redis 지표는 connection lane 단위 redis.lane.*다(docs/registries/metrics.yaml, lane 태그). capability·operation 단위 지표(redis.capability.*)는 설계만 있고 아직 어떤 코드도 내보내지 않는다 — 대시보드에서 찾지 않는다(재리뷰 2026-11-03, src/adapter/outbound/cache-redis/README.md 「아직 내보내지 않는 지표」).
  • lane 포화: redis.lane.acquire.refused.total(거절)과 redis.lane.acquire.wait.seconds(대기)를 lane별로 본다. CACHE_SCRIPT만 차 있으면 캐시 조건부 쓰기의 문제이고, 멱등성·lease가 쓰는 SCRIPT lane은 따로 본다(재리뷰 RR-04-02).
  • 연결 불안정: redis.lane.connections.opened.total·redis.lane.connections.discarded.total의 급증, redis.lane.connections.active·pending.
  • operation 결과(hit/miss/denied/conflict, certainty=indeterminate)는 지표가 아니라 각 capability의 로그와 health detail에서 확인한다. timeout이나 연결 끊김은 미실행 증거가 아니다.
  • readiness는 최신 health detail의 state/reason/requirement로 본다. optional cache의 degraded serving과 required coordination/session의 fail-closed 결정을 같은 availability 의미로 합치지 않는다.
  • 재연결은 redis.lane.connections.opened.total과 discarded.total을 함께 본다(Cluster TRANSACTION lane은 borrow마다 열어 opened가 꾸준히 오른다 — cache-redis/README.md). cache source-load·session repository 오류 지표는 내보내는 코드가 없다(설계만 있음).
  • Redis server 측에서는 memory/eviction, rejected clients, replication link/lag, persistence error, Cluster coverage를 operator dashboard에서 확인한다.
  • NOSCRIPT, result-schema mismatch, ACL denial, TLS/auth failure, OOM, timeout을 서로 다른 incident category로 분류한다. timeout은 command 미실행 증거가 아니다.

Observability and lifecycle boundaries

  • redis.lane.* meter의 tag는 닫힌 lane 이름뿐이다. key, subject, session id, token, endpoint, exception text, script/SHA, value 같은 identity/wire material을 metric이나 ticket에 복사하지 않는다.
  • semantic operation 단위 계측(hit/miss/denied/conflict/unavailable/indeterminate 결과, cache의 stale/skipped, session의 tombstoned/absolute_expired)은 설계만 있고 내보내지 않는다 (redis.capability.*, 위 Detection 절). operation 결과는 로그와 health detail로 본다. redis.lane.* 계측(listener)이 실패해도 borrow 결과나 원래 exception은 바뀌지 않는다. 처음 실패는 WARN 로그 한 줄로 남고(RedisRuntimeOwner), 그 뒤는 DEBUG다 — 지표가 통째로 비면 그 WARN을 찾는다.
  • route 응답이 설정된 byte/collection bound를 넘으면 동일 logical operation을 unavailable로 종료한다. GET/read-only 응답은 not_applied, mutation VALUE/MULTI 응답은 서버 실행 여부를 되돌릴 수 없으므로 indeterminate다.
  • Spring 종료의 dependency order는 invalidation subscription 같은 capability dependent를 먼저 닫고, capability bean을 닫은 다음 canonical registry가 router admission을 닫아 in-flight를 bounded drain하고 마지막에 runtime을 닫는 순서다. 종료 중 새 command를 허용하거나 drain timeout 뒤 무기한 기다리지 않는다.
  • 현재 composition에는 active Redis scheduler나 dormant credential-rotation coordinator가 없다. 존재하지 않는 lifecycle coordinator를 복구 절차에서 찾거나 수동 호출하지 않는다.
  • redis.lane.* meter와 단일-process lifecycle test는 Sentinel/Cluster failover, TLS/ACL 배포 적합성, k3s multi-node, L1/L2 분산 일관성, distributed session 동작의 qualification 증거가 아니다. 해당 label은 별도 topology/conformance lane의 실제 증거가 있어야 한다.

Immediate mitigation

  1. 새 배포나 credential/program 전환 직후라면 해당 rollout을 중지한다. 이미 실행된 mutation을 무조건 재시도하지 않는다.
  2. optional cache만 영향을 받으면 source bulkhead와 stale/source fallback 예산을 확인한 뒤 degraded serving을 유지한다. source가 포화되면 cache miss를 더 많은 source 요청으로 증폭시키지 않는다.
  3. rate limit이 불확실하면 정책에 정의된 fail-closed 또는 bounded local-emergency만 사용한다. local provider를 조용한 primary fallback으로 바꾸지 않는다.
  4. idempotency claim/complete 응답이 유실됐으면 같은 operation token으로 inspect/reconcile한다. record를 삭제하거나 새 owner를 추측하지 않는다.
  5. lease 결과가 불확실하면 소유권이 있다고 가정하지 않는다. fencing 없는 efficiency lease를 correctness lock으로 승격하지 않는다.
  6. session repository 장애에서는 기존 요청을 인증된 것으로 간주하지 않는다. fail closed 또는 재인증으로 전환하고 JWT와 Redis Session filter를 동시에 활성화하지 않는다.

Diagnosis

Connectivity, TLS, ACL

  • 배포 설정이 올바른 role을 참조하고 TLS, hostname verification, explicit trust bundle, named ACL user를 사용하는지 확인한다.
  • runtime identity로 CONFIG, KEYS, FLUSH*, arbitrary program deployment를 시도하지 않는다. Catalog digest로 닫힌 recovery 외 ACL 점검은 별도 operator/deployer identity의 ACL DRYRUN 또는 동등한 관리 절차로 수행한다.
  • runtime readiness identity에는 bounded probe namespace ~ca-health:*, SET/GET/DEL, PING/EVALSHA와 catalog recovery에 필요한 SCRIPT LOAD, 그리고 선택 capability manifest의 exact command set이 필요하다. broad ~*/+@all로 장애를 우회하지 않는다.
  • readiness probe는 5초 TTL의 opaque key만 사용한다. ca-health:* key가 5초를 넘겨 남는다면 cleanup/expiry 이상으로 분류하되 key나 value를 ticket/log에 복사하지 않는다.
  • 기본 semantic cadence는 minimum interval 5초, maximum staleness 15초다. refresh follower는 blocking하지 않는다. maximum staleness를 넘은 관측을 backend 정상으로 해석하지 말고, probe 부하를 줄이기 위해 interval을 1초 미만으로 낮추지 않는다.
  • optional CACHE의 typed temporary connect/PING outage만 dormant degraded startup과 health-triggered reconnect를 허용한다. reconnect 후보는 full semantic qualification 뒤에만 설치된다. auth/TLS/material/version/ACL/schema mismatch를 transient로 재분류하거나 required role에 같은 fallback을 적용하지 않는다.
  • credential rotation 중이라면 new credential 검증, traffic switch, old connection drain, old credential revoke 순서를 확인한다. secret 값은 ticket, log, shell history에 복사하지 않는다.

Program or schema

  • checked-in program manifest digest와 배포 artifact digest를 대조한다.
  • semantic-capability-acl-v1 contract와 Redis minimum 7.2를 확인한다. 이 프로그램은 Redis Lua API의 redis.acl_check_cmd로 선택 capability의 exact command/key 권한을 비변경 방식으로 검사하고 redis.REDIS_VERSION_NUM의 explicit >=7.2 gate를 먼저 적용한다. 두 API는 7.0부터 존재하지만 repository support policy minimum은 7.2다.
  • NOSCRIPT는 bounded SCRIPT LOAD -> digest verify -> EVALSHA recovery가 수행됐는지 확인한다. arbitrary EVAL로 우회하지 않는다.
  • result-schema/key/codec future version은 장애가 아니라 호환성 위반으로 분류하고 writer rollout을 중지한다.
  • BUSY 또는 slow program이면 affected capability admission을 줄이고 isolated environment에서만 재현한다. shared Redis에 장시간 script를 추가 실행하지 않는다.

Memory and eviction

  • CACHE 배포와 COORDINATION/SESSION 배포가 물리적으로 분리됐는지 확인한다.
  • correctness role에서 eviction이 관측되면 P1이다. 새 write를 중지하고 record loss를 전제로 idempotency/session reconciliation 또는 재인증 범위를 산정한다.
  • noeviction OOM은 성공으로 변환하지 않는다. cache write는 degraded/indeterminate, coordination mutation은 unavailable/indeterminate로 유지한다.
  • big key를 찾을 때 production request path에서 KEYS나 unbounded collection read를 사용하지 않는다. 승인된 operator job의 bounded SCAN/sampling을 사용한다.

Topology and persistence

  • 현재 구현 후보 card의 promotion topology는 readiness registry의 selected-topology가 정본이다. 이는 selection 또는 R2 qualification을 뜻하지 않는다. Sentinel/Cluster evidence가 없는 상태에서 standalone 증거를 HA 증거로 재사용하지 않는다.
  • Cluster same-slot semantic probe는 해당 hash slot owner 한 노드만 검증한다. 이를 cluster-wide 또는 failover target version/ACL/program 증거로 해석하지 말고, promotion 전에 모든 target을 별도 conformance lane으로 검증한다.
  • failover 뒤에는 in-flight mutation의 certainty, primary role, program availability, replication offset/lag, persistence status를 각각 확인한다.
  • restore 후 session/idempotency/lease record를 자동으로 신뢰하지 않는다. security epoch, tombstone, durable receipt/fencing high-watermark가 필요한 capability는 별도 reconciliation을 수행한다.

Sentinel failover

  1. affected role의 semantic readiness가 unavailable인지 확인하고 단순 PING success로 정상 판정하지 않는다. required coordination/session은 새 mutation admission을 닫는다.
  2. 세 Sentinel 중 응답 수와 같은 master에 동의한 수를 확인한다. 2-of-3 동의 전에는 임의 endpoint, 최초 응답 또는 DNS 추측으로 data runtime을 바꾸지 않는다.
  3. Sentinel discovery credential/CA와 Redis data credential/CA가 분리되어 있는지 확인한다. 장애 우회를 위해 trust-all, hostname verification off, plaintext 또는 broad ACL을 열지 않는다.
  4. election, discovered primary qualification, new runtime install, old runtime admission close/drain의 순서를 확인한다. old runtime을 강제로 닫아야 했다면 그 시점의 mutation을 성공/미실행으로 추정하지 않는다.
  5. response-only cut, timeout, disconnect가 있었던 rate/idempotency/session mutation은 INDETERMINATE를 보존한다. rate evaluation replay, 같은 idempotency/session operation token의 inspect/reconcile 또는 재인증을 사용하고 blind retry하지 않는다.
  6. semantic readiness 복구 전에는 traffic을 정상화하지 않는다. 복구 뒤 old primary의 replica 재합류, replication lag/acknowledgement, program digest, actor runtime generation을 확인한다.

Sentinel은 asynchronous replication의 zero-data-loss나 strong consistency를 보장하지 않는다. min-replicas-to-write, lag bound, replica acknowledgement가 설정돼도 acknowledgement 결과가 불명확한 mutation은 여전히 INDETERMINATE다.

min-replicas-to-write 1 + min-replicas-max-lag 1은 선택이 아니라 필수다. 미설정 시 promotion 중 교체된 구 primary가 계속 +OK를 반환하고 그 write는 resync에서 폐기된다. 7.4 레인 실측: 승격 후 강등까지 11초, 그 사이 2,086건이 acknowledge된 뒤 소실, 실패한 명령은 1건. 클라이언트는 이를 감지할 수단이 없다 — 서버가 응답했으므로 driver·SDK·호출자 모두 정상 성공으로 기록한다. 설정 후 동일 promotion에서 소실 1건, 나머지 2,020건은 NOREPLICAS로 명시 거부됐다. 근거: docs/redis/operations.md, LiveRedisSentinelPromotionTest.

Disposable Multipass k3s qualification safety

qualification lab은 host k3s incident 조치 도구가 아니다. VM exact allowlist는 ca-redis-lab-server, ca-redis-lab-agent-1, ca-redis-lab-agent-2이며 전용 kubeconfig와 ca-redis-lab context만 사용한다.

  • 시작 전 host context/API/node/CIDR/NodePort와 Multipass inventory fingerprint를 기록한다.
  • lab pod/service CIDR 10.52.0.0/16, 10.53.0.0/16이 host와 겹치면 생성하지 않는다.
  • default kubeconfig를 merge/overwrite하거나 host context에 write command를 실행하지 않는다.
  • cleanup은 exact 세 VM만 대상으로 한다. global multipass purge, wildcard delete를 사용하지 않는다.
  • 성공/실패 뒤 postflight fingerprint와 VM resource 0을 확인한다. local retain-on-failure가 명시적으로 활성화됐으면 보존 이유와 exact inventory를 기록하며 CI에서는 보존하지 않는다.
  • 이 한 물리 host의 3 VM 결과를 k3s control-plane HA, physical host/AZ failure 또는 multi-region 증거로 승격하지 않는다.

Recovery and verification

  1. affected role의 connection/auth/TLS와 ca-health: SET/GET/cleanup probe가 정상인지 확인한다. probe 잔여 key가 있으면 최대 TTL 5초 뒤 소멸하는지도 확인한다.
  2. 선택 capability의 대표 program digest/result schema, semantic ACL contract와 Redis minimum version 7.2를 재확인한다.
  3. capability별 smoke를 수행한다: cache generation guarded write, rate evaluation replay, idempotency same-operation inspect, lease stale-owner reject, session create/read/logout.
  4. queue saturation, indeterminate outcome, source fallback, re-auth 지표가 incident 전 범위로 돌아온 뒤에만 rollout을 재개한다.
  5. CONFIGURED_EXPECTATION_ONLY인 eviction은 operator/deployer identity의 외부 conformance job 또는 서명 attestation으로 effective policy를 별도 검증한다. runtime user에 CONFIG/ACL 권한을 추가하지 않는다.
  6. production label을 변경하기 전 repository readiness task를 실행한다. Sentinel/Cluster task가 zero-evidence로 실패한다면 topology를 낮춰 표기하거나 실제 evidence를 먼저 추가한다.
  7. Sentinel qualification에서는 actual image ID/digest와 fault/election/runtime-swap/readiness timeline, capability certainty, teardown 결과가 sanitizer/reconciler를 통과했는지 확인한다. clean committed source와 실제 remote CI가 없으면 implemented-candidate, releaseQualification=NOT_CLAIMED를 유지한다.

Escalation

  • COORDINATION 또는 SESSION required role이 5분 이상 unavailable이면 P1로 Redis/platform, application on-call을 동시에 호출한다.
  • data loss, stale session resurrection, conflicting idempotency completion, duplicate correctness side effect가 의심되면 security/business owner까지 즉시 확대한다.
  • 한 물리 host의 VM 세 개 또는 standalone container 결과를 AZ/host failure 증거로 해석하지 않는다. 그 증거가 필요한 release는 별도 disposable multi-node qualification을 요구한다.