From 0fded57cb35b44d2979bedf8c4ca5548f32630d5 Mon Sep 17 00:00:00 2001 From: DongHyeonka Date: Fri, 13 Nov 2026 08:29:28 +0900 Subject: [PATCH] =?UTF-8?q?docs(runbooks):=20runbook=20=EC=8B=A0=ED=98=B8?= =?UTF-8?q?=EB=A5=BC=20=EC=A7=80=EA=B8=88=20=EC=BD=94=EB=93=9C=EA=B0=80=20?= =?UTF-8?q?=EB=82=B4=EB=8A=94=20=EC=9D=91=EB=8B=B5=C2=B7=EB=A1=9C=EA=B7=B8?= =?UTF-8?q?=C2=B7=EC=A7=80=ED=91=9C=EB=A1=9C=20=EA=B3=A0=EC=B9=9C=EB=8B=A4?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit runbook이 코드가 내지 않는 신호로 장애를 찾게 한다. actuator·cross-tenant runbook은 아무 코드도 내지 않는 ACTUATOR_FORBIDDEN·AUTHZ_TENANT_MISMATCH를 증상으로 적고, 없는 경보·지표·로그 칸을 적는다. auth runbook은 로그에서 token payload·Authorization 원문을 보라고 하고(남지도 않고 남겨서도 안 된다), 없는 JWKS 캐시 손잡이와 decoder가 읽지 않는 Spring issuer 키를 적는다. rate-limit·dependency runbook은 없는 gateway 지표·헤더· CACHE_UNAVAILABLE·dependency_name 칸을, web runbook은 연산마다의 TTL, 시험 도구 GracefulShutdownProbe, 없는 tag routeTemplate, 기동이 거부하는 CORS 설정을 「기동은 된다」고 적는다. job runbook은 내는 코드가 없는 JOB_DEAD_LETTER·JOB_TIMEOUT과 job.* 지표에 경보를 걸게 한다. 각 runbook을 지금 코드가 내는 신호로 다시 쓴다: 응답 코드·헤더, 보안 로그 줄 `security failure: code=… path=…`, 요청 로그 줄, ServerFailureLog 의 고정 문구(`dependency failure classified as … dependency=<이름>`, `persistence failure classified as …`), 실제 설정 키 APP_SECURITY_JWT_ISSUER, registry에 있는 지표. 이 템플릿에 경보 규칙이 없다는 것, 내는 코드가 없는 코드·지표는 서비스가 낼 때만 있다는 것을 적는다. 진단 순서도 고친다: actuator 노출은 관리 포트 9001로 가르고, INTERNAL_AUTH_MISCONFIGURATION은 issuer discovery(4xx·issuer 불일치· jwks_uri 없음은 500, 연결 실패·5xx·JSON 아님은 503)부터, 종료 예산은 웹 drain 30s + async 19s + preStop의 합으로 본다. 같은 원인의 다른 자리(경보 이름을 지어 적은 job·outbox·internal-error-spike, traceId로 적은 칸, 지적 밖 auth·dependency·db·outbox runbook, error-codes.yaml 주석, 같은 틀린 신호를 적은 shared-contract README·web README· DependencyFailureException Javadoc)도 고치고, 본문의 리뷰 ID는 지운다. 버린 안: 선언만 있는 두 코드를 내는 WARN·counter를 새로 만들기. actuator 노출 밖 경로는 메인 chain이 401 AUTH_TOKEN_MISSING(익명)·404(인증됨)로 답해 403 상황이 없고, cross-tenant는 정한 규칙(남의 것은 404)이라 판정 자리가 서비스 코드에 있다. 새 신호는 서비스가 더할 일로 runbook에 적는다. 위험: 문서만 바뀐다. runbook은 모두 status 초안으로 둔다. dependency-unavailable이 적은 hikaricp.connections.pending·timeout 행과 job.* 행의 emitted_when은 관측 registry 변경(같은 묶음의 다른 PR)이 더하고, auth-jwks-unavailable의 「캐시가 지난 뒤 503」은 인증 PR의 JWKS 재조회 분류 수정이 만든다. 세 PR을 함께 병합한다. 검증: python3 scripts/check-docs.py·check-work-docs.py OK, desktop :app-bootstrap:documentContractTest :app-bootstrap:repositoryContractTest, scripts/verify.sh pr rc=0. Refs: RR9-02-04, RR9-02-24, RR9-04-34, RR9-04-37 --- docs/registries/error-codes.yaml | 2 + docs/runbooks/auth-audience-mismatch.md | 4 +- docs/runbooks/auth-issuer-mismatch.md | 14 ++-- docs/runbooks/auth-jwks-unavailable.md | 9 ++- docs/runbooks/auth-kid-unknown.md | 14 ++-- .../auth-public-path-misconfiguration.md | 19 ++--- docs/runbooks/auth-token-expired.md | 4 +- docs/runbooks/auth-token-invalid-signature.md | 4 +- docs/runbooks/auth-token-malformed.md | 17 ++-- docs/runbooks/auth-token-missing.md | 10 +-- docs/runbooks/auth-token-rotation-failure.md | 62 ++++----------- docs/runbooks/authz-cross-tenant-violation.md | 64 ++++----------- docs/runbooks/authz-tenant-mismatch.md | 14 ++-- docs/runbooks/db-unavailable.md | 4 +- docs/runbooks/dependency-4xx-client.md | 6 +- docs/runbooks/dependency-5xx-server.md | 6 +- docs/runbooks/dependency-circuit-open.md | 6 +- docs/runbooks/dependency-connect-failed.md | 6 +- docs/runbooks/dependency-dns-failed.md | 6 +- docs/runbooks/dependency-timeout.md | 6 +- docs/runbooks/dependency-unavailable.md | 77 ++++--------------- docs/runbooks/idempotency-unavailable.md | 4 +- docs/runbooks/internal-error-spike.md | 19 +++-- docs/runbooks/job-dead-letter.md | 14 ++-- docs/runbooks/job-executor-rejected.md | 7 +- docs/runbooks/job-timeout.md | 15 ++-- .../runbooks/management-actuator-forbidden.md | 20 ++--- docs/runbooks/outbox-dead-letter.md | 25 +++--- docs/runbooks/outbox-publish-failed.md | 17 ++-- docs/runbooks/rate-limit-exceeded.md | 66 ++++------------ docs/runbooks/redis-capability-incident.md | 6 +- docs/web/runbook.md | 40 ++++++---- src/adapter/inbound/web/README.md | 2 +- src/shared-contract/README.md | 30 ++++---- .../error/DependencyFailureException.java | 8 +- 35 files changed, 255 insertions(+), 372 deletions(-) diff --git a/docs/registries/error-codes.yaml b/docs/registries/error-codes.yaml index d3d531db..1b72892a 100644 --- a/docs/registries/error-codes.yaml +++ b/docs/registries/error-codes.yaml @@ -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 diff --git a/docs/runbooks/auth-audience-mismatch.md b/docs/runbooks/auth-audience-mismatch.md index 028422e6..6b3fc753 100644 --- a/docs/runbooks/auth-audience-mismatch.md +++ b/docs/runbooks/auth-audience-mismatch.md @@ -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`, 쉼표로 구분)와 비교한다. 토큰은 그중 하나 이상을 담아야 한다. diff --git a/docs/runbooks/auth-issuer-mismatch.md b/docs/runbooks/auth-issuer-mismatch.md index d77b97bd..07e6f169 100644 --- a/docs/runbooks/auth-issuer-mismatch.md +++ b/docs/runbooks/auth-issuer-mismatch.md @@ -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은 계속 거부한다. ## 에스컬레이션 - 예상하지 않은 발급자를 찾으면 플랫폼 보안 팀에 넘긴다. + --- > **초안**: 서비스가 도메인을 채운 뒤 본문을 쓴다. diff --git a/docs/runbooks/auth-jwks-unavailable.md b/docs/runbooks/auth-jwks-unavailable.md index 15197436..04785b51 100644 --- a/docs/runbooks/auth-jwks-unavailable.md +++ b/docs/runbooks/auth-jwks-unavailable.md @@ -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:///.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 팀과 복구를 맞춘다. ## 에스컬레이션 diff --git a/docs/runbooks/auth-kid-unknown.md b/docs/runbooks/auth-kid-unknown.md index d5949cfa..534a0ba0 100644 --- a/docs/runbooks/auth-kid-unknown.md +++ b/docs/runbooks/auth-kid-unknown.md @@ -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 팀에 넘긴다. + --- > **초안**: 서비스가 도메인을 채운 뒤 본문을 쓴다. diff --git a/docs/runbooks/auth-public-path-misconfiguration.md b/docs/runbooks/auth-public-path-misconfiguration.md index 5d6e8226..92a14795 100644 --- a/docs/runbooks/auth-public-path-misconfiguration.md +++ b/docs/runbooks/auth-public-path-misconfiguration.md @@ -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 설정을 본다. 앱이 도는 곳에서 `/.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이다. --- diff --git a/docs/runbooks/auth-token-expired.md b/docs/runbooks/auth-token-expired.md index acb5d48d..0cbbb7bf 100644 --- a/docs/runbooks/auth-token-expired.md +++ b/docs/runbooks/auth-token-expired.md @@ -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 동기화를 확인한다. ## 조치 diff --git a/docs/runbooks/auth-token-invalid-signature.md b/docs/runbooks/auth-token-invalid-signature.md index c0edd8eb..f4335bb5 100644 --- a/docs/runbooks/auth-token-invalid-signature.md +++ b/docs/runbooks/auth-token-invalid-signature.md @@ -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는 로그에 남지 않고 남겨서도 안 된다. - 위조가 의심되면 보안 팀에 알린다. ## 에스컬레이션 diff --git a/docs/runbooks/auth-token-malformed.md b/docs/runbooks/auth-token-malformed.md index 1ba219dd..2b53b7a4 100644 --- a/docs/runbooks/auth-token-malformed.md +++ b/docs/runbooks/auth-token-malformed.md @@ -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 `, 잘린 값)을 고친다. ## 에스컬레이션 -- 급증이 인프라 문제를 가리키면 넘긴다. +- 급증이 인프라 문제(프록시가 헤더를 바꿈 등)를 가리키면 넘긴다. + --- diff --git a/docs/runbooks/auth-token-missing.md b/docs/runbooks/auth-token-missing.md index 64cb8c13..1aa3115c 100644 --- a/docs/runbooks/auth-token-missing.md +++ b/docs/runbooks/auth-token-missing.md @@ -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: 초안 - 넓게 퍼졌거나 중요한 업무 흐름에 영향이 있으면 넘긴다. + --- > **초안**: 서비스가 도메인을 채운 뒤 본문을 쓴다. diff --git a/docs/runbooks/auth-token-rotation-failure.md b/docs/runbooks/auth-token-rotation-failure.md index 1290ffe5..34d90cc8 100644 --- a/docs/runbooks/auth-token-rotation-failure.md +++ b/docs/runbooks/auth-token-rotation-failure.md @@ -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= 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:///.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 팀에 넘긴다. --- diff --git a/docs/runbooks/authz-cross-tenant-violation.md b/docs/runbooks/authz-cross-tenant-violation.md index 5ef14248..9032726d 100644 --- a/docs/runbooks/authz-cross-tenant-violation.md +++ b/docs/runbooks/authz-cross-tenant-violation.md @@ -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=""` -- 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로 넘긴다. --- diff --git a/docs/runbooks/authz-tenant-mismatch.md b/docs/runbooks/authz-tenant-mismatch.md index 7a9e7035..554c13fb 100644 --- a/docs/runbooks/authz-tenant-mismatch.md +++ b/docs/runbooks/authz-tenant-mismatch.md @@ -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는 로그에 남지 않고 남겨서도 안 된다. 값을 봐야 하면 클라이언트 쪽에서 재현한다. - 클라이언트 설정 오류인지 의도한 공격인지 가린다. ## 조치 diff --git a/docs/runbooks/db-unavailable.md b/docs/runbooks/db-unavailable.md index 60a957ae..e207d837 100644 --- a/docs/runbooks/db-unavailable.md +++ b/docs/runbooks/db-unavailable.md @@ -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`(재시도 금지)이다. ## 진단 diff --git a/docs/runbooks/dependency-4xx-client.md b/docs/runbooks/dependency-4xx-client.md index 81be84b1..3383b22a 100644 --- a/docs/runbooks/dependency-4xx-client.md +++ b/docs/runbooks/dependency-4xx-client.md @@ -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가 유효한지 확인한다. ## 조치 diff --git a/docs/runbooks/dependency-5xx-server.md b/docs/runbooks/dependency-5xx-server.md index 3affac0f..edca7051 100644 --- a/docs/runbooks/dependency-5xx-server.md +++ b/docs/runbooks/dependency-5xx-server.md @@ -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`으로도 본다. - 업스트림 서비스의 상태 페이지를 본다. ## 조치 diff --git a/docs/runbooks/dependency-circuit-open.md b/docs/runbooks/dependency-circuit-open.md index 16111f36..ab76f48b 100644 --- a/docs/runbooks/dependency-circuit-open.md +++ b/docs/runbooks/dependency-circuit-open.md @@ -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이 열린다. ## 조치 diff --git a/docs/runbooks/dependency-connect-failed.md b/docs/runbooks/dependency-connect-failed.md index 259ca94f..a84e9f29 100644 --- a/docs/runbooks/dependency-connect-failed.md +++ b/docs/runbooks/dependency-connect-failed.md @@ -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`으로도 본다. - 네트워크 경로와 방화벽 규칙을 확인한다. ## 조치 diff --git a/docs/runbooks/dependency-dns-failed.md b/docs/runbooks/dependency-dns-failed.md index e65820d2..098c2d8f 100644 --- a/docs/runbooks/dependency-dns-failed.md +++ b/docs/runbooks/dependency-dns-failed.md @@ -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 ` +- 그 줄의 `dependency=`로 어느 업스트림인지 본다. 앱 pod에서 DNS 조회를 시험한다: `nslookup ` - 클러스터 DNS(CoreDNS) 상태를 확인한다. ## 조치 diff --git a/docs/runbooks/dependency-timeout.md b/docs/runbooks/dependency-timeout.md index 693cc116..e8030519 100644 --- a/docs/runbooks/dependency-timeout.md +++ b/docs/runbooks/dependency-timeout.md @@ -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`을 본다. - 업스트림 서비스의 지연 메트릭을 본다. ## 조치 diff --git a/docs/runbooks/dependency-unavailable.md b/docs/runbooks/dependency-unavailable.md index f207c45c..11151260 100644 --- a/docs/runbooks/dependency-unavailable.md +++ b/docs/runbooks/dependency-unavailable.md @@ -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="" | stats count by error.code` -- metric panel: - - `resilience4j_circuitbreaker_state{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에 넘긴다. --- diff --git a/docs/runbooks/idempotency-unavailable.md b/docs/runbooks/idempotency-unavailable.md index 72da6af8..42d25636 100644 --- a/docs/runbooks/idempotency-unavailable.md +++ b/docs/runbooks/idempotency-unavailable.md @@ -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로 돌린다. diff --git a/docs/runbooks/internal-error-spike.md b/docs/runbooks/internal-error-spike.md index de04cdfe..bab656ea 100644 --- a/docs/runbooks/internal-error-spike.md +++ b/docs/runbooks/internal-error-spike.md @@ -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 (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 `(분류된 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.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 `) ## 4. Mitigation diff --git a/docs/runbooks/job-dead-letter.md b/docs/runbooks/job-dead-letter.md index 1ea39f43..3da9bd71 100644 --- a/docs/runbooks/job-dead-letter.md +++ b/docs/runbooks/job-dead-letter.md @@ -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로 분류 diff --git a/docs/runbooks/job-executor-rejected.md b/docs/runbooks/job-executor-rejected.md index 0424c44e..e2920811 100644 --- a/docs/runbooks/job-executor-rejected.md +++ b/docs/runbooks/job-executor-rejected.md @@ -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) diff --git a/docs/runbooks/job-timeout.md b/docs/runbooks/job-timeout.md index fe049126..048b2a2f 100644 --- a/docs/runbooks/job-timeout.md +++ b/docs/runbooks/job-timeout.md @@ -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 '' to terminate`를 남긴다 + (`AsyncExecutorConfig.AWAIT_TERMINATION_SECONDS`). 남은 작업은 JVM이 끝날 때 함께 끊긴다. +- 서비스가 낼 때 경보에 실을 만한 값: `error.code=JOB_TIMEOUT`, `job_name`, `correlation_id` +- 임계: `job.retry.total{outcome=RETRY}` 급증 ## 2. First Response (10분 이내) diff --git a/docs/runbooks/management-actuator-forbidden.md b/docs/runbooks/management-actuator-forbidden.md index d3115fb4..5722bfbe 100644 --- a/docs/runbooks/management-actuator-forbidden.md +++ b/docs/runbooks/management-actuator-forbidden.md @@ -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://: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/…` 시도만 있으면 보통 스캐너다. + --- diff --git a/docs/runbooks/outbox-dead-letter.md b/docs/runbooks/outbox-dead-letter.md index 1189736b..552e0eb9 100644 --- a/docs/runbooks/outbox-dead-letter.md +++ b/docs/runbooks/outbox-dead-letter.md @@ -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로 옮긴다. ```sql @@ -109,8 +106,8 @@ UPDATE outbox_event SET status = 'PUBLISHED' WHERE event_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으로 하지 않는다**: 옛 버전 인스턴스를 모두 멈춘 뒤(옛·새 버전이 함께 쓰는 구간 없이) 새 버전을 띄운다. diff --git a/docs/runbooks/outbox-publish-failed.md b/docs/runbooks/outbox-publish-failed.md index 0f29b13b..21275c88 100644 --- a/docs/runbooks/outbox-publish-failed.md +++ b/docs/runbooks/outbox-publish-failed.md @@ -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 = '' 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`). diff --git a/docs/runbooks/rate-limit-exceeded.md b/docs/runbooks/rate-limit-exceeded.md index 05cc641a..315b5326 100644 --- a/docs/runbooks/rate-limit-exceeded.md +++ b/docs/runbooks/rate-limit-exceeded.md @@ -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분 넘게 막히면 제품 팀에 알린다. --- diff --git a/docs/runbooks/redis-capability-incident.md b/docs/runbooks/redis-capability-incident.md index 2af8035f..4f864856 100644 --- a/docs/runbooks/redis-capability-incident.md +++ b/docs/runbooks/redis-capability-incident.md @@ -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의 diff --git a/docs/web/runbook.md b/docs/web/runbook.md index 86eb1e30..58ac17c5 100644 --- a/docs/web/runbook.md +++ b/docs/web/runbook.md @@ -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`과 모듈마다의 diff --git a/src/adapter/inbound/web/README.md b/src/adapter/inbound/web/README.md index 6792c246..69345a97 100644 --- a/src/adapter/inbound/web/README.md +++ b/src/adapter/inbound/web/README.md @@ -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 전용 코드는 없다) | diff --git a/src/shared-contract/README.md b/src/shared-contract/README.md index 998e49ac..dfe9afb5 100644 --- a/src/shared-contract/README.md +++ b/src/shared-contract/README.md @@ -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 diff --git a/src/shared-contract/src/main/java/dev/caskeleton/shared/error/DependencyFailureException.java b/src/shared-contract/src/main/java/dev/caskeleton/shared/error/DependencyFailureException.java index 2495b313..5b4fa6ff 100644 --- a/src/shared-contract/src/main/java/dev/caskeleton/shared/error/DependencyFailureException.java +++ b/src/shared-contract/src/main/java/dev/caskeleton/shared/error/DependencyFailureException.java @@ -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. * *

The {@code diagnosticMessage} is SERVER-LOG-ONLY and must * NEVER contain the upstream raw response body. See the module README for the -- 2.54.0