문제: 재리뷰 수정 커밋(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로 빌드를 정한다.
230 lines
16 KiB
Markdown
230 lines
16 KiB
Markdown
---
|
|
title: Runbook — Redis capability incident
|
|
category: TRANSIENT_DEPENDENCY
|
|
error_codes: []
|
|
severity: P1
|
|
owner: oncall
|
|
last_updated: 2026-07-29
|
|
status: 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을 요구한다.
|