Merge pull request 'docs(runbooks): runbook 신호를 지금 코드가 내는 응답·로그·지표로 고친다' (#30) from claude/r9-a-runbooks into main
main / build-logic (push) Successful in 2m3s
main / main (push) Successful in 26m51s
main / configuration-cache (push) Successful in 2m5s
main / links (push) Successful in 11s
main / vulnerabilities (push) Successful in 1m4s
main / http3-experimental (push) Successful in 57s
main / jpa-postgresql (16) (push) Skipped
main / jpa-postgresql (17) (push) Skipped
main / jpa-postgresql (18) (push) Skipped
main / httpclient-transport (push) Skipped
main / redis-topology (push) Skipped
main / fileserver-nfs-ambiguity (push) Skipped
main / notification-chaos (push) Skipped
main / jpa-next (hibernate-8, Hibernate 8 is not resolvable from this build, so nothing has been compiled or run against it, Hibernate 8, *Hibernate8CompatibilityTest) (push) Skipped
main / jpa-next (jakarta-persistence-4, the JPA 4 API is not on any configuration this build resolves, so nothing has been compiled against it, Jakarta Persistence 4, *Jpa4CompatibilityTest) (push) Skipped
main / jpa-next (postgresql-19, no PostgreSQL 19 image is published yet, so no container of that major has ever been started by this lane, PostgreSQL 19, *PostgreSql19CompatibilityTest) (push) Skipped
main / performance (push) Skipped
main / object-storage-aws (push) Skipped
main / compose-smoke (push) Skipped
main / done (push) Skipped
main / build-logic (push) Successful in 2m3s
main / main (push) Successful in 26m51s
main / configuration-cache (push) Successful in 2m5s
main / links (push) Successful in 11s
main / vulnerabilities (push) Successful in 1m4s
main / http3-experimental (push) Successful in 57s
main / jpa-postgresql (16) (push) Skipped
main / jpa-postgresql (17) (push) Skipped
main / jpa-postgresql (18) (push) Skipped
main / httpclient-transport (push) Skipped
main / redis-topology (push) Skipped
main / fileserver-nfs-ambiguity (push) Skipped
main / notification-chaos (push) Skipped
main / jpa-next (hibernate-8, Hibernate 8 is not resolvable from this build, so nothing has been compiled or run against it, Hibernate 8, *Hibernate8CompatibilityTest) (push) Skipped
main / jpa-next (jakarta-persistence-4, the JPA 4 API is not on any configuration this build resolves, so nothing has been compiled against it, Jakarta Persistence 4, *Jpa4CompatibilityTest) (push) Skipped
main / jpa-next (postgresql-19, no PostgreSQL 19 image is published yet, so no container of that major has ever been started by this lane, PostgreSQL 19, *PostgreSql19CompatibilityTest) (push) Skipped
main / performance (push) Skipped
main / object-storage-aws (push) Skipped
main / compose-smoke (push) Skipped
main / done (push) Skipped
This commit was merged in pull request #30.
This commit is contained in:
@@ -191,6 +191,8 @@ errors:
|
||||
# ============================================================
|
||||
|
||||
# source: feature-security-operational-baseline L93 — "public path misconfiguration ... | 500 + P1 alert | INTERNAL_AUTH_MISCONFIGURATION | INTERNAL"
|
||||
# 지금 이 코드는 JWT decoder를 만들지 못할 때(issuer discovery 4xx·issuer 불일치·jwks_uri 없음) 나온다. 공개 경로
|
||||
# 설정 오류는 이 코드를 내지 않는다(runbook auth-public-path-misconfiguration.md).
|
||||
- code: INTERNAL_AUTH_MISCONFIGURATION
|
||||
category: INTERNAL
|
||||
http_status: 500
|
||||
|
||||
@@ -4,7 +4,7 @@ category: AUTH
|
||||
error_codes: [AUTH_AUDIENCE_MISMATCH]
|
||||
severity: P2
|
||||
owner: oncall
|
||||
last_updated: 2026-06-15
|
||||
last_updated: 2026-11-13
|
||||
status: 초안
|
||||
---
|
||||
|
||||
@@ -17,7 +17,7 @@ status: 초안
|
||||
|
||||
## 진단
|
||||
|
||||
- 토큰의 `aud` 클레임 값을 본다.
|
||||
- 클라이언트가 어떤 audience로 token을 요청하는지 클라이언트 설정에서 본다. 토큰·`Authorization` 헤더·JWT payload는 로그에 남지 않고 남겨서도 안 된다. 값을 봐야 하면 클라이언트 쪽에서 재현한다.
|
||||
- 설정된 `app.security.audience`(`APP_SECURITY_JWT_AUDIENCE`, 쉼표로 구분)와 비교한다. 토큰은 그중 하나 이상을
|
||||
담아야 한다.
|
||||
|
||||
|
||||
@@ -4,7 +4,7 @@ category: AUTH
|
||||
error_codes: [AUTH_ISSUER_MISMATCH]
|
||||
severity: P2
|
||||
owner: oncall
|
||||
last_updated: 2026-06-15
|
||||
last_updated: 2026-11-13
|
||||
status: 초안
|
||||
---
|
||||
|
||||
@@ -13,22 +13,24 @@ status: 초안
|
||||
## 증상
|
||||
|
||||
- HTTP 401, `error.code=AUTH_ISSUER_MISMATCH`.
|
||||
- 토큰의 `iss` 클레임이 설정된 발급자와 다르다.
|
||||
- WARN 로그 줄 `security failure: code=AUTH_ISSUER_MISMATCH category=AUTH method=… path=…`(logger `AuthErrorResponseWriter`).
|
||||
|
||||
## 진단
|
||||
|
||||
- 토큰의 `iss`를 `spring.security.oauth2.resourceserver.jwt.issuer-uri`와 비교한다.
|
||||
- IdP 환경이 바뀌었는지 확인한다.
|
||||
- 검증기가 비교하는 값은 `app.security.issuer-uri`(env `APP_SECURITY_JWT_ISSUER`)다(`config/security.yml` → `JwtDecoderConfig`). 같은 env가 `spring.security.oauth2.resourceserver.jwt.issuer-uri`도 채우지만 decoder는 그 키를 읽지 않는다.
|
||||
- 거부된 token의 `iss`를 클라이언트 쪽에서 디코딩해 `APP_SECURITY_JWT_ISSUER`와 견준다. 흔한 원인은 hostname(내부·외부 주소), realm 이름, 끝의 `/` 차이다. IdP discovery의 `issuer`와 설정값이 다르면 이 401이 아니라 decoder를 만들지 못한 500 `INTERNAL_AUTH_MISCONFIGURATION`이다(`docs/runbooks/auth-public-path-misconfiguration.md`).
|
||||
- 토큰, `Authorization` 헤더, JWT payload는 로그에 남지 않고 남겨서도 안 된다.
|
||||
|
||||
## 조치
|
||||
|
||||
- IdP를 옮겼으면 issuer 설정을 고친다.
|
||||
- 예상하지 않은 발급자의 토큰은 계속 거부한다.
|
||||
- IdP를 옮겼으면 `APP_SECURITY_JWT_ISSUER`를 고친다.
|
||||
- 예상하지 않은 발급자의 token은 계속 거부한다.
|
||||
|
||||
## 에스컬레이션
|
||||
|
||||
- 예상하지 않은 발급자를 찾으면 플랫폼 보안 팀에 넘긴다.
|
||||
|
||||
|
||||
---
|
||||
|
||||
> **초안**: 서비스가 도메인을 채운 뒤 본문을 쓴다.
|
||||
|
||||
@@ -4,7 +4,7 @@ category: TRANSIENT_DEPENDENCY
|
||||
error_codes: [AUTH_JWKS_UNAVAILABLE]
|
||||
severity: P1
|
||||
owner: oncall
|
||||
last_updated: 2026-11-06
|
||||
last_updated: 2026-11-13
|
||||
status: 초안
|
||||
---
|
||||
|
||||
@@ -15,16 +15,17 @@ status: 초안
|
||||
- HTTP 503, `error.code=AUTH_JWKS_UNAVAILABLE`.
|
||||
- ERROR 로그 줄 `security failure: code=AUTH_JWKS_UNAVAILABLE category=TRANSIENT_DEPENDENCY method=… path=…`
|
||||
(logger `AuthErrorResponseWriter`).
|
||||
- 인증이 모두 실패하고, JWKS 새로 고침도 실패한다.
|
||||
- token을 실은 요청이 모두 이 503으로 답하고, 응답에는 `Retry-After: 30`이 붙는다.
|
||||
|
||||
## 진단
|
||||
|
||||
- IdP의 JWKS 엔드포인트 상태를 본다: `curl -sf https://<idp-host>/.well-known/jwks.json`
|
||||
- 앱이 읽는 JWKS 주소는 issuer discovery로 정해진다: `app.security.issuer-uri`(`APP_SECURITY_JWT_ISSUER`)의 `/.well-known/openid-configuration`에 있는 `jwks_uri`다. 앱이 도는 곳에서 그 두 주소를 `curl -sf`로 읽는다.
|
||||
- 앱 pod에서 IdP까지 네트워크가 닿는지 확인한다.
|
||||
|
||||
## 조치
|
||||
|
||||
- 캐시된 JWKS로 버틸 수단이 있으면 쓴다.
|
||||
- 첫 검증에 성공한 뒤에는 키를 라이브러리(Nimbus) 기본 캐시에 두므로, IdP가 잠깐 멈춰도 캐시가 살아 있는 동안은 검증이 된다. 앱에는 캐시 시간·새로 고침 손잡이가 없다.
|
||||
- 첫 검증 전이거나 캐시가 지난 뒤 IdP에 닿지 않으면 이 503이 난다. decoder는 다음 요청에서 다시 시도하므로 IdP가 돌아오면 저절로 회복한다.
|
||||
- IdP 팀과 복구를 맞춘다.
|
||||
|
||||
## 에스컬레이션
|
||||
|
||||
@@ -4,7 +4,7 @@ category: AUTH
|
||||
error_codes: [AUTH_KID_UNKNOWN]
|
||||
severity: P2
|
||||
owner: oncall
|
||||
last_updated: 2026-06-15
|
||||
last_updated: 2026-11-13
|
||||
status: 초안
|
||||
---
|
||||
|
||||
@@ -12,23 +12,25 @@ status: 초안
|
||||
|
||||
## 증상
|
||||
|
||||
- HTTP 401, `error.code=AUTH_KID_UNKNOWN`, `retryable=true`.
|
||||
- 토큰 헤더의 `kid`가 캐시된 JWKS에 없다.
|
||||
- HTTP 401, `error.code=AUTH_KID_UNKNOWN`, `retryable=true`, `Retry-After: 5`.
|
||||
- WARN 로그 줄 `security failure: code=AUTH_KID_UNKNOWN category=AUTH method=… path=…`(logger `AuthErrorResponseWriter`).
|
||||
- token 헤더의 `kid`가 앱이 읽은 JWKS에 없다.
|
||||
|
||||
## 진단
|
||||
|
||||
- 최근에 IdP 키 교체가 있었는지 확인한다.
|
||||
- JWKS 캐시 TTL과 새로 고침 시점을 확인한다.
|
||||
- JWKS는 issuer discovery의 `jwks_uri`에서 읽는다(`app.security.issuer-uri`, `APP_SECURITY_JWT_ISSUER`). 그 주소에 새 kid가 있는지 본다. 앱에는 JWKS 캐시 TTL·새로 고침 손잡이가 없다(라이브러리 기본 캐시).
|
||||
|
||||
## 조치
|
||||
|
||||
- JWKS 캐시를 강제로 새로 고친다.
|
||||
- 새 키가 IdP JWKS 엔드포인트에 게시됐는지 확인한다.
|
||||
- 새 키가 IdP JWKS에 게시됐는지 확인한다.
|
||||
- 모르는 kid가 오면 decoder가 JWKS를 다시 받으므로, 새 키가 게시되면 재시작 없이 다음 요청부터 통과한다. 게시됐는데도 계속 이 401이면 앱이 읽는 `jwks_uri`가 IdP가 키를 게시한 곳과 같은지(앞단 캐시·다른 realm) 본다.
|
||||
|
||||
## 에스컬레이션
|
||||
|
||||
- 10분이 지나도 새 kid가 JWKS에 나타나지 않으면 IdP 팀에 넘긴다.
|
||||
|
||||
|
||||
---
|
||||
|
||||
> **초안**: 서비스가 도메인을 채운 뒤 본문을 쓴다.
|
||||
|
||||
@@ -1,10 +1,10 @@
|
||||
---
|
||||
title: Runbook — INTERNAL_AUTH_MISCONFIGURATION (공개 경로 설정 오류)
|
||||
title: Runbook — INTERNAL_AUTH_MISCONFIGURATION (JWT decoder 설정 오류)
|
||||
category: INTERNAL
|
||||
error_codes: [INTERNAL_AUTH_MISCONFIGURATION]
|
||||
severity: P1
|
||||
owner: oncall
|
||||
last_updated: 2026-11-07
|
||||
last_updated: 2026-11-13
|
||||
status: 초안
|
||||
---
|
||||
|
||||
@@ -15,22 +15,23 @@ status: 초안
|
||||
- HTTP 500, `error.code=INTERNAL_AUTH_MISCONFIGURATION`.
|
||||
- ERROR 로그 줄 `security failure: code=INTERNAL_AUTH_MISCONFIGURATION category=INTERNAL method=… path=…`
|
||||
(logger `AuthErrorResponseWriter`).
|
||||
- 실행 중에 보안 필터 설정 오류가 드러났다.
|
||||
- 이 코드는 JWT decoder를 만들 수 없을 때 나온다: issuer metadata가 망가졌거나 네트워크 문제가 아닌 이유로 decoder 초기화가 실패했다(`JwtDecoderConfig` → `SecurityErrorClassifier`). decoder는 첫 token을 검증할 때 만들어지므로 기동은 성공하고, token을 실은 요청마다 이 500이 난다.
|
||||
- 공개 경로 설정 오류는 이 코드를 내지 않는다. 잘못 연 공개 경로는 오류 없이 열리므로 스냅숏 검사(아래)로만 잡힌다.
|
||||
|
||||
## 진단
|
||||
|
||||
- CI의 `verifyPublicPathSnapshot` 결과를 본다.
|
||||
- `SecurityConfig`와 공개 경로 목록(`config/security.yml`의 `public-paths`, `SECURITY_PUBLIC_PATHS`)의 최근
|
||||
변경을 본다.
|
||||
- 먼저 issuer 설정을 본다. 앱이 도는 곳에서 `<APP_SECURITY_JWT_ISSUER>/.well-known/openid-configuration`을 받는다. 이 500은 discovery 후보 주소가 모두 4xx(없는 realm, 틀린 경로)이거나, 응답의 `issuer`가 `APP_SECURITY_JWT_ISSUER`와 글자까지 다르거나(끝의 `/` 포함), `jwks_uri`가 없을 때다.
|
||||
- 연결 실패·5xx·JSON이 아닌 응답이면 이 코드가 아니라 503 `AUTH_JWKS_UNAVAILABLE`이다(`docs/runbooks/auth-jwks-unavailable.md`).
|
||||
- 공개 경로를 의심하면 CI의 `verifyPublicPathSnapshot` 결과와 공개 경로 목록(`config/security.yml`의 `public-paths`, `SECURITY_PUBLIC_PATHS`)의 최근 변경을 본다.
|
||||
|
||||
## 조치
|
||||
|
||||
- 잘못된 공개 경로 변경을 되돌린다.
|
||||
- 저장소 루트에서 `./gradlew verifyPublicPathSnapshot`을 돌려 스냅숏과 비교한다.
|
||||
- `APP_SECURITY_JWT_ISSUER`를 IdP discovery의 `issuer`와 같게 고쳐 다시 배포한다. 설정은 기동 때 읽는다.
|
||||
- 잘못된 공개 경로 변경을 되돌린다. 저장소 루트에서 `./gradlew verifyPublicPathSnapshot`을 돌려 스냅숏과 비교한다.
|
||||
|
||||
## 에스컬레이션
|
||||
|
||||
- P1 즉시: 설정 오류로 인증을 건너뛸 수 있으면.
|
||||
- P1 즉시: token을 싣는 모든 요청이 500이다. 공개 경로를 잘못 열어 인증을 건너뛸 수 있을 때도 P1이다.
|
||||
|
||||
---
|
||||
|
||||
|
||||
@@ -4,7 +4,7 @@ category: AUTH
|
||||
error_codes: [AUTH_TOKEN_EXPIRED]
|
||||
severity: P3
|
||||
owner: oncall
|
||||
last_updated: 2026-11-07
|
||||
last_updated: 2026-11-13
|
||||
status: 초안
|
||||
---
|
||||
|
||||
@@ -17,7 +17,7 @@ status: 초안
|
||||
|
||||
## 진단
|
||||
|
||||
- `exp` 클레임과 서버 시계를 비교한다.
|
||||
- 서버 시계와 token 발급 호스트의 시계를 비교한다. token의 `exp`는 클라이언트 쪽에서 재현해 본다. 토큰·`Authorization` 헤더·JWT payload는 로그에 남지 않고 남겨서도 안 된다.
|
||||
- 토큰을 발급하는 호스트의 NTP 동기화를 확인한다.
|
||||
|
||||
## 조치
|
||||
|
||||
@@ -4,7 +4,7 @@ category: AUTH
|
||||
error_codes: [AUTH_TOKEN_INVALID_SIGNATURE]
|
||||
severity: P1
|
||||
owner: oncall
|
||||
last_updated: 2026-11-06
|
||||
last_updated: 2026-11-13
|
||||
status: 초안
|
||||
---
|
||||
|
||||
@@ -24,7 +24,7 @@ status: 초안
|
||||
|
||||
## 조치
|
||||
|
||||
- JWKS의 키 ID가 토큰 헤더와 맞는지 확인한다.
|
||||
- IdP가 서명에 쓰는 키가 JWKS(`jwks_uri`)에 게시됐는지 확인한다. token 헤더의 `kid`는 클라이언트 쪽에서 재현해 본다. 토큰·`Authorization` 헤더·JWT payload는 로그에 남지 않고 남겨서도 안 된다.
|
||||
- 위조가 의심되면 보안 팀에 알린다.
|
||||
|
||||
## 에스컬레이션
|
||||
|
||||
@@ -4,7 +4,7 @@ category: AUTH
|
||||
error_codes: [AUTH_TOKEN_MALFORMED, INVALID_TOKEN]
|
||||
severity: P3
|
||||
owner: oncall
|
||||
last_updated: 2026-06-15
|
||||
last_updated: 2026-11-13
|
||||
status: 초안
|
||||
---
|
||||
|
||||
@@ -12,22 +12,23 @@ status: 초안
|
||||
|
||||
## 증상
|
||||
|
||||
- HTTP 401 응답, `error.code=AUTH_TOKEN_MALFORMED`.
|
||||
- 토큰은 있지만 JWT로 파싱되지 않는다(세 부분이 아님, base64가 아님 등).
|
||||
- HTTP 401, `error.code=AUTH_TOKEN_MALFORMED`, `WWW-Authenticate: Bearer error="invalid_token"`.
|
||||
- WARN 로그 줄 `security failure: code=AUTH_TOKEN_MALFORMED category=AUTH method=… path=…`(logger `AuthErrorResponseWriter`).
|
||||
- 분류기가 더 좁은 코드로 가르지 못한 token 실패도 이 코드다(`SecurityErrorClassifier`).
|
||||
|
||||
## 진단
|
||||
|
||||
- 로그에서 Authorization 헤더 원문을 본다.
|
||||
- 토큰을 만드는 도구에 버그가 있는지 확인한다.
|
||||
- 토큰, `Authorization` 헤더, JWT payload는 로그에 남지 않고 남겨서도 안 된다. 값을 봐야 하면 클라이언트 쪽에서 재현한다.
|
||||
- 같은 `path=`·시각에 몰리는지 보고 어느 클라이언트인지 앞단 접근 로그로 찾는다.
|
||||
|
||||
## 조치
|
||||
|
||||
- 잘못된 토큰이 어디서 오는지 찾는다.
|
||||
- 클라이언트의 토큰 생성을 고친다.
|
||||
- 클라이언트의 token 생성·전달(접두어 `Bearer `, 잘린 값)을 고친다.
|
||||
|
||||
## 에스컬레이션
|
||||
|
||||
- 급증이 인프라 문제를 가리키면 넘긴다.
|
||||
- 급증이 인프라 문제(프록시가 헤더를 바꿈 등)를 가리키면 넘긴다.
|
||||
|
||||
|
||||
---
|
||||
|
||||
|
||||
@@ -4,7 +4,7 @@ category: AUTH
|
||||
error_codes: [AUTH_TOKEN_MISSING, UNAUTHENTICATED]
|
||||
severity: P3
|
||||
owner: oncall
|
||||
last_updated: 2026-06-15
|
||||
last_updated: 2026-11-13
|
||||
status: 초안
|
||||
---
|
||||
|
||||
@@ -12,13 +12,12 @@ status: 초안
|
||||
|
||||
## 증상
|
||||
|
||||
- HTTP 401 응답, `error.code=AUTH_TOKEN_MISSING`.
|
||||
- 클라이언트가 Authorization 헤더나 Bearer 토큰을 보내지 않았다.
|
||||
- HTTP 401, `error.code=AUTH_TOKEN_MISSING`, `WWW-Authenticate: Bearer`.
|
||||
- WARN 로그 줄 `security failure: code=AUTH_TOKEN_MISSING category=AUTH method=… path=…`(logger `AuthErrorResponseWriter`). 보안 chain이 거부한 요청은 요청 로그(`http_request …`)에는 없다.
|
||||
|
||||
## 진단
|
||||
|
||||
- 요청 로그에서 Authorization 헤더가 빠졌는지 본다.
|
||||
- 클라이언트 SDK 설정을 확인한다.
|
||||
- 헤더가 있었는지는 앱 로그에 없다. 앞단 프록시·gateway 설정과 클라이언트 SDK 설정을 본다.
|
||||
|
||||
## 조치
|
||||
|
||||
@@ -29,6 +28,7 @@ status: 초안
|
||||
|
||||
- 넓게 퍼졌거나 중요한 업무 흐름에 영향이 있으면 넘긴다.
|
||||
|
||||
|
||||
---
|
||||
|
||||
> **초안**: 서비스가 도메인을 채운 뒤 본문을 쓴다.
|
||||
|
||||
@@ -4,65 +4,33 @@ category: AUTH
|
||||
error_codes: [AUTH_TOKEN_EXPIRED, AUTH_KID_UNKNOWN, AUTH_JWKS_UNAVAILABLE, AUTH_TOKEN_INVALID_SIGNATURE]
|
||||
severity: P1
|
||||
owner: oncall
|
||||
last_updated: 2026-05-22
|
||||
last_updated: 2026-11-13
|
||||
status: 초안
|
||||
---
|
||||
|
||||
# Runbook: JWT key rotation 시 인증 실패 spike
|
||||
|
||||
## 1. Trigger
|
||||
## 증상
|
||||
|
||||
이 runbook은 다음 alert가 울리면 쓴다.
|
||||
- 401이 몰리고 코드가 `AUTH_KID_UNKNOWN`(retryable, `Retry-After: 5`)·`AUTH_TOKEN_INVALID_SIGNATURE`·`AUTH_TOKEN_EXPIRED`, 또는 503 `AUTH_JWKS_UNAVAILABLE`(`Retry-After: 30`)이다.
|
||||
- WARN 로그 줄 `security failure: code=<CODE> category=<CATEGORY> method=… path=…`(logger `AuthErrorResponseWriter`). 4xx는 WARN, 5xx는 ERROR다. `code=`·`category=`는 메시지 글자이고 구조화 칸이 아니다. `AUTH_JWKS_UNAVAILABLE`의 category는 `TRANSIENT_DEPENDENCY`다.
|
||||
- 이 템플릿은 경보 규칙·대시보드를 두지 않는다. 서비스가 위 `security failure` 줄의 `code=`·`path=`나 `http.server.requests`의 tag `status`로 만든다. 보안 chain이 거부한 요청은 handler가 없어 tag `uri`가 `UNKNOWN`이니 경로로 가르지 못한다. 이 경로의 로그에는 `dependency_name` 칸이 없다.
|
||||
|
||||
- alert name: `auth_401_error_rate_high` 또는 `jwks_refresh_failure_spike`
|
||||
- alert payload 필수 field: `operation`, `error.code`, `error.category`, `runbook_link`, `dependency_name`
|
||||
- 임계: 401 error rate > 5% 5분 지속 OR JWKS refresh failure count > 10건/분
|
||||
## 진단
|
||||
|
||||
## 2. First Response (5분 이내)
|
||||
- JWKS 주소는 issuer discovery로 정해진다: `app.security.issuer-uri`(`APP_SECURITY_JWT_ISSUER`)의 `/.well-known/openid-configuration`에 있는 `jwks_uri`다(`JwtDecoderConfig`). 그 주소를 앱이 도는 곳에서 `curl -sf`로 읽어 새 kid가 있는지 본다.
|
||||
- JWKS 캐시 TTL·강제 새로 고침 손잡이는 없다. decoder는 처음 쓸 때 discovery를 하고, 실패하면 다음 요청에서 다시 한다. 한 번 성공한 뒤에는 라이브러리 기본 캐시로 `jwks_uri`를 다시 읽는다.
|
||||
- 시계 차이 허용은 60초다(`JwtDecoderConfig`). 만료가 몰리면 발급 호스트의 NTP를 본다.
|
||||
- 토큰, `Authorization` 헤더, JWT payload는 로그에 남지 않고 남겨서도 안 된다. 값을 봐야 하면 클라이언트 쪽에서 재현한다.
|
||||
|
||||
### Step 1 — 확인
|
||||
1. JWKS endpoint health check: `curl -sf https://<idp-host>/.well-known/jwks.json | jq '.keys | length'`
|
||||
2. log query에서 `error.code` 분포 확인 — `AUTH_KID_UNKNOWN` 비중이 높으면 rotation 원인 강력 시사
|
||||
3. IdP rotation schedule 확인 (직전 24h 내 rotation 이벤트가 있었는지)
|
||||
## 조치
|
||||
|
||||
### Step 2 — 임시 격리
|
||||
- JWKS cache TTL을 짧게(예: 60s) 강제하여 새 kid 전파 가속
|
||||
- 새 kid가 JWKS에 publish되어 있는지 확인. 누락이면 IdP에 republish 요청
|
||||
- IdP가 새 키를 게시하기 전에 그 키로 서명한 token을 냈으면 IdP 쪽에서 「게시 → 대기 → 전환」 순서를 지킨다. 앱 쪽 kid 허용 목록은 없다.
|
||||
- 모르는 kid가 오면 decoder가 JWKS를 다시 받으므로 키 교체에 재시작은 필요 없다. 재시작이 필요한 경우는 IdP가 `jwks_uri`를 옮겼을 때뿐이다. discovery는 decoder를 처음 만들 때 한 번만 읽기 때문이다(`JwtDecoderConfig`).
|
||||
|
||||
## 3. Diagnosis
|
||||
## 에스컬레이션
|
||||
|
||||
- log query (Loki/CloudWatch): `{service="auth"} | error.category="AUTH" | dependency_name="jwks-endpoint"`
|
||||
- metric panel: `auth_jwks_cache_hit_ratio`, `auth_jwks_refresh_failure_total`, `auth_kid_unknown_total`
|
||||
- trace: 실패한 request 1건에서 `traceId` 추출 → IdP outbound span 확인
|
||||
- 가능한 원인:
|
||||
- 새 kid가 JWKS에 publish되기 전 token 발급 → 24h overlap window 안에 있는지 확인
|
||||
- JWKS endpoint 장애 (5xx, timeout) → IdP status page 확인
|
||||
- 시계 skew로 인한 만료 오판 → NTP sync 상태 확인
|
||||
|
||||
## 4. Mitigation
|
||||
|
||||
- 단기: old kid를 임시 재허용 (rollback). overlap window를 48h로 일시 확장
|
||||
- IdP에 새 JWKS publish 재시도 요청
|
||||
- 장기: rotation 절차에 "publish → 24h 대기 → switch" 단계 강제. observability에 kid 분포 metric 추가
|
||||
|
||||
## 5. Escalation
|
||||
|
||||
- P2 → P1 격상 조건: 401 error rate > 20% 또는 다중 tenant에 동시 발생
|
||||
- 다음 on-call로 page: 10분 내 회복 안 되면 IdP team 또는 platform-security team page
|
||||
|
||||
## 6. Recovery / Verification
|
||||
|
||||
- 회복 확인 metric: `auth_401_error_rate < 1%` 5분 지속, `AUTH_KID_UNKNOWN` 건수 0
|
||||
- post-incident:
|
||||
- rotation 절차 RCA 작성
|
||||
- JWKS overlap window 정책 문서 업데이트
|
||||
- kid 분포 dashboard 영구화
|
||||
|
||||
## 7. Related
|
||||
|
||||
- error-codes.yaml rows: `AUTH_TOKEN_EXPIRED`, `AUTH_KID_UNKNOWN`, `AUTH_JWKS_UNAVAILABLE`, `AUTH_TOKEN_INVALID_SIGNATURE`
|
||||
- metrics.yaml: `auth_jwks_cache_hit_ratio`, `auth_jwks_refresh_failure_total`
|
||||
- 관련 branch: [[feature-security-operational-baseline]]
|
||||
- 10분 안에 회복하지 않으면 IdP 팀에 넘긴다.
|
||||
|
||||
---
|
||||
|
||||
|
||||
@@ -4,68 +4,32 @@ category: AUTHZ
|
||||
error_codes: [AUTHZ_INSUFFICIENT_PERMISSION, AUTHZ_TENANT_MISMATCH]
|
||||
severity: P2
|
||||
owner: oncall
|
||||
last_updated: 2026-05-22
|
||||
last_updated: 2026-11-13
|
||||
status: 초안
|
||||
---
|
||||
|
||||
# Runbook: cross-tenant 접근 시도 감지
|
||||
|
||||
## 1. Trigger
|
||||
## 증상
|
||||
|
||||
이 runbook은 다음 alert가 울리면 쓴다.
|
||||
- `AUTHZ_TENANT_MISMATCH`는 enum 상수(`OperationalError`)와 registry 행이 있지만 내는 코드가 없다.
|
||||
- 실제 동작: 남의 tenant·소유자의 객체는 없는 것과 같은 404다(예: durable operation `OPERATION_NOT_FOUND`, `DurableOperationAccessPolicy`). 파일 서버는 403 `ACCESS_DENIED`, GraphQL은 HTTP 200 본문의 오류 `RESOURCE_NOT_FOUND`(category AUTHORIZATION)다. tenant를 요청 입력으로 보낸 요청은 서비스가 요청 경로에서 web-advanced `WebSecurityContextBridge.resolve(authentication, requestInput)`(요청 입력을 받는 두 인자 판)을 부를 때만 403 `TENANT_INPUT_UNTRUSTED`가 된다. 한 인자 `resolve`와 기본 구성은 그 검사를 하지 않아 그런 header는 무시된다.
|
||||
- 이 거부들에는 코드를 가진 전용 WARN 줄이 없다(4xx carrier, `ServerFailureLog`). web은 요청 로그 줄 `http_request … status=<404 또는 파일 서버 403>`(MDC `user_principal` 포함)과 `http.server.requests`의 `status`가 남지만 평범한 404·403과 구별되지 않는다. GraphQL 거부는 HTTP 200이라 status로도 보이지 않는다. 시도를 세려면 서비스가 판정하는 자리에서 WARN 한 줄과 지표를 더해야 한다.
|
||||
|
||||
- alert name: `authz_cross_tenant_violation` 또는 `authz_403_spike`
|
||||
- alert payload 필수 field: `operation`, `error.code`, `error.category`, `principal_id_pseudonymized`, `tenant_id`, `runbook_link`
|
||||
- 임계:
|
||||
- P2: 403 with `error.code=AUTHZ_TENANT_MISMATCH` > 10건/5분
|
||||
- P1 격상: 동일 principal에서 3개 이상 tenant 시도 OR 5분 내 100건 초과
|
||||
## 진단
|
||||
|
||||
## 2. First Response (5분 이내)
|
||||
- 서비스가 그 신호를 더했다면 그 WARN 줄의 MDC `request_id`로 같은 요청의 `http_request` 줄을 찾고, 그 줄의 MDC `user_principal`(가명화한 사용자 식별자)로 같은 호출자를 묶는다. `user_principal`은 `RequestLoggingFilter`가 요청 로그 줄을 쓸 때만 MDC에 두므로 handler 안에서 남긴 줄에는 없다. 서비스 WARN 줄에 직접 실으려면 `UserPrincipalPseudonymizerPort`로 가명 값을 만든다. 원본 사용자 식별자·IP·토큰 claim은 로그에 없고 남기지 않는다.
|
||||
- `trace_id`로 요청 흐름을 따라간다. tenant는 인증 정보에서만 오고 요청 값에서 오지 않으므로(`docs/manual/07-authorization.md` 「객체 단위 권한」), 비교할 「요청의 tenant」는 없다.
|
||||
- 가능한 원인: 계정 탈취, 다른 tenant의 id를 쓰는 클라이언트 버그, 여러 tenant를 다뤄야 하는 관리 작업의 권한 누락.
|
||||
|
||||
### Step 1 — 확인
|
||||
1. log query로 위반 principal 식별 (pseudonymized): `error.code=AUTHZ_TENANT_MISMATCH`
|
||||
2. principal의 정상 tenant scope 확인 (IdP claim 또는 entitlement table)
|
||||
3. `CROSS_TENANT_ADMIN` capability 보유 여부 확인 — 보유자라면 false positive 가능성
|
||||
## 조치
|
||||
|
||||
### Step 2 — 임시 격리
|
||||
- 명백한 위반 패턴이면 principal session 강제 만료 (token revocation list 추가)
|
||||
- security incident channel 통보 (`#sec-incident`)
|
||||
- 위반 request의 source IP / user-agent 기록
|
||||
- 반복하는 호출자는 gateway·IdP에서 막는다. 이 템플릿에는 token 폐기 목록이 없다(JWT 모드는 상태가 없다. Redis 세션 모드는 세션을 지우면 끊긴다).
|
||||
- 여러 tenant를 다루는 관리 작업이 거부되면 그 유스케이스의 권한 판정을 본다. 관리 경로는 관리 권한으로 따로 판정한다(예: 파일 서버 `ForceDeleteFileApplicationUseCase`의 `file:admin`과 `FileOperation.ADMIN_FORCE_DELETE`). `@UseCaseCapability(crossTenantAdmin = true)`는 ArchUnit·리뷰가 보는 선언이라 실행 시 접근을 열지 않는다(`docs/registries/capabilities.yaml`).
|
||||
|
||||
## 3. Diagnosis
|
||||
## 에스컬레이션
|
||||
|
||||
- log query: `{service="api"} | error.category="AUTHZ" | principal_id_pseudonymized="<hash>"`
|
||||
- metric panel: `authz_denied_total{reason="tenant_mismatch"}`, `authz_principal_tenant_distribution`
|
||||
- trace: 위반 request의 `traceId`로 호출 chain 확인. token claim의 `tenant_id`와 요청 path의 `tenant_id` 비교
|
||||
- 가능한 원인:
|
||||
- account takeover (계정 탈취) → 즉시 session revoke + 비밀번호 reset 요구
|
||||
- client bug (잘못된 tenant id 전송) → product team에 통보
|
||||
- 정상 admin operation 누락된 capability → entitlement 보정
|
||||
|
||||
## 4. Mitigation
|
||||
|
||||
- 단기: principal session revoke, source IP rate-limit 강화
|
||||
- 위반이 client bug면 client patch release 협조
|
||||
- 장기: tenant boundary 검증 layer를 controller가 아닌 repository 진입점에서 강제 ([[feature-repository-access-permission-contract]])
|
||||
|
||||
## 5. Escalation
|
||||
|
||||
- 다음 on-call로 page: 보안 incident channel 즉시 page. 5분 내 security on-call 응답 없으면 CISO escalation
|
||||
- legal/compliance 통보 필요 여부 판단 (개인정보 noted시)
|
||||
|
||||
## 6. Recovery / Verification
|
||||
|
||||
- 회복 확인 metric: `AUTHZ_TENANT_MISMATCH` 건수 정상 baseline 복귀
|
||||
- post-incident:
|
||||
- account takeover면 forensics 수행 + audit log 보존
|
||||
- cross-tenant 검증 unit test 추가
|
||||
- 위반 패턴 detection rule 영구화
|
||||
|
||||
## 7. Related
|
||||
|
||||
- error-codes.yaml rows: `AUTHZ_INSUFFICIENT_PERMISSION`, `AUTHZ_TENANT_MISMATCH`
|
||||
- metrics.yaml: `authz_denied_total`, `authz_principal_tenant_distribution`
|
||||
- 관련 branch: [[feature-tenant-context-policy]], [[feature-repository-access-permission-contract]]
|
||||
- 계정 탈취가 의심되면 보안 incident로 넘긴다.
|
||||
|
||||
---
|
||||
|
||||
|
||||
@@ -4,7 +4,7 @@ category: AUTHZ
|
||||
error_codes: [AUTHZ_TENANT_MISMATCH]
|
||||
severity: P1
|
||||
owner: oncall
|
||||
last_updated: 2026-11-07
|
||||
last_updated: 2026-11-13
|
||||
status: 초안
|
||||
---
|
||||
|
||||
@@ -12,14 +12,16 @@ status: 초안
|
||||
|
||||
## 증상
|
||||
|
||||
- HTTP 403, `error.code=AUTHZ_TENANT_MISMATCH`.
|
||||
- 템플릿은 이 코드를 내지 않는다. 다른 테넌트 접근을 판단하는 서비스가 낸다. 403 carrier는 로그 줄 없이
|
||||
응답하므로(`ServerFailureLog`), 이 runbook으로 시도를 찾으려면 그 서비스가 판단하는 자리에서
|
||||
`code=AUTHZ_TENANT_MISMATCH`를 남겨야 한다.
|
||||
- `AUTHZ_TENANT_MISMATCH`는 enum 상수와 registry 행이 있지만 템플릿 코드는 내지 않는다. 템플릿이 정한 규칙은 남의
|
||||
tenant 객체를 없는 것처럼 404로 답하는 것이다(`docs/manual/07-authorization.md` 「객체 단위 권한」, 실제 신호는
|
||||
`docs/runbooks/authz-cross-tenant-violation.md`).
|
||||
- 서비스가 다른 tenant 접근을 403 `AUTHZ_TENANT_MISMATCH`로 따로 답하기로 했을 때만 이 runbook을 쓴다. 403 carrier는
|
||||
로그 줄 없이 응답하므로(`ServerFailureLog`), 그 서비스가 판단하는 자리에서 `code=AUTHZ_TENANT_MISMATCH`를 남겨야
|
||||
찾을 수 있다.
|
||||
|
||||
## 진단
|
||||
|
||||
- `traceId`를 뽑고, 요청의 테넌트 헤더(서비스가 정한 이름, 예: `X-Tenant-Id`)와 토큰의 테넌트 클레임을 비교한다.
|
||||
- `trace_id`로 요청 흐름을 따라간다. tenant는 인증 정보에서만 온다. 요청이 tenant를 제안하면(`X-Tenant-Id` 등) 서비스가 web-advanced `WebSecurityContextBridge.resolve(authentication, requestInput)`을 부를 때 403 `TENANT_INPUT_UNTRUSTED`로 거부하고, 한 인자 `resolve`만 부르거나 부르지 않으면 무시한다. 그래서 비교할 「요청의 tenant」는 없다. 토큰·`Authorization` 헤더·JWT payload는 로그에 남지 않고 남겨서도 안 된다. 값을 봐야 하면 클라이언트 쪽에서 재현한다.
|
||||
- 클라이언트 설정 오류인지 의도한 공격인지 가린다.
|
||||
|
||||
## 조치
|
||||
|
||||
@@ -4,7 +4,7 @@ category: TRANSIENT_DEPENDENCY
|
||||
error_codes: [DB_UNAVAILABLE]
|
||||
severity: P1
|
||||
owner: oncall
|
||||
last_updated: 2026-06-15
|
||||
last_updated: 2026-11-13
|
||||
status: 초안
|
||||
---
|
||||
|
||||
@@ -13,7 +13,7 @@ status: 초안
|
||||
## 증상
|
||||
|
||||
- HTTP 503, `error.code=DB_UNAVAILABLE`.
|
||||
- 로그에 SQLState 08* 연결 오류가 있다.
|
||||
- ERROR 줄 `persistence failure classified as DB_UNAVAILABLE (category=TRANSIENT_DEPENDENCY, retryable=true)`(`ServerFailureLog`). 원인 사슬은 붙지 않아 SQLState·SQL은 로그에 없다. 연결 계열 SQLState(08*)와 PostgreSQL 종료 상태(57P01·57P02)가 이 코드로 분류된다(`PersistenceExceptionTranslator`, `PostgreSqlFailureClassifier`). 쓰기 트랜잭션의 commit 중에 같은 상태가 나면 적용됐는지 모르므로 이 코드가 아니라 `DB_COMPLETION_UNKNOWN`(재시도 금지)이다.
|
||||
|
||||
## 진단
|
||||
|
||||
|
||||
@@ -4,7 +4,7 @@ category: PERMANENT_DEPENDENCY
|
||||
error_codes: [DEPENDENCY_4XX_CLIENT]
|
||||
severity: P2
|
||||
owner: oncall
|
||||
last_updated: 2026-06-15
|
||||
last_updated: 2026-11-13
|
||||
status: 초안
|
||||
---
|
||||
|
||||
@@ -14,10 +14,12 @@ status: 초안
|
||||
|
||||
- HTTP 502, `error.code=DEPENDENCY_4XX_CLIENT`.
|
||||
- 업스트림이 401·403·400을 돌려줬다. 자격 증명, scope, 요청 형식 문제다.
|
||||
- 이 코드는 서비스 코드가 `DependencyFailureException`을 던질 때만 나온다. httpclient 예외는 코드를 싣지 않아 500 `INTERNAL_ERROR`다(`dependency-unavailable.md`).
|
||||
- ERROR 줄 `dependency failure classified as DEPENDENCY_4XX_CLIENT (category=PERMANENT_DEPENDENCY, retryable=false, dependency=<이름>)`(`ServerFailureLog`, 원인 사슬 포함).
|
||||
|
||||
## 진단
|
||||
|
||||
- 로그에서 업스트림 응답 본문의 오류 내용을 본다.
|
||||
- 업스트림 응답 본문은 로그에 남지 않는다(본문은 비밀·개인 정보를 실을 수 있어 남기지 않는다). 그 줄의 `dependency=`와, httpclient capability를 켠 서비스는 `http.client.requests`의 tag `clientName`·`status`로 어느 업스트림이 어떤 4xx를 돌려줬는지 본다. 본문은 업스트림 쪽 로그나 재현으로 본다.
|
||||
- API 자격 증명과 scope가 유효한지 확인한다.
|
||||
|
||||
## 조치
|
||||
|
||||
@@ -4,7 +4,7 @@ category: TRANSIENT_DEPENDENCY
|
||||
error_codes: [DEPENDENCY_5XX_SERVER]
|
||||
severity: P1
|
||||
owner: oncall
|
||||
last_updated: 2026-06-15
|
||||
last_updated: 2026-11-13
|
||||
status: 초안
|
||||
---
|
||||
|
||||
@@ -14,10 +14,12 @@ status: 초안
|
||||
|
||||
- HTTP 502, `error.code=DEPENDENCY_5XX_SERVER`.
|
||||
- 업스트림이 5xx를 돌려줬다. 서버 쪽 일시 장애다.
|
||||
- 이 코드는 서비스 코드가 `DependencyFailureException`을 던질 때만 나온다. httpclient 예외는 코드를 싣지 않아 500 `INTERNAL_ERROR`다(`dependency-unavailable.md`).
|
||||
- ERROR 줄 `dependency failure classified as DEPENDENCY_5XX_SERVER (category=TRANSIENT_DEPENDENCY, retryable=true, dependency=<이름>)`(`ServerFailureLog`, 원인 사슬 포함).
|
||||
|
||||
## 진단
|
||||
|
||||
- `dependency_name` 태그로 어느 업스트림이 실패하는지 본다.
|
||||
- 그 줄의 `dependency=`가 서비스가 붙인 업스트림 이름이다. httpclient capability를 켠 서비스는 `http.client.requests`의 tag `clientName`·`outcome`으로도 본다.
|
||||
- 업스트림 서비스의 상태 페이지를 본다.
|
||||
|
||||
## 조치
|
||||
|
||||
@@ -4,7 +4,7 @@ category: TRANSIENT_DEPENDENCY
|
||||
error_codes: [DEPENDENCY_CIRCUIT_OPEN]
|
||||
severity: P2
|
||||
owner: oncall
|
||||
last_updated: 2026-06-15
|
||||
last_updated: 2026-11-13
|
||||
status: 초안
|
||||
---
|
||||
|
||||
@@ -14,10 +14,12 @@ status: 초안
|
||||
|
||||
- HTTP 503, `error.code=DEPENDENCY_CIRCUIT_OPEN`.
|
||||
- 어떤 의존성의 circuit breaker(Resilience4j)가 OPEN 상태다.
|
||||
- 이 코드는 서비스 코드가 `DependencyFailureException`을 던질 때만 나온다. httpclient 예외는 코드를 싣지 않아 500 `INTERNAL_ERROR`다(`dependency-unavailable.md`).
|
||||
- ERROR 줄 `dependency failure classified as DEPENDENCY_CIRCUIT_OPEN (category=TRANSIENT_DEPENDENCY, retryable=true, dependency=<이름>)`(`ServerFailureLog`, 원인 사슬 포함).
|
||||
|
||||
## 진단
|
||||
|
||||
- 그 의존성의 Resilience4j circuit breaker 메트릭을 본다.
|
||||
- 그 줄의 `dependency=`가 서비스가 붙인 업스트림 이름이다. httpclient capability를 켠 서비스는 `http.client.circuit.state`(tag `clientName`, 1 = open)와 `http.client.circuit.state.rejected`(열려 거부한 호출)를 본다. Resilience4j 자체 지표(`resilience4j_*`)는 묶지 않았다.
|
||||
- 업스트림 상태를 확인한다. 실패가 임계를 넘으면 circuit이 열린다.
|
||||
|
||||
## 조치
|
||||
|
||||
@@ -4,7 +4,7 @@ category: TRANSIENT_DEPENDENCY
|
||||
error_codes: [DEPENDENCY_CONNECT_FAILED]
|
||||
severity: P1
|
||||
owner: oncall
|
||||
last_updated: 2026-06-15
|
||||
last_updated: 2026-11-13
|
||||
status: 초안
|
||||
---
|
||||
|
||||
@@ -14,10 +14,12 @@ status: 초안
|
||||
|
||||
- HTTP 503, `error.code=DEPENDENCY_CONNECT_FAILED`.
|
||||
- 업스트림으로 TCP 연결이 거부됐거나 네트워크에 닿지 않는다.
|
||||
- 이 코드는 서비스 코드가 `DependencyFailureException`을 던질 때만 나온다. httpclient 예외는 코드를 싣지 않아 500 `INTERNAL_ERROR`다(`dependency-unavailable.md`).
|
||||
- ERROR 줄 `dependency failure classified as DEPENDENCY_CONNECT_FAILED (category=TRANSIENT_DEPENDENCY, retryable=true, dependency=<이름>)`(`ServerFailureLog`, 원인 사슬 포함).
|
||||
|
||||
## 진단
|
||||
|
||||
- `dependency_name` 태그로 어느 업스트림에 닿지 않는지 본다.
|
||||
- 그 줄의 `dependency=`가 서비스가 붙인 업스트림 이름이다. httpclient capability를 켠 서비스는 `http.client.requests`의 tag `clientName`·`outcome`으로도 본다.
|
||||
- 네트워크 경로와 방화벽 규칙을 확인한다.
|
||||
|
||||
## 조치
|
||||
|
||||
@@ -4,7 +4,7 @@ category: TRANSIENT_DEPENDENCY
|
||||
error_codes: [DEPENDENCY_DNS_FAILED]
|
||||
severity: P1
|
||||
owner: oncall
|
||||
last_updated: 2026-06-15
|
||||
last_updated: 2026-11-13
|
||||
status: 초안
|
||||
---
|
||||
|
||||
@@ -14,10 +14,12 @@ status: 초안
|
||||
|
||||
- HTTP 503, `error.code=DEPENDENCY_DNS_FAILED`.
|
||||
- 업스트림 호스트 이름의 DNS 조회가 실패했다.
|
||||
- 이 코드는 서비스 코드가 `DependencyFailureException`을 던질 때만 나온다. httpclient 예외는 코드를 싣지 않아 500 `INTERNAL_ERROR`다(`dependency-unavailable.md`).
|
||||
- ERROR 줄 `dependency failure classified as DEPENDENCY_DNS_FAILED (category=TRANSIENT_DEPENDENCY, retryable=true, dependency=<이름>)`(`ServerFailureLog`, 원인 사슬 포함).
|
||||
|
||||
## 진단
|
||||
|
||||
- 앱 pod에서 DNS 조회를 시험한다: `nslookup <upstream-host>`
|
||||
- 그 줄의 `dependency=`로 어느 업스트림인지 본다. 앱 pod에서 DNS 조회를 시험한다: `nslookup <upstream-host>`
|
||||
- 클러스터 DNS(CoreDNS) 상태를 확인한다.
|
||||
|
||||
## 조치
|
||||
|
||||
@@ -4,7 +4,7 @@ category: TRANSIENT_DEPENDENCY
|
||||
error_codes: [DEPENDENCY_TIMEOUT]
|
||||
severity: P1
|
||||
owner: oncall
|
||||
last_updated: 2026-11-07
|
||||
last_updated: 2026-11-13
|
||||
status: 초안
|
||||
---
|
||||
|
||||
@@ -15,10 +15,12 @@ status: 초안
|
||||
- HTTP 504, `error.code=DEPENDENCY_TIMEOUT`.
|
||||
- 업스트림 서비스가 설정된 시간 안에 답하지 않았다. 호출 전체의 상한은 HTTP 클라이언트 profile의
|
||||
`timeout.total-call`이다(기본값은 `docs/httpclient/configuration-reference.md`).
|
||||
- 이 코드는 서비스 코드가 `DependencyFailureException`을 던질 때만 나온다. httpclient 예외는 코드를 싣지 않아 500 `INTERNAL_ERROR`다(`dependency-unavailable.md`).
|
||||
- ERROR 줄 `dependency failure classified as DEPENDENCY_TIMEOUT (category=TRANSIENT_DEPENDENCY, retryable=true, dependency=<이름>)`(`ServerFailureLog`, 원인 사슬 포함).
|
||||
|
||||
## 진단
|
||||
|
||||
- 로그의 `dependency_name`으로 어느 업스트림이 시간을 넘기는지 본다.
|
||||
- 그 줄의 `dependency=`가 서비스가 붙인 업스트림 이름이다. httpclient capability를 켠 서비스는 `http.client.requests`의 tag `clientName`·`outcome`으로도 본다. 시간 초과만 따로 보려면 `http.client.timeout`을 본다.
|
||||
- 업스트림 서비스의 지연 메트릭을 본다.
|
||||
|
||||
## 조치
|
||||
|
||||
@@ -1,80 +1,37 @@
|
||||
---
|
||||
title: Runbook — 외부 의존성 unavailable
|
||||
category: TRANSIENT_DEPENDENCY
|
||||
error_codes: [DEPENDENCY_TIMEOUT, DEPENDENCY_CONNECT_FAILED, DEPENDENCY_DNS_FAILED, DEPENDENCY_CIRCUIT_OPEN, DEPENDENCY_5XX_SERVER, CACHE_UNAVAILABLE, DB_UNAVAILABLE]
|
||||
error_codes: [DEPENDENCY_TIMEOUT, DEPENDENCY_CONNECT_FAILED, DEPENDENCY_DNS_FAILED, DEPENDENCY_CIRCUIT_OPEN, DEPENDENCY_5XX_SERVER, DB_UNAVAILABLE]
|
||||
severity: P1
|
||||
owner: oncall
|
||||
last_updated: 2026-05-22
|
||||
last_updated: 2026-11-13
|
||||
status: 초안
|
||||
---
|
||||
|
||||
# Runbook: 외부 의존성 unavailable
|
||||
|
||||
## 1. Trigger
|
||||
## 증상
|
||||
|
||||
이 runbook은 다음 alert가 울리면 쓴다.
|
||||
- DB: 503 `DB_UNAVAILABLE`과 ERROR 줄 `persistence failure classified as DB_UNAVAILABLE (category=TRANSIENT_DEPENDENCY, retryable=true)`(`ServerFailureLog`, 원인 사슬은 붙지 않는다).
|
||||
- outbound HTTP: 지금 httpclient 예외는 코드를 싣지 않아 500 `INTERNAL_ERROR`와 ERROR 줄 `unhandled exception on …`이 된다. registry의 `DEPENDENCY_*` 코드는 `DependencyFailureException`을 던지는 서비스 코드에서만 나오고, ERROR 줄 `dependency failure classified as DEPENDENCY_… (category=TRANSIENT_DEPENDENCY, retryable=…, dependency=<이름>)`을 남긴다.
|
||||
- Redis: `CACHE_UNAVAILABLE` 코드는 없다. cache 읽기가 실패하면 원천에서 읽고 HTTP 오류는 없다. WARN 줄 `Redis semantic operation degraded; capability=… operation=… failureType=…`(`RedisSemanticFailureLogger`)이 남는다. cache만이 아니라 idempotency·rate-limit·lease도 같은 줄을 낸다. 같은 capability·operation·failureType은 1분에 한 번만 WARN이고 나머지는 DEBUG라, 경보는 건수가 아니라 그 줄이 나왔는지로 건다.
|
||||
- 이 템플릿은 경보 규칙·대시보드를 두지 않는다. 서비스가 위 줄의 고정 문구(`persistence failure classified as`, `dependency failure classified as`, `unhandled exception on`, `Redis semantic operation degraded`)와 `http.server.requests`(tag `status`, `uri`)로 만든다. 업스트림 이름은 `dependency=` 값뿐이다. 위 줄들에는 `dependency_name` 칸이 없다.
|
||||
|
||||
- alert name: `dependency_error_rate_critical` 또는 `circuit_breaker_open`
|
||||
- alert payload 필수 field: `operation`, `error.code`, `error.category`, `dependency_name`, `dependency_kind`(required|optional), `runbook_link`
|
||||
- 임계:
|
||||
- P1: required dependency의 error rate > 50% 1분 OR circuit_open state 활성
|
||||
- P2: optional dependency degraded (fail-open으로 동작 중)
|
||||
## 진단
|
||||
|
||||
## 2. First Response (5분 이내)
|
||||
- outbound HTTP 지표(httpclient capability를 켠 서비스): `http.client.requests`(tag `clientName`, `outcome`=`success`|`failure`), `http.client.retry.count`, `http.client.retry.exhausted`, `http.client.circuit.state`(1=open), `http.client.circuit.state.rejected`(`docs/registries/metrics.yaml`). Resilience4j 자체 지표(`resilience4j_*`)는 묶지 않았다.
|
||||
- DB 풀: `hikaricp.connections.active`·`hikaricp.connections.pending`·`hikaricp.connections.timeout`(persistence-jpa를 켠 서비스).
|
||||
- readiness는 DB와 required Redis만 본다. outbound HTTP 의존은 readiness에 들지 않는다.
|
||||
|
||||
### Step 1 — 확인
|
||||
1. `dependency_name` 별 status page 확인 (외부 SaaS면 vendor status, internal이면 해당 service dashboard)
|
||||
2. log query로 실패 패턴 확인: timeout / connect / DNS / 5xx 중 어떤 모드인지
|
||||
3. runtime-health Dependency Matrix에서 required vs optional 분류 확인
|
||||
4. circuit breaker state 확인 (Resilience4j metric)
|
||||
## 조치
|
||||
|
||||
### Step 2 — 임시 격리
|
||||
- required dep이면 readiness probe로 traffic 차단 (회복 대기) — cascade failure 방지
|
||||
- optional dep이면 fail-open with degraded mode 확인. degraded banner를 client에 노출
|
||||
- DNS failure면 resolver/coredns 상태 확인. cache 강제 flush 검토
|
||||
- DB·required Redis 장애면 readiness가 트래픽을 뺀다. 회복을 기다린다.
|
||||
- outbound 의존 장애면 그 클라이언트의 timeout·retry·circuit 설정(`docs/httpclient/`)을 본다. circuit을 손으로 되돌리는 actuator는 없다(`circuitbreakerevents`는 노출하지 않는다).
|
||||
- 풀이 고갈되면 풀 크기와 오래 쥔 트랜잭션을 본다.
|
||||
|
||||
## 3. Diagnosis
|
||||
## 에스컬레이션
|
||||
|
||||
- log query: `{service="app"} | dependency_name="<name>" | stats count by error.code`
|
||||
- metric panel:
|
||||
- `resilience4j_circuitbreaker_state{name="<name>"}`
|
||||
- `resilience4j_retry_calls_total{kind="failed_without_retry"}`
|
||||
- `hikaricp_connections_active`, `hikaricp_connections_pending` (DB_UNAVAILABLE)
|
||||
- `http_client_requests_seconds_count{outcome="SERVER_ERROR"}`
|
||||
- trace: 실패 request의 outbound span에서 timeout/connect/DNS 분류, target endpoint 확인
|
||||
- 가능한 원인:
|
||||
- vendor outage → status page 확인, 회복 대기
|
||||
- 네트워크 문제 (DNS, security group, NAT) → infra team 확인
|
||||
- connection pool 고갈 (Hikari) → pool size/timeout 점검
|
||||
- circuit breaker open 후 half-open 전환 실패 → 수동 reset 검토
|
||||
- retry-storm으로 인한 self-DoS → retry budget 축소
|
||||
|
||||
## 4. Mitigation
|
||||
|
||||
- 단기: required면 회복 대기 + traffic 차단, optional이면 degraded mode로 유지
|
||||
- pool 고갈이면 일시 pool size 상향 + leak detection 활성화
|
||||
- circuit이 stuck이면 수동 reset (`actuator/circuitbreakerevents`)
|
||||
- 장기: retry budget·timeout·circuit 임계 재조정, fallback path 보강, vendor SLA 재협상
|
||||
|
||||
## 5. Escalation
|
||||
|
||||
- 다음 on-call로 page: required dep 5분 내 회복 안 되면 외부 dep team 또는 vendor에 page
|
||||
- 다중 dep 동시 장애면 incident commander 호출 (네트워크 전반 문제 의심)
|
||||
|
||||
## 6. Recovery / Verification
|
||||
|
||||
- 회복 확인 metric: dependency error rate < 1% 5분 지속, circuit_breaker_state = CLOSED, pool utilization 정상
|
||||
- post-incident:
|
||||
- vendor postmortem 요청 (외부 SaaS면)
|
||||
- timeout/retry/circuit 설정 재검토
|
||||
- degraded mode가 사용자 경험에 미친 영향 측정
|
||||
- chaos test에 해당 시나리오 추가
|
||||
|
||||
## 7. Related
|
||||
|
||||
- error-codes.yaml rows: `DEPENDENCY_TIMEOUT`, `DEPENDENCY_CONNECT_FAILED`, `DEPENDENCY_DNS_FAILED`, `DEPENDENCY_CIRCUIT_OPEN`, `DEPENDENCY_5XX_SERVER`, `CACHE_UNAVAILABLE`, `DB_UNAVAILABLE`
|
||||
- metrics.yaml: `resilience4j_circuitbreaker_state`, `hikaricp_connections_active`, `http_client_requests_seconds_count`
|
||||
- 관련 branch: [[feature-outbound-http-client-baseline]], [[feature-persistence-failure-baseline]]
|
||||
- required 의존이 5분 안에 돌아오지 않으면 그 의존의 담당이나 vendor에 넘긴다.
|
||||
|
||||
---
|
||||
|
||||
|
||||
@@ -4,7 +4,7 @@ category: TRANSIENT_DEPENDENCY
|
||||
error_codes: [IDEMPOTENCY_UNAVAILABLE, IDEMPOTENCY_COMPLETION_UNKNOWN, IDEMPOTENCY_RECOVERY_REQUIRED]
|
||||
severity: P2
|
||||
owner: oncall
|
||||
last_updated: 2026-11-07
|
||||
last_updated: 2026-11-13
|
||||
status: 운영
|
||||
---
|
||||
|
||||
@@ -114,7 +114,7 @@ status: 운영
|
||||
- Redis: 확인과 삭제를 한 단계로, 서비스에 등록된 스크립트가 도는 계정으로 한다
|
||||
(`APP_REDIS_AUTHENTICATION_ADVANCED_CREDENTIAL_REFERENCE`, 비어 있으면 애플리케이션 계정). `HMGET`으로
|
||||
확인하고 `DEL`을 보내면 명령이 둘이다. 그 사이에 만료되어 새 요청이 다시 claim한 기록은 그 요청이 도는
|
||||
동안 지워지고, 그 키의 다음 요청이 일을 한 번 더 한다(2026-11-04 재확인 리뷰 RR4-03-02). 아래 프로그램은
|
||||
동안 지워지고, 그 키의 다음 요청이 일을 한 번 더 한다. 아래 프로그램은
|
||||
`state`가 `ABANDONED`일 때만 키를 지운다. 애플리케이션 계정은 `EVAL`이 막혀 있으므로
|
||||
(`compose/redis/acl/README.md`), 서비스가 자기 스크립트를 돌리는 것처럼 불러 올리고 `SCRIPT LOAD`가 찍은
|
||||
digest로 돌린다.
|
||||
|
||||
@@ -4,7 +4,7 @@ category: INTERNAL
|
||||
error_codes: [INTERNAL_ERROR, INTERNAL_AUTH_MISCONFIGURATION, JVM_OOM]
|
||||
severity: P1
|
||||
owner: oncall
|
||||
last_updated: 2026-05-22
|
||||
last_updated: 2026-11-13
|
||||
status: 초안
|
||||
---
|
||||
|
||||
@@ -12,10 +12,9 @@ status: 초안
|
||||
|
||||
## 1. Trigger
|
||||
|
||||
이 runbook은 다음 alert가 울리면 쓴다.
|
||||
이 runbook은 아래 신호로 서비스가 만든 경보가 울리면 쓴다. 이 템플릿은 경보 규칙을 두지 않는다. 경보 이름과 싣는 값은 서비스가 정한다.
|
||||
|
||||
- alert name: `http_5xx_error_rate_critical`
|
||||
- alert payload 필수 field: `operation`, `error.code`, `error.category`, `request_id`, `traceId`, `runbook_link`
|
||||
- 경보에 실을 만한 값: MDC `request_id`·`trace_id`, ERROR 줄의 고정 문구(`unhandled exception on <경로>`, `failure classified as <code> (category=…, retryable=…)`), `http.server.requests`의 `status`. 5xx 줄에는 `error.code`·`error.category` 구조화 칸이 없고 코드는 메시지 글자로만 남는다(`ServerFailureLog`)
|
||||
- 임계: 5xx error rate > 5% 5분 지속 OR > 10% 1분
|
||||
|
||||
## 2. First Response (5분 이내)
|
||||
@@ -23,8 +22,8 @@ status: 초안
|
||||
### Step 1 — 확인
|
||||
1. 가장 최근 deploy 시각 확인 (CI/CD dashboard, artifact registry digest)
|
||||
2. JVM metric 확인: heap usage, GC pause, CPU, thread count
|
||||
3. log에서 실패 request 1건 추출 → `request_id`, `traceId` 확보
|
||||
4. error.code 분포 확인: `INTERNAL_ERROR` vs `JVM_OOM` vs `INTERNAL_AUTH_MISCONFIGURATION`
|
||||
3. log에서 실패 request 1건 추출 → `request_id`, `trace_id` 확보
|
||||
4. 실패 종류 가르기: ERROR 줄 고정 문구 `unhandled exception on`(분류 안 된 실패, `INTERNAL_ERROR`) vs `failure classified as <code>`(분류된 5xx) vs `security failure: code=INTERNAL_AUTH_MISCONFIGURATION`. OOM은 로그 코드가 아니라 `runtime-jvm-oom.md`의 신호로 본다
|
||||
|
||||
### Step 2 — 임시 격리
|
||||
- 직전 deploy가 의심되면 즉시 rollback (artifact registry에서 직전 image digest pin)
|
||||
@@ -33,14 +32,14 @@ status: 초안
|
||||
|
||||
## 3. Diagnosis
|
||||
|
||||
- log query: `{service="app"} | http.status>=500 | stats count by error.code`
|
||||
- log query: ERROR 줄을 위 고정 문구별로 센다(예: `{service="app"} |= "unhandled exception on"`). 로그에는 `http.status`·`error.code` 칸이 없다
|
||||
- metric panel: `jvm_memory_used_bytes{area="heap"}`, `jvm_gc_pause_seconds`, `process_cpu_seconds_total`, `http_server_requests_seconds_count{status=~"5.."}`
|
||||
- trace: 실패 request의 `traceId`로 span chain 확인 → stack trace에서 root exception 추출
|
||||
- trace: 실패 request의 `trace_id`로 span chain 확인 → stack trace에서 root exception 추출
|
||||
- heap dump 위치: `/var/tmp/heap/java_pid<pid>.hprof`(`-XX:HeapDumpPath=/var/tmp/heap`). 그 경로에 디스크 볼륨을 붙인 배포에만 남는다. 읽는 법은 `docs/runbooks/runtime-jvm-oom.md` 「진단」
|
||||
- 가능한 원인:
|
||||
- 직전 deploy의 회귀 버그 → rollback
|
||||
- JVM OOM (메모리 leak 또는 부하 증가) → heap dump 분석
|
||||
- 외부 의존성 설정 오류 (`INTERNAL_AUTH_MISCONFIGURATION`) → config secret 확인
|
||||
- JVM OOM (메모리 leak 또는 부하 증가) → heap dump 분석(`runtime-jvm-oom.md`)
|
||||
- JWT decoder 설정 오류 (`INTERNAL_AUTH_MISCONFIGURATION`) → issuer 설정과 discovery(`auth-public-path-misconfiguration.md`)
|
||||
- thread starvation (pool 고갈) → thread dump (`jstack <pid>`)
|
||||
|
||||
## 4. Mitigation
|
||||
|
||||
@@ -4,7 +4,7 @@ category: INTERNAL
|
||||
error_codes: [JOB_DEAD_LETTER]
|
||||
severity: P1
|
||||
owner: oncall
|
||||
last_updated: 2026-06-13
|
||||
last_updated: 2026-11-13
|
||||
status: 초안
|
||||
---
|
||||
|
||||
@@ -12,10 +12,12 @@ status: 초안
|
||||
|
||||
## 1. Trigger
|
||||
|
||||
이 runbook은 다음 alert가 울리면 쓴다.
|
||||
`JOB_DEAD_LETTER`는 enum 상수와 registry 행이 있지만 템플릿 코드는 내지 않는다. 템플릿에는 job 재시도·DLQ 실행기가 없다.
|
||||
`job.dlq.total`·`job.retry.total`도 서비스가 `BackgroundJobMetrics.recordDeadLetter`·`recordRetryOutcome`을 부를 때만
|
||||
생긴다(meter는 처음 셀 때 등록된다). 그래서 이 runbook은 서비스가 job 재시도·DLQ를 붙이고 아래 줄과 지표를 낼 때만
|
||||
쓴다. 그 전에는 이 신호로 만든 경보가 울리지 않는다. 이 템플릿은 경보 규칙을 두지 않는다.
|
||||
|
||||
- alert name: `job_dead_letter`
|
||||
- alert payload 필수 field: `error.code=JOB_DEAD_LETTER`, `job_name`, `correlation_id`, `runbook_link`
|
||||
- 서비스가 낼 때 경보에 실을 만한 값: `error.code=JOB_DEAD_LETTER`, `job_name`, `correlation_id`
|
||||
- 임계: `job.dlq.total` > 0 for 5m (p1) — retry 소진 후 DLQ 진입은 자동 회복이 없으므로 점검 대상
|
||||
|
||||
## 2. First Response (5분 이내)
|
||||
@@ -26,7 +28,7 @@ status: 초안
|
||||
3. DLQ 적재 위치(향후 retry carrier 확정 시 DB 테이블/큐) 확인 — 현재 skeleton은 vocabulary 단계
|
||||
|
||||
### Step 2 — 임시 격리
|
||||
- DLQ는 max attempts(3) 소진의 최종 상태 — 자동 재시도 없음, 수동 개입 필수
|
||||
- DLQ는 서비스가 정한 최대 시도를 다 쓴 최종 상태 — 자동 재시도 없음, 수동 개입 필수
|
||||
- 비즈니스 크리티컬 job이면 §4의 수동 처분(재처리 또는 폐기)을 우선 수행
|
||||
|
||||
## 3. Diagnosis
|
||||
@@ -40,7 +42,7 @@ status: 초안
|
||||
|
||||
## 4. Mitigation (수동 처분 — 둘 중 하나)
|
||||
|
||||
- **재처리 (기본)**: 원인 해소 후 해당 job을 다시 enqueue. 소비자는 멱등(idempotencyKey dedupe) 의무가 있으므로 중복 처리 안전
|
||||
- **재처리 (기본)**: 원인 해소 후 해당 job을 다시 enqueue. 다시 넣어도 안전한지는 그 job이 멱등한지(서비스가 정한 dedupe key)에 달렸다. 멱등이 아니면 먼저 부작용이 이미 났는지 확인한다
|
||||
- **폐기 (영구)**: 작업이 더 이상 유효하지 않으면 DLQ에서 제거. ⚠ 비즈니스 오너 승인 후에만 수행하고 incident 기록에 남김
|
||||
- 장기: poison input 재발 방지(입력 계약 테스트 보강), non-transient error는 retry 없이 즉시 DLQ로 분류
|
||||
|
||||
|
||||
@@ -4,7 +4,7 @@ category: TRANSIENT_DEPENDENCY
|
||||
error_codes: [JOB_EXECUTOR_REJECTED]
|
||||
severity: P1
|
||||
owner: oncall
|
||||
last_updated: 2026-06-13
|
||||
last_updated: 2026-11-13
|
||||
status: 초안
|
||||
---
|
||||
|
||||
@@ -12,10 +12,9 @@ status: 초안
|
||||
|
||||
## 1. Trigger
|
||||
|
||||
이 runbook은 다음 alert가 울리면 쓴다.
|
||||
이 runbook은 아래 신호로 서비스가 만든 경보가 울리면 쓴다. 이 템플릿은 경보 규칙을 두지 않는다. 경보 이름과 싣는 값은 서비스가 정한다.
|
||||
|
||||
- alert name: `executor_rejected`
|
||||
- alert payload 필수 field: `error.code=JOB_EXECUTOR_REJECTED`, `executor_name`, `policy`, `runbook_link`
|
||||
- 경보에 실을 만한 값: `error.code=JOB_EXECUTOR_REJECTED`, `executor_name`, `policy`
|
||||
- 임계: `executor.rejected.total` > 0 for 1m (p1) — bounded pool이 saturation으로 task를 거부
|
||||
- 보조 신호: `executor.saturation` gauge > queue capacity의 80% for 5m (p2)
|
||||
|
||||
|
||||
@@ -4,7 +4,7 @@ category: TRANSIENT_DEPENDENCY
|
||||
error_codes: [JOB_TIMEOUT]
|
||||
severity: P2
|
||||
owner: oncall
|
||||
last_updated: 2026-11-03
|
||||
last_updated: 2026-11-13
|
||||
status: 초안
|
||||
---
|
||||
|
||||
@@ -12,12 +12,15 @@ status: 초안
|
||||
|
||||
## 1. Trigger
|
||||
|
||||
이 runbook은 다음 alert가 울리면 쓴다.
|
||||
`JOB_TIMEOUT`은 enum 상수와 registry 행이 있지만 템플릿 코드는 내지 않는다. `job.retry.total`도 서비스가
|
||||
`BackgroundJobMetrics.recordRetryOutcome`을 부를 때만 생긴다. 그래서 이 runbook의 코드·지표 신호는 서비스가 job
|
||||
시간 상한·재시도를 붙여 낼 때만 있다. 이 템플릿은 경보 규칙을 두지 않는다.
|
||||
|
||||
- alert name: `job_timeout`
|
||||
- alert payload 필수 field: `error.code=JOB_TIMEOUT`, `job_name`, `correlation_id`, `runbook_link`
|
||||
- 임계: `job.retry.total{outcome=RETRY}` 급증 또는 graceful-shutdown 중 in-flight job interrupt 발생
|
||||
- 연관: shutdown phase에서 19s await 초과로 interrupt된 job (D8)
|
||||
- 템플릿이 내는 신호는 종료 때 하나다: async executor가 남은 작업을 19s 기다리고도 끝나지 않으면 Spring이 WARN 줄
|
||||
`Timed out while waiting for executor '<bean 이름>' to terminate`를 남긴다
|
||||
(`AsyncExecutorConfig.AWAIT_TERMINATION_SECONDS`). 남은 작업은 JVM이 끝날 때 함께 끊긴다.
|
||||
- 서비스가 낼 때 경보에 실을 만한 값: `error.code=JOB_TIMEOUT`, `job_name`, `correlation_id`
|
||||
- 임계: `job.retry.total{outcome=RETRY}` 급증
|
||||
|
||||
## 2. First Response (10분 이내)
|
||||
|
||||
|
||||
@@ -4,7 +4,7 @@ category: AUTHZ
|
||||
error_codes: [ACTUATOR_FORBIDDEN]
|
||||
severity: P2
|
||||
owner: oncall
|
||||
last_updated: 2026-11-07
|
||||
last_updated: 2026-11-13
|
||||
status: 초안
|
||||
---
|
||||
|
||||
@@ -12,24 +12,24 @@ status: 초안
|
||||
|
||||
## 증상
|
||||
|
||||
- HTTP 403, `error.code=ACTUATOR_FORBIDDEN`.
|
||||
- 제한된 actuator 엔드포인트(env·configprops·heapdump·shutdown)에 접근하려 했다.
|
||||
- `ACTUATOR_FORBIDDEN`은 enum 상수(`OperationalError`)와 registry 행(`docs/registries/error-codes.yaml`)이 있지만 내는 코드가 없다.
|
||||
- 실제 신호: 노출한 actuator(`health`·`info`·`prometheus`) 밖의 경로(env·configprops·heapdump·threaddump·shutdown·loggers)는 actuator chain이 잡지 않아 메인 보안 chain으로 간다. token이 없으면 401 `AUTH_TOKEN_MISSING`(Envelope, `WWW-Authenticate: Bearer`)과 WARN 줄 `security failure: code=AUTH_TOKEN_MISSING category=AUTH method=… path=/actuator/…`(logger `AuthErrorResponseWriter`)이다. 인증된 호출자는 mapping이 없어 404다(`config/observability.yml`의 `management.endpoints.web.exposure`).
|
||||
- 서비스가 노출 목록을 넓혀 `health`·`info`·`prometheus` 밖의 endpoint를 더하면, 그 endpoint는 actuator chain이 잡고 본문 없는 401로 답한다. 그 chain에는 인증 수단이 없다(`ManagementSecurityConfig`). 이 401과 인증된 호출자의 404는 보안 로그 줄을 남기지 않는다.
|
||||
|
||||
## 진단
|
||||
|
||||
- 어느 actuator 엔드포인트에 접근했는지 찾는다.
|
||||
- 호출자가 누구인지(내부 도구인지 외부인지) 확인한다.
|
||||
- 관리 포트 노출은 포트로 가른다. 클러스터 밖에서 `curl -s -o /dev/null -w '%{http_code}' http://<host>:9001/actuator/health`가 200이면 관리 포트(`MANAGEMENT_SERVER_PORT`, 기본 9001, bind 주소 `MANAGEMENT_SERVER_ADDRESS`, 기본 `127.0.0.1`)가 클러스터 밖에 노출된 것이다. kubelet·Prometheus가 pod IP로 읽도록 `0.0.0.0`에 묶은 배포에서 클러스터 안의 200은 정상이다. 401·404만으로는 가를 수 없다: actuator가 없는 메인 포트의 `/actuator/env`도 메인 chain이 같은 401·WARN 줄·404로 답한다.
|
||||
- 앱 로그에서 `path=/actuator`가 든 `security failure` 줄을 찾는다(token 없는 시도). 그 줄에는 포트가 없다. 인증된 호출자의 404는 보안 로그 줄이 없다. 앞단 프록시·ingress 접근 로그로 어느 포트를 누가 불렀는지 찾는다.
|
||||
|
||||
## 조치
|
||||
|
||||
- management 포트가 밖으로 노출되지 않았는지 확인한다.
|
||||
- heapdump·threaddump는 노출 목록에서 빠져 있다(`config/observability.yml`의
|
||||
`management.endpoints.web.exposure.exclude`). 꼭 필요하면 운영 조직의 break-glass 절차를 따른다. 이 저장소에는
|
||||
그 절차 문서가 없다.
|
||||
- 관리 포트를 클러스터 밖으로 열지 않는다. kubelet 프로브와 Prometheus는 pod IP로 붙으므로 둘 중 하나를 고른다(`src/bootstrap/service-runtime/README.md` 「ManagementSecurityConfig」): `MANAGEMENT_SERVER_ADDRESS`를 `0.0.0.0`으로 두고 NetworkPolicy로 클러스터 안의 그 둘만 들이거나, 같은 pod의 sidecar가 loopback으로 읽는다. 기본값(loopback) 그대로면 liveness가 실패한다.
|
||||
- heapdump·threaddump는 노출 목록에서 빠져 있다. 꼭 필요하면 운영 조직의 break-glass 절차를 따른다. 이 저장소에는 그 절차 문서가 없다.
|
||||
|
||||
## 에스컬레이션
|
||||
|
||||
- 금지된 actuator 접근이 외부 공격으로 보이면 P1.
|
||||
- 관리 포트가 밖에 열려 있고(위 `curl`이 200) 외부에서 actuator를 두드린 흔적이 있으면 P1. 메인 포트의 `/actuator/…` 시도만 있으면 보통 스캐너다.
|
||||
|
||||
|
||||
---
|
||||
|
||||
|
||||
@@ -4,7 +4,7 @@ category: INTERNAL
|
||||
error_codes: [OUTBOX_DEAD_LETTER]
|
||||
severity: P1
|
||||
owner: oncall
|
||||
last_updated: 2026-11-04
|
||||
last_updated: 2026-11-13
|
||||
status: 초안
|
||||
---
|
||||
|
||||
@@ -12,14 +12,12 @@ status: 초안
|
||||
|
||||
## 1. Trigger
|
||||
|
||||
이 runbook은 다음 alert가 울리면 쓴다.
|
||||
이 runbook은 아래 신호로 서비스가 만든 경보가 울리면 쓴다. 이 템플릿은 경보 규칙을 두지 않는다. 경보 이름과 싣는 값은 서비스가 정한다.
|
||||
|
||||
- alert name: `outbox_dead_letter`
|
||||
- alert payload 필수 field: `error.code=OUTBOX_DEAD_LETTER`, `event_type`, `event_id`, `correlation_id`, `runbook_link`
|
||||
- 경보에 실을 만한 값: `error.code=OUTBOX_DEAD_LETTER`, `event_type`, `event_id`, `correlation_id`
|
||||
- 임계: `outbox.publisher.published.total{outcome=DEAD}` > 0 또는 `outbox.pending.size{status=DEAD}` > 0 (DEAD 전이는
|
||||
자동 회복이 없으므로 단건도 점검 대상). 두 번째 조건이 필요한 이유: claim이 행을 DEAD로 옮기는 경우
|
||||
(`ATTEMPT_COUNTERS_INCONSISTENT`, `UNREADABLE_ROW`)는 relay 결과를 거치지 않아 첫 번째 카운터가 오르지 않는다
|
||||
(재리뷰 2026-11-03 2차 RR-02-12)
|
||||
(`ATTEMPT_COUNTERS_INCONSISTENT`, `UNREADABLE_ROW`)는 relay 결과를 거치지 않아 첫 번째 카운터가 오르지 않는다.
|
||||
|
||||
## 2. First Response (5분 이내)
|
||||
|
||||
@@ -53,8 +51,7 @@ status: 초안
|
||||
|
||||
**재발행 (기본)**: 원인 해소 후 해당 row를 다시 claim 가능 상태로 되돌린다. 시도 횟수 두 개
|
||||
(`attempt_count`, `deferred_attempt_count`)를 함께 0으로 되돌린다. `attempt_count`만 되돌리면 다음 claim에서
|
||||
미룬 claim 수가 전체 claim 수보다 많아지고, claim은 그 행을 읽지 않고 다시 DEAD로 옮긴다(재리뷰 2026-11-03
|
||||
RR-05-01).
|
||||
미룬 claim 수가 전체 claim 수보다 많아지고, claim은 그 행을 읽지 않고 다시 DEAD로 옮긴다.
|
||||
|
||||
<!-- runbook-sql: dead-redrive-one -->
|
||||
```sql
|
||||
@@ -109,8 +106,8 @@ UPDATE outbox_event SET status = 'PUBLISHED' WHERE event_id = '<id>' AND status
|
||||
V21(`V21__outbox_aggregate_sequence.sql`)은 `outbox_event`의 순서 키
|
||||
`(tenant_scope, aggregate_type, aggregate_id, aggregate_sequence, event_index)`에 유일 인덱스
|
||||
`ux_outbox_event_aggregate_order`를 만든다. 같은 키를 가진 행이 이미 둘 이상 있으면 인덱스 생성이
|
||||
실패하고 기동이 멈춘다(`MIGRATION_FAILED`, exit 70). 이 실패는 의도한 동작이다(리뷰 2026-11-01
|
||||
README 15절 결정). 같은 키의 행들은 claim gate가 순서를 정하지 못한 행이다. 그냥 넘기면 순서 위반이
|
||||
실패하고 기동이 멈춘다(`MIGRATION_FAILED`, exit 70). 이 실패는 의도한 동작이다(소유자
|
||||
결정). 같은 키의 행들은 claim gate가 순서를 정하지 못한 행이다. 그냥 넘기면 순서 위반이
|
||||
숨는다. V21은 transaction 하나로 적용되므로, 실패하면 V21 전체가 롤백되고 V20 상태로 남는다.
|
||||
|
||||
V21이 하는 일은 세 가지 더 있다.
|
||||
@@ -118,14 +115,14 @@ V21이 하는 일은 세 가지 더 있다.
|
||||
- **floor 기록.** `outbox_aggregate_sequence_floor`에 V21 적용 시각(epoch 마이크로초)을 한 번 쓴다. 새로
|
||||
생기는 aggregate counter는 이 값과 남은 행의 최대 번호 중 큰 값 다음에서 시작한다. 그래서 reaper가
|
||||
행을 지운 aggregate, tenant scope가 바뀐 aggregate도 소비자가 이미 받은 벽시계 번호(약 1.7×10¹⁵)보다
|
||||
작은 번호를 받지 않는다(리뷰 RR-03-02). 벽시계 번호를 쓴 적 없는 서비스도 첫 번호가 floor + 1이다.
|
||||
작은 번호를 받지 않는다. 벽시계 번호를 쓴 적 없는 서비스도 첫 번호가 floor + 1이다.
|
||||
- **counter 미리 만들기.** 남은 행이 있는 aggregate의 counter를 그 최대 번호로 만든다.
|
||||
- **잠금 대기 5초.** 유일 인덱스는 만드는 동안 `outbox_event`에 SHARE 잠금을 건다. 그동안 outbox를 쓰는
|
||||
업무 쓰기가 모두 멈춘다. V21은 `lock_timeout = 5s`로 잠금을 기다린다. 열린 outbox 쓰기 트랜잭션 때문에
|
||||
5초 안에 못 잡으면 V21이 실패하고 V20에 남는다(`MIGRATION_FAILED`). 덜 바쁜 시각에 다시 배포하거나
|
||||
Step 0으로 인덱스를 먼저 만든다.
|
||||
|
||||
V20(`deferred_attempt_count`)과 V22(`last_failure_code`)도 같은 상한을 둔다(재리뷰 2026-11-03 2차 RR-02-09).
|
||||
V20(`deferred_attempt_count`)과 V22(`last_failure_code`)도 같은 상한을 둔다.
|
||||
둘 다 `ALTER TABLE outbox_event`라 가장 강한 잠금(ACCESS EXCLUSIVE)을 건다. 이 잠금은 읽기와도 충돌하므로,
|
||||
`outbox_event`를 읽기만 한 트랜잭션 하나(운영자가 `BEGIN` 안에서 조회하고 둔 psql 세션 포함)가 열려 있어도
|
||||
기다린다. 5초 안에 못 잡으면 그 마이그레이션이 실패·롤백되고 DB는 한 버전 아래(V19 또는 V21)에 남으며 새 버전은
|
||||
@@ -147,8 +144,8 @@ rolling 배포 중 아직 옛 버전인 인스턴스가 벽시계 번호로 쓴
|
||||
|
||||
이 "그 행 뒤에"는 **같은 aggregate identity**의 행에만 성립한다. tenant scope를 바꾸는 배포에서는 옛 버전이
|
||||
옛 scope로, 새 버전이 새 scope로 쓴다. 새 버전의 counter는 옛 scope 행을 보지 못하므로 floor + 1부터 시작하고,
|
||||
rolling 중 옛 버전이 방금 쓴 번호(floor보다 초당 10⁶씩 큰 벽시계 번호)보다 **작은** 번호를 준다(재리뷰
|
||||
2026-11-03 2차 RR-02-10, 실 PG 확인). scope를 무시하고 aggregate id로 "마지막 번호보다 작으면 버린다"를 구현한
|
||||
rolling 중 옛 버전이 방금 쓴 번호(floor보다 초당 10⁶씩 큰 벽시계 번호)보다 **작은** 번호를 준다(실
|
||||
PostgreSQL에서 확인). scope를 무시하고 aggregate id로 "마지막 번호보다 작으면 버린다"를 구현한
|
||||
소비자는 그 사이 새 이벤트를 버린다. 그래서 **tenant scope를 바꾸는 배포는 rolling으로 하지 않는다**: 옛 버전
|
||||
인스턴스를 모두 멈춘 뒤(옛·새 버전이 함께 쓰는 구간 없이) 새 버전을 띄운다.
|
||||
|
||||
|
||||
@@ -4,7 +4,7 @@ category: TRANSIENT_DEPENDENCY
|
||||
error_codes: [OUTBOX_PUBLISH_FAILED]
|
||||
severity: P2
|
||||
owner: oncall
|
||||
last_updated: 2026-11-04
|
||||
last_updated: 2026-11-13
|
||||
status: 초안
|
||||
---
|
||||
|
||||
@@ -12,10 +12,9 @@ status: 초안
|
||||
|
||||
## 1. Trigger
|
||||
|
||||
이 runbook은 다음 alert가 울리면 쓴다.
|
||||
이 runbook은 아래 신호로 서비스가 만든 경보가 울리면 쓴다. 이 템플릿은 경보 규칙을 두지 않는다. 경보 이름과 싣는 값은 서비스가 정한다.
|
||||
|
||||
- alert name: `outbox_publish_failed_rate`, `outbox_publisher_lag` 또는 `outbox_retry_long`
|
||||
- alert payload 필수 field: `error.code=OUTBOX_PUBLISH_FAILED`, `error.reason`, `event_type`, `correlation_id`, `runbook_link`
|
||||
- 경보에 실을 만한 값: `error.code=OUTBOX_PUBLISH_FAILED`, `error.reason`, `event_type`, `correlation_id`
|
||||
- 임계 (metrics.yaml verbatim):
|
||||
- P2: `outbox.publisher.published.total{outcome=FAILED}` rate > 1% for 10m
|
||||
- P2: `outbox.publisher.lag` > 60s for 10m / P1: > 300s for 5m
|
||||
@@ -35,8 +34,8 @@ status: 초안
|
||||
아니라 **선택자**다 — messaging을 끄는 것은 `APP_MESSAGING_ENABLED=false`이고, 이 값을 비운다고
|
||||
messaging이 꺼지지는 않는다.
|
||||
- relay 스케줄러는 발행 포트(`OutboxMessagePublishPort`, messaging bridge가 제공)가 있을 때만
|
||||
생긴다. messaging을 고르지 않은 배포에서는 relay가 없고 PENDING row가 그대로 남는다(MSG-024의
|
||||
"DEAD까지 소진"은 대역 publisher가 있던 때의 이야기다). messaging 모듈이 켜져 있는데
|
||||
생긴다. messaging을 고르지 않은 배포에서는 relay가 없고 PENDING row가 그대로 남는다(DEAD로 가지
|
||||
않는다). messaging 모듈이 켜져 있는데
|
||||
`APP_MESSAGING_PRODUCER_ID`가 공백이면(messaging `MessagingConfig`) 또는 `APP_MESSAGING_BROKER`가
|
||||
공백이면(messaging platform `MessagingProviderSelection`) 기동이 거부된다 — 값을 설정하거나
|
||||
messaging을 끈다.
|
||||
@@ -81,8 +80,8 @@ status: 초안
|
||||
|
||||
### 4.1 끝나지 않는 재시도 — 찾기, 보류(park), 재개(resume), 버리기(skip)
|
||||
|
||||
시도 예산을 쓰지 않는 실패(§2 Step 2)는 끝 상태가 없다. 리뷰 2026-11-01 README 15절 결정(재시도 유지)은 그대로 두고,
|
||||
운영자가 그런 행을 보고 멈출 수 있게 한다(재리뷰 2026-11-03 RR-05-03 결정).
|
||||
시도 예산을 쓰지 않는 실패(§2 Step 2)는 끝 상태가 없다. 그런 실패는 계속 재시도한다(소유자 결정). 대신 운영자가
|
||||
그런 행을 보고 멈출 수 있게 한다.
|
||||
|
||||
**Step 1 — 찾기 (읽기 전용).** 미룬 claim(`deferred_attempt_count`)이 10번 이상인 FAILED 행이다. backoff 상한이
|
||||
5분이라 10번은 적어도 약 35분 동안 계속 실패했다는 뜻이다. `outbox.retry.long.size`·`outbox.retry.long.age`가
|
||||
@@ -117,7 +116,7 @@ UPDATE outbox_event SET status = 'PARKED' WHERE event_id = '<id>' AND status = '
|
||||
|
||||
**롤백 전에 보류를 푼다.** `PARKED`는 이 버전(`bbe944bd` 이후)에 생긴 상태다. 그보다 옛 버전은 이 이름을 몰라
|
||||
상태별 집계 전체가 실패하고, `outbox.pending.size` 게이지가 PENDING까지 통째로 꺼진다 — `PENDING size growing`
|
||||
경보의 입력이 사라진다(재리뷰 2026-11-03 2차 RR-02-11). 옛 버전으로 롤백해야 하면 그 전에 보류한 행을 모두
|
||||
경보의 입력이 사라진다. 옛 버전으로 롤백해야 하면 그 전에 보류한 행을 모두
|
||||
Step 3으로 재개하거나 버린다. 이 버전부터는 모르는 상태가 있어도 그 상태만 빼고 세고 WARN 한 번으로 이름을
|
||||
말한다(`outbox_event holds rows in a status this version does not know`).
|
||||
|
||||
|
||||
@@ -4,69 +4,33 @@ category: RATE_LIMIT
|
||||
error_codes: [RATE_LIMIT_EXCEEDED, IDEMPOTENT_IN_FLIGHT]
|
||||
severity: P3
|
||||
owner: oncall
|
||||
last_updated: 2026-05-22
|
||||
last_updated: 2026-11-13
|
||||
status: 초안
|
||||
---
|
||||
|
||||
# Runbook: Rate limit 초과 spike
|
||||
|
||||
## 1. Trigger
|
||||
## 증상
|
||||
|
||||
이 runbook은 다음 alert가 울리면 쓴다.
|
||||
- HTTP 429 `RATE_LIMIT_EXCEEDED`, `Retry-After`(초), `X-RateLimit-Limit`·`X-RateLimit-Remaining`·`X-RateLimit-Reset` 헤더(`RateLimitInterceptor`). 저장소에 닿지 못하면 503 `RATE_LIMIT_UNAVAILABLE`이다.
|
||||
- 앱 안 limiter는 기본으로 꺼져 있다(`APP_RATE_LIMIT_ENABLED=false`, `docs/security/rate-limiting.md`). 켠 서비스에서만 이 증상이 난다.
|
||||
- 429에는 전용 WARN 줄이 없다. 요청 로그 INFO 줄 `http_request method=… uri_template=… status=429 duration_ms=…`(`RequestLoggingFilter`, `APP_LOG_SAMPLING_RATE` 표본)과 `http.server.requests`의 `status=429`가 신호다. 이 템플릿은 경보 규칙·대시보드를 두지 않는다. 서비스가 그 둘로 만든다.
|
||||
- `IDEMPOTENT_IN_FLIGHT`는 요청률 제한이 아니다. 같은 멱등 키의 요청이 아직 처리 중이라는 409(CONFLICT)다(`docs/web/runbook.md`).
|
||||
|
||||
- alert name: `rate_limit_429_high`
|
||||
- alert payload 필수 field: `operation`, `error.code`, `error.category`, `rate_limit_key_type`(ip|principal|tenant), `runbook_link`
|
||||
- 임계:
|
||||
- P3: 429 rate > 1% 10분 지속 (일상적 abuse 차단 효과 정상)
|
||||
- P2 격상: 정상 client(known principal/tenant)에서 spike 또는 spike와 함께 5xx 동반
|
||||
## 진단
|
||||
|
||||
## 2. First Response (5분 이내)
|
||||
- limiter key는 「호출자 × 연산」이다(`RateLimitKeyResolver`). 호출자는 인증된 사용자, `service` 역할을 가진 principal(종류 이름 `API_KEY`, header의 API key가 아니다), 인증이 없으면 client IP(`getRemoteAddr()`)다. 연산은 method와 route template(`GET /v1/orders/{id}`)이다. tenant 단위는 없다. 호출자 값(사용자 id·IP)은 가명으로 바꿔 쓰고 로그·지표에 남기지 않는다.
|
||||
- 정책 값(`APP_RATE_LIMIT_LIMIT`·`_WINDOW` 등)은 정책 id마다 하나이고 재시작해야 바뀐다. key 하나만 올리는 손잡이는 없다.
|
||||
|
||||
### Step 1 — 확인
|
||||
1. rate-limit key 분포 확인: IP/principal/tenant 중 어디서 spike가 발생했는지
|
||||
- log query: `error.code=RATE_LIMIT_EXCEEDED | stats count by rate_limit_key_type, rate_limit_key`
|
||||
2. top-N offending key 추출 (상위 10건)
|
||||
3. 정상 client 식별 — 알려진 partner/internal service면 P2 격상
|
||||
## 조치
|
||||
|
||||
### Step 2 — 임시 격리
|
||||
- abuse traffic 패턴이면 WAF/gateway에서 IP block (geo, ASN 단위)
|
||||
- IDEMPOTENT_IN_FLIGHT 다발이면 client의 retry-storm 의심 → client에 retry-after 협조 요청
|
||||
- 남용이면 앞단(WAF·gateway)에서 막는다.
|
||||
- 정상 트래픽이 늘었으면 정책 값을 올리고 재배포한다.
|
||||
- 클라이언트가 `Retry-After`를 지키지 않고 재시도하면 backoff를 요청한다.
|
||||
|
||||
## 3. Diagnosis
|
||||
## 에스컬레이션
|
||||
|
||||
- log query: `{service="gateway"} | error.code="RATE_LIMIT_EXCEEDED" | stats count by rate_limit_key`
|
||||
- metric panel: `gateway_rate_limit_dropped_total`, `gateway_rate_limit_bucket_utilization`
|
||||
- trace: 429 응답의 `Retry-After` 헤더 값, `rate_limit_remaining` header 확인
|
||||
- 가능한 원인:
|
||||
- abuse / bot traffic → IP/ASN block
|
||||
- 정상 client의 traffic 증가 (캠페인, 신규 feature) → limit 일시 상향
|
||||
- retry-storm (client backoff 미적용) → client에 idempotency-key + exponential backoff 권고
|
||||
- limit 설정 오류 (잘못된 정량 threshold) → config rollback
|
||||
|
||||
## 4. Mitigation
|
||||
|
||||
- 단기: abuse면 IP/ASN block, 정상 client면 해당 key의 limit 일시 상향(예: 2x, 1시간 TTL)
|
||||
- IDEMPOTENT_IN_FLIGHT 다발: idempotency-key 정책 점검, client 협조 요청
|
||||
- 장기: limit 정책을 tenant tier별 차등으로 재설계, abuse pattern detection 자동화
|
||||
|
||||
## 5. Escalation
|
||||
|
||||
- 다음 on-call로 page: 30분 내 정상 client 회복 안 되면 product team 통보
|
||||
- 정상 client에 SLO 위반 가능성 있으면 CSM/계정담당 통보
|
||||
|
||||
## 6. Recovery / Verification
|
||||
|
||||
- 회복 확인 metric: 429 rate < 0.5% 10분 지속, 정상 client의 success rate 정상화
|
||||
- post-incident:
|
||||
- 일시 상향한 limit 원복 (TTL 만료 확인)
|
||||
- abuse pattern을 detection rule에 영구 등록
|
||||
- retry-storm이면 client SDK 가이드 보완
|
||||
|
||||
## 7. Related
|
||||
|
||||
- error-codes.yaml rows: `RATE_LIMIT_EXCEEDED`, `IDEMPOTENT_IN_FLIGHT`
|
||||
- metrics.yaml: `gateway_rate_limit_dropped_total`, `gateway_rate_limit_bucket_utilization`
|
||||
- 관련 branch: [[feature-rate-limit-idempotency-contract]]
|
||||
- 정상 클라이언트가 30분 넘게 막히면 제품 팀에 알린다.
|
||||
|
||||
---
|
||||
|
||||
|
||||
@@ -4,7 +4,7 @@ category: TRANSIENT_DEPENDENCY
|
||||
error_codes: []
|
||||
severity: P1
|
||||
owner: oncall
|
||||
last_updated: 2026-07-29
|
||||
last_updated: 2026-11-13
|
||||
status: 운영
|
||||
---
|
||||
|
||||
@@ -36,11 +36,11 @@ Redis liveness 실패만으로 pod를 재시작하지 않는다. 재시작 폭
|
||||
뜻이다. 이를 정상 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`
|
||||
내보내지 않는다 — 대시보드에서 찾지 않는다(`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의
|
||||
|
||||
+23
-17
@@ -34,7 +34,10 @@ HTTP 경계가 이상할 때 운영자에게 필요한 것이다. 어느 모듈
|
||||
요구한다.
|
||||
2. **client가 다른 본문을 보냈다.** `422 IDEMPOTENT_REQUEST_MISMATCH`로 답하고 절대 다시 보내지 않는다. 다시 보내면
|
||||
호출자가 한 적 없는 요청의 영수증을 돌려주게 된다.
|
||||
3. **기록이 만료됐다.** TTL은 연산마다 정하고 상한은 72h다. 만료 뒤의 재시도는 정의상 새 요청이다.
|
||||
3. **기록이 만료됐다.** TTL은 전역 하나다: `APP_IDEMPOTENCY_TTL`(`app.capabilities.idempotency.replay-ttl`, 기본 24h,
|
||||
상한 72h). 연산마다 정하는 손잡이는 없다. 이 값은 실패 기록 보존 `APP_IDEMPOTENCY_FAILURE_RETENTION`(기본 24h)보다 길
|
||||
수 없다. TTL만 48h로 올리면 기동이 실패하니 둘을 같이 올린다(`IdempotencySettings`). 만료 뒤의 재시도는 정의상 새
|
||||
요청이다.
|
||||
|
||||
`409 IDEMPOTENT_IN_FLIGHT`(retryable=true, `Retry-After: 2`)는 실패가 아니다. 앞 시도가 아직 돌고 있고 그 결과를
|
||||
모른다. 호출자는 `Retry-After` 뒤에 **같은** `Idempotency-Key`로 다시 보낸다. 새 key는 새 요청이고, 쓰기가 두 번
|
||||
@@ -42,37 +45,40 @@ HTTP 경계가 이상할 때 운영자에게 필요한 것이다. 어느 모듈
|
||||
|
||||
## rolling 배포가 인스턴스를 반쯤 비운 채 멈춘다
|
||||
|
||||
`shutDownGracefully`는 진행 중인 일을 기다리고, 열려 있지만 노는 keep-alive connection이 진행 중으로 셀 수 있다. 그
|
||||
기다림 중에 `stop()`을 부르면 멈춘다.
|
||||
graceful shutdown(`server.shutdown=graceful`)은 진행 중인 요청이 끝나기를 기다린다. 끝나지 않는 요청이 있으면 그
|
||||
기다림이 길어진다.
|
||||
|
||||
- **증상:** 요청을 받지도 않고 끝나지도 않는 인스턴스. 로그에 오류가 없다.
|
||||
- **원인:** 상한 없는 graceful 기다림. `GracefulShutdownProbe`는 정한 유예 시간으로 그것을 제한하고, 시간이 지나면
|
||||
어쨌든 서버를 멈춘다. 배포도 같게 해야 한다.
|
||||
- **설정:** `spring.lifecycle.timeout-per-shutdown-phase`. 상한이 없으면 배포는 영영 놀지 않을 수도 있는 connection을
|
||||
기다린다.
|
||||
- **증상:** 종료 중인 인스턴스가 새 요청을 받지 않은 채 오래 남는다. 종료 예산보다 유예가 짧으면 멈추는 대신
|
||||
SIGKILL로 끝나고, 진행 중이던 요청·async 작업이 끊긴다. 로그에 오류가 없다.
|
||||
- **원인:** 종료 단계는 차례로 더해진다. 웹 drain(`spring.lifecycle.timeout-per-shutdown-phase`,
|
||||
`APP_SERVER_SHUTDOWN_TIMEOUT`, 기본 30s)이 끝난 뒤 async executor가 남은 작업을 19s 기다린다
|
||||
(`AsyncExecutorConfig.AWAIT_TERMINATION_SECONDS`). 합계 49s에 preStop(5s)과 여유를 더한 값보다 배포의 종료 유예
|
||||
(Kubernetes `terminationGracePeriodSeconds` 등, 기본 30s)가 짧으면 async 대기 중에 죽는다. compose는 60s다
|
||||
(`compose.yaml` `stop_grace_period`). 같은 예산을 `docs/runbooks/job-timeout.md` 「Escalation」이 적는다.
|
||||
- `GracefulShutdownProbe`는 시험 도구다(web `testFixtures`, 성능 lane이 쓴다). 운영 코드에는 없다.
|
||||
|
||||
## metric이 오지 않거나 청구액이 뛰었다
|
||||
|
||||
거의 늘 가짓수가 많은 tag다. 흔히 *풀린* 경로를 담은 `routeTemplate`이고, 자원마다 시계열 하나가 된다.
|
||||
거의 늘 가짓수가 많은 tag다. 흔히 *풀린* 경로를 담은 경로 tag이고, 자원마다 시계열 하나가 된다. 이 템플릿의
|
||||
`http.server.requests`는 Spring Framework 기본 convention(`DefaultServerRequestObservationConvention`)의 tag `uri`를
|
||||
쓴다(`docs/registries/metrics.yaml`). 맞는 route가 있으면 template(`/v1/orders/{id}`)이고, 없으면 그 convention이 정한
|
||||
상수(`NOT_FOUND`, `REDIRECTION`, `UNKNOWN`, `root`)다.
|
||||
|
||||
- **확인:** metric 저장소에서 `routeTemplate`의 tag 값을 본다. 중괄호가 있으면 template이고, 식별자가 있으면 풀린
|
||||
경로가 새어 나갔다.
|
||||
- **확인:** metric 저장소에서 `uri`의 tag 값을 본다. 중괄호가 있으면 template이고, 식별자가 있으면 풀린 경로가 새어
|
||||
나갔다(서비스가 자기 convention으로 tag를 바꿨을 때 생긴다).
|
||||
- **절대 tag로 쓰지 않는 것:** URL, query string, 식별자, tenant, key, token, cookie, 본문. tag 값은 가려지지 않은 채
|
||||
metric 저장소에 닿고, 보통 그와 함께 외부 SaaS에도 닿는다.
|
||||
|
||||
## 브라우저에서만 cross-origin 요청이 실패한다
|
||||
|
||||
API는 맞게 답하는데 브라우저가 응답을 거부한다. CORS는 `SecurityConfig`가 적용하는 `CorsSettings`(`app.cors.*`)다.
|
||||
시작 단계는 두 설정을 거부한다.
|
||||
시작 단계는 아래 설정을 거부한다.
|
||||
|
||||
- origin 없이 `APP_SECURITY_CORS_ENABLED=true`.
|
||||
- `APP_SECURITY_CORS_ALLOW_CREDENTIALS=true`와 함께 `APP_SECURITY_CORS_ORIGINS`의 `*` — 어떤 브라우저도 받아들이지
|
||||
않는다.
|
||||
|
||||
다음 둘은 시작은 되지만 브라우저에서 여전히 실패한다.
|
||||
|
||||
- origin 목록의 `https://*.example.com` — 글자 그대로 비교하므로 아무것에도 맞지 않는다.
|
||||
- 경로가 있는 origin(`https://app.example.com/ui`) — origin은 scheme, host, port뿐이다.
|
||||
- origin 목록의 `https://*.example.com` 같은 wildcard origin과 경로가 있는 origin(`https://app.example.com/ui`) — origin은
|
||||
scheme, host, port뿐이다(`CorsSettings`).
|
||||
|
||||
응답은 오는데 브라우저 코드에서 헤더가 `null`로 읽힌다(`Retry-After`, `X-Request-Id`, `Location`, tus
|
||||
`Upload-Offset`): 그 헤더가 `Access-Control-Expose-Headers`에 없다. 노출 목록은 `CorsExposedHeaders.PLATFORM`과 모듈마다의
|
||||
|
||||
@@ -258,7 +258,7 @@ commit-aware response wrapper 계약을 구현한다. 또한 이 모듈은 HTML
|
||||
| `LockAcquisitionTimeoutException` | `LOCK_ACQUISITION_TIMEOUT` | 409 (retryable=true, `Retry-After: 1`) | 분산 락을 `waitTime` 안에 못 잡음. 경합은 일시적이라 잠시 뒤 같은 요청을 다시 보낸다. carrier 분기(전에는 carrier 가 아니라 500 `INTERNAL_ERROR`, 재리뷰 RR7-01-04) |
|
||||
| `IdempotencyRequestMismatchException` | `IDEMPOTENT_REQUEST_MISMATCH` | 422 (retryable=false) | D8: `Idempotency-Key` 를 다른 본문으로 재사용. 다시 보내지 않는다(`docs/web/http-contract.md` §2). fingerprint/scope 노출 금지 |
|
||||
| `PersistenceFailureException` (JPA `JpaPersistenceException` 포함) | `ex.errorCode()` (사전분류 `DB_*`) | 코드 결정 | adapter-persistence translator 가 SQLState→`DB_*` 로 이미 분류, JPA 예외는 `FailureCategory`→`DB_*`. 클라이언트 메시지는 category 문구, **절대 `ex.getMessage()` 아님**(SQLState/제약명 담음, 서버 로그 전용) |
|
||||
| `DependencyFailureException` | `ex.errorCode()` (사전분류 `DEPENDENCY_*`) | 코드 결정 | adapter-outbound `OutboundHttpErrorMapper` 가 upstream 실패를 분류. 클라이언트 메시지는 category 문구, **절대 `ex.getMessage()` 아님**. retryable + `retry_after_seconds` 있으면 `RetryAfterAdvisor` 로 `Retry-After` 부착 |
|
||||
| `DependencyFailureException` | `ex.errorCode()` (사전분류 `DEPENDENCY_*`) | 코드 결정 | upstream 실패를 분류하는 서비스 코드가 던진다(템플릿 httpclient 는 만들지 않는다). 클라이언트 메시지는 category 문구, **절대 `ex.getMessage()` 아님**. retryable + `retry_after_seconds` 있으면 `RetryAfterAdvisor` 로 `Retry-After` 부착 |
|
||||
| `HttpRequestMethodNotSupportedException` | `METHOD_NOT_ALLOWED` | 405 | D12: 405 는 지원 메서드를 나열한 `Allow` 헤더 필수 |
|
||||
| `HttpMediaTypeNotSupportedException` | `UNSUPPORTED_MEDIA_TYPE` | 415 | D9: 요청 본문 형식 미지원 — 406 과 구별 |
|
||||
| `MaxUploadSizeExceededException` | `PAYLOAD_TOO_LARGE` | 413 | D8: 과대 본문은 envelope 내 413, raw 500 금지. multipart와 JSON 본문 모두 이 코드다(multipart 전용 코드는 없다) |
|
||||
|
||||
@@ -144,9 +144,10 @@ Spring/Lettuce 타입을 노출하지 않는다.
|
||||
- `AUTH_KID_UNKNOWN` 은 `retryable=true`: 키 회전(key rotation) 중 알 수 없는 JWKS `kid` 는 키
|
||||
세트가 새로고침되면 저절로 풀린다(레지스트리에서 `false→true` 로 바뀐 이력 있음, Retry-After 5s).
|
||||
- `AUTH_JWKS_UNAVAILABLE` 은 JWKS 엔드포인트 장애 = 일시적 의존성 실패 → 503, retryable.
|
||||
- `INTERNAL_AUTH_MISCONFIGURATION` 은 `retryable=false`: 보호돼야 할 엔드포인트가 public 으로
|
||||
새어 나가는 것은 **배포 시점 설정 버그**이지 일시적 장애가 아니다. 같은 요청을 다시 보내도 (재배포
|
||||
전까지) 절대 풀리지 않으므로 false 다(`INTERNAL` category 코드는 모두 `retryable=false`).
|
||||
- `INTERNAL_AUTH_MISCONFIGURATION` 은 `retryable=false`: JWT decoder 를 만들 수 없는 것(issuer discovery 4xx,
|
||||
discovery 의 `issuer` 불일치, `jwks_uri` 없음)은 **배포 시점 설정 버그**이지 일시적 장애가 아니다. 같은 요청을
|
||||
다시 보내도 (설정을 고쳐 재배포하기 전까지) 풀리지 않으므로 false 다(`INTERNAL` category 코드는 모두
|
||||
`retryable=false`). 공개 경로 설정 오류는 이 코드를 내지 않는다.
|
||||
|
||||
**rate-limit / idempotency**
|
||||
- `RATE_LIMIT_EXCEEDED` 는 `retryable=true` 이며 Retry-After 헤더와 짝을 이룬다.
|
||||
@@ -185,8 +186,9 @@ Spring/Lettuce 타입을 노출하지 않는다.
|
||||
| `DB_QUERY_CANCELED` | 57014 | TRANSIENT_DEPENDENCY | 503 | ❌ | |
|
||||
|
||||
**outbound HTTP — upstream 실패 분류**
|
||||
- `DEPENDENCY_*` 코드는 adapter-outbound 의 `OutboundHttpErrorMapper` 가 upstream HTTP/네트워크
|
||||
실패를 분류한 뒤 방출한다. raw upstream 응답은 web 계층까지 도달하지 않는다.
|
||||
- `DEPENDENCY_*` 코드는 서비스 코드가 upstream HTTP/네트워크 실패를 분류해 `DependencyFailureException` 으로 던질
|
||||
때 나온다. 템플릿의 httpclient 예외는 코드를 싣지 않아 500 `INTERNAL_ERROR` 다. raw upstream 응답은 web 계층까지
|
||||
도달하지 않는다.
|
||||
- **알려진 미해결 엣지:** 408(Request Timeout)·429(Too Many Requests)는 의미상 재시도 가능하지만,
|
||||
레지스트리 SSOT 는 **모든 upstream 4xx 를 `PERMANENT_DEPENDENCY`(`retryable=false`)로 분류**한다.
|
||||
이는 의도적 결정이며, 바꾸려면 레지스트리 갱신과 어댑터 변경을 함께 해야 한다.
|
||||
@@ -226,12 +228,12 @@ Spring/Lettuce 타입을 노출하지 않는다.
|
||||
(D6)이며, 정합성 자체는 이 코드가 아니라 DB 제약이 지킨다.
|
||||
|
||||
**기타 운영 코드**
|
||||
- `JVM_OOM`: JVM OutOfMemoryError 분류. JVM 이 죽는
|
||||
종료성 장애(`ExitOnOutOfMemoryError`, exit 137)라 재시도해도 안 풀림 → `retryable=false`
|
||||
(`INTERNAL`/500). 로그의 `error.code=JVM_OOM` 유무로 kubelet OOMKill 과 구별한다.
|
||||
- `ACTUATOR_FORBIDDEN`: 운영 환경에서 위험한
|
||||
actuator 엔드포인트(env/configprops/heapdump/threaddump/shutdown) 접근 → 403(`AUTHZ`/403/false,
|
||||
로그 WARN).
|
||||
- `JVM_OOM`: JVM OutOfMemoryError 분류. JVM 이 죽는 종료성 장애(`ExitOnOutOfMemoryError`, 종료 코드 3)라
|
||||
재시도해도 안 풀림 → `retryable=false`(`INTERNAL`/500). 이 코드를 로그에 쓰는 코드는 없다. kubelet OOMKill(137)과는
|
||||
종료 코드와 stderr 마지막 줄로 구별한다(`docs/runbooks/runtime-jvm-oom.md`).
|
||||
- `ACTUATOR_FORBIDDEN`: enum 상수와 registry 행(`AUTHZ`/403/false)만 있고 내는 코드가 없다. 노출 목록 밖의 actuator
|
||||
경로(env/configprops/heapdump/threaddump/shutdown)는 401 `AUTH_TOKEN_MISSING`(token 없음)이나 404(인증됨)다
|
||||
(`docs/runbooks/management-actuator-forbidden.md`).
|
||||
|
||||
### MappingException
|
||||
- **경계 mapper 의 sentinel.** request→command/query 변환, response shaping, outbound ACL 등 어떤
|
||||
@@ -253,9 +255,9 @@ Spring/Lettuce 타입을 노출하지 않는다.
|
||||
`MappingException` 과 동일하다.
|
||||
|
||||
### DependencyFailureException
|
||||
- **분류된 outbound HTTP(의존성) 실패의 프레임워크 중립 운반체**. adapter-outbound 의 `OutboundHttpErrorMapper` 가 raw 네트워크/HTTP 예외를 잡아 upstream
|
||||
실패 매트릭스로 분류한 뒤, 안정적 `ApiErrorCode`(`DEPENDENCY_*`)와 upstream 의존성 이름을 담아
|
||||
이 타입으로 감싸 다시 던진다.
|
||||
- **분류된 outbound HTTP(의존성) 실패의 프레임워크 중립 운반체**. upstream 실패를 분류하는 서비스 코드가 raw
|
||||
네트워크/HTTP 예외를 잡아 안정적 `ApiErrorCode`(`DEPENDENCY_*`)와 upstream 의존성 이름을 담아 이 타입으로 감싸 다시
|
||||
던진다. 템플릿의 httpclient 는 이 타입을 만들지 않는다.
|
||||
- **`diagnosticMessage` 는 서버 로그 전용이며 upstream raw 응답 본문을 절대 담아선 안 된다.** 테스트
|
||||
계약: "upstream raw error body 가 response/log 에 노출되면 실패". web 어댑터는 `errorCode()` +
|
||||
고정된 client-safe 메시지로 매핑하므로 upstream status/body/header/raw 예외 클래스가 API
|
||||
|
||||
+4
-4
@@ -1,10 +1,10 @@
|
||||
package dev.caskeleton.shared.error;
|
||||
|
||||
/**
|
||||
* Framework-neutral carrier for a classified outbound HTTP (dependency) failure. The
|
||||
* adapter-outbound {@code OutboundHttpErrorMapper} classifies a raw network / HTTP exception and
|
||||
* rethrows it wrapped in this type, carrying a stable {@link ApiErrorCode} (a {@code DEPENDENCY_*}
|
||||
* code in {@link OperationalError}) and the upstream dependency name.
|
||||
* Framework-neutral carrier for a classified outbound HTTP (dependency) failure. Service code that
|
||||
* classifies a raw network / HTTP exception rethrows it wrapped in this type, carrying a stable
|
||||
* {@link ApiErrorCode} (a {@code DEPENDENCY_*} code in {@link OperationalError}) and the upstream
|
||||
* dependency name. The template's HTTP client does not raise it.
|
||||
*
|
||||
* <p>The {@code diagnosticMessage} is <strong>SERVER-LOG-ONLY</strong> and must
|
||||
* <strong>NEVER</strong> contain the upstream raw response body. See the module README for the
|
||||
|
||||
Reference in New Issue
Block a user