문제: `docs/runbooks`의 runbook 38개가 영어였다(`check-docs.py` language
예외). 머리말 `status`는 `stub`·`active`였는데 문서 체계 규칙(design-docs
`conventions/docs-system.md` 1절)은 runbook 상태를 「초안 · 운영」으로 정한다.
번역하며 대조하니 지금 코드와 다른 주장도 있었다.
고친 것:
- 38개를 번역했다. 코드·명령·경로·설정 키·로그 문자열·표 구조는 그대로다.
lane이 읽는 SQL·Redis 블록과 표지(`<!-- runbook-sql: … -->`)는 바이트 그대로다.
- `status`: stub → 초안 43개, active → 운영 3개, `template.md`는 `<초안|운영>`.
머리말이 없는 gRPC runbook 둘은 그대로다.
- 코드에 맞춘 주장:
- adapter-adapter-disabled: 없는 `adapter_name` 로그 칸 → `ServerFailureLog`의
`failure classified as ADAPTER_DISABLED` 줄과 예외 메시지. 지금 이 코드를 내는
곳은 `RoutingNotifier`뿐이다.
- startup-required-adapter-disabled: `startup.phase=adapter-check` →
`adapter-enablement`(`StartupPhase.ADAPTER_ENABLEMENT`).
- cache-stampede-lock-timeout·cache-unavailable·file-download-streaming-failure:
그 코드는 `error-codes.yaml`에 없고 어느 코드도 내지 않는다고 밝혔다.
- db-idle-in-tx-timeout: 없는 `spring.jpa.properties.hibernate.connection.timeout`
→ `app.persistence-jpa.transaction.*`. db-query-canceled에 남은 시간 전달을 더했다.
- dependency-timeout: 「기본 전체 10s」 → profile `timeout.total-call`
(`HttpClientPlatformSettings` 기본 `4s`, 값은 configuration-reference를 가리킨다).
- management-actuator-forbidden: 없는 break-glass runbook → 노출 제외 목록
(`config/observability.yml`).
- runtime-jvm-oom: 아무것도 쓰지 않는 `error.code=JVM_OOM` 로그를 지우고, 힙 덤프
경로(`src/Dockerfile`)를 적었다.
- auth-public-path-misconfiguration: 공개 경로는 `config/security.yml` `public-paths`.
- grpc-advanced-capabilities: 지운 `GrpcAdvancedSupportMatrix` →
`GrpcAdvancedCapability.defaultGrade()`, envoy 참조 설정의 실제 경로.
- grpc-platform-operations: 없는 `runtime_memberships` → registry `"build": "optional-grpc"`.
- 다른 문서·코드가 영어 절 제목으로 인용하는 곳("Recover a failed concurrent index
migration", "Classify the failure")은 한국어 제목 뒤 괄호에 영어를 남겼다. 인용하는
쪽(테스트 fixture 메시지, `docs/upgrade`, 다른 세션 범위 문서)은 고치지 않아도 맞다.
- `RunbookCoverageContractTest`: `초안`을 초안으로 보고, 머리말 `status`가 `초안`·`운영`
밖이면 실패하는 테스트를 더했다.
- `scripts/check-docs-exceptions.txt`에서 runbook language 줄 38개를 지웠다.
버린 대안: 옛 `stub`도 초안으로 계속 받기. 그러면 옛 표기로 쓴 초안이 운영
runbook으로 통과한다. 어휘 밖 값을 실패로 둬야 그 길이 막힌다.
위험·한계:
- 이미 한국어였던 runbook 11개는 `status`만 바꿨고 본문 감사는 하지 않았다.
- runtime-jvm-oom의 「종료 코드 137」은 원문대로 두었다. JVM의
`-XX:+ExitOnOutOfMemoryError` 종료 코드는 3이고 137은 SIGKILL이라 확인이 필요하다.
- `docs/mongodb/runbooks/*.md`의 `status: active`는 이 테스트 밖이고 범위 밖이라 두었다.
검증: 아래 「검증」 줄은 영역 커밋 여섯이 합쳐진 최종 트리에서 돌렸다.
검증(desktop, 최종 트리 8295db89 = 이 묶음 마지막 커밋의 트리. 로그
`~/d2c-ops-docs-1-logs/`):
- `:app-bootstrap:documentContractTest` rc=0, 68개 실패 0(`RunbookCoverageContractTest` 7개).
`:app-bootstrap:repositoryContractTest` rc=0, 65개 건너뜀 1(원래 그렇다) 실패 0.
- runbook SQL·Redis 블록을 문서에서 읽는 lane: persistence-jpa
`postgresqlConcurrentIndexMigrationIntegrationTest`·`postgresqlDistributedLockIntegrationTest`·
`postgresqlOutboxOrderKeyRunbookIntegrationTest`·`postgresqlOutboxDispositionRunbookIntegrationTest`
rc=0(35개 실패 0), cache-redis `redisContainerContractTest` rc=0(103개 실패 0),
`:composition:outbox-relay:mainCheck` rc=0. 모두 실행됨(FROM-CACHE는 다른 leaf의 main 컴파일뿐).
- RED: 새 테스트를 기준 커밋의 옛 runbook에 대면 `legacyStubDebtMustMatchEveryAndOnlyCurrentStubRunbook`과
`everyRunbookFrontmatterDeclaresDraftOrOperatingStatus`가 실패한다("status=stub").
- `:app-bootstrap:spotlessCheck checkstyleTest testQualityCheck` rc=0.
- 커밋마다(노트북): `python3 scripts/check-docs.py` rc=0, `python3 -m unittest discover -s scripts/tests` rc=0.
11 KiB
title, category, error_codes, severity, owner, last_updated, status
| title | category | error_codes | severity | owner | last_updated | status | |
|---|---|---|---|---|---|---|---|
| Runbook — MIGRATION_FAILED (DB 마이그레이션 실패) | INTERNAL |
|
P1 | oncall | 2026-11-07 | 운영 |
Runbook: MIGRATION_FAILED (runbook://migration/failed)
증상
- 컨테이너가 코드 70으로 끝난다(마이그레이션 실패 종료).
- 구조화 로그
error.code=MIGRATION_FAILED,startup.phase=migration. - 앱이 뜨기를 거부한다(fail-fast).
- JPA capability 어댑터가 활성화를 거부한다. 그
capability_schema_registry.lifecycle_state가ACTIVE가 아니다.
진단
-
rollout을 멈추고, 실패한 revision을 readiness 밖에 둔다. 마이그레이션이 반쯤 된 인스턴스로 트래픽을 보내지 않는다.
-
src/adapter/outbound/persistence-jpa/release/readiness-cards.yaml에서 정확한 stream을 찾는다. stream마다location과history-table이 따로 있다. 넓은classpath:db/migration스캔으로 소유를 짐작하지 않는다. -
권한 있는 마이그레이션 세션에서, 무엇이든 바꾸기 전에 stream 상태를 남긴다.
select installed_rank, version, description, success from <owned_history_table> order by installed_rank; select capability_id, installation_origin, core_epoch, feature_revision, lifecycle_state from capability_schema_registry where capability_id = '<card-id>'; -
성공한 이력 행 없이 만들어진 소유 relation이 있는지 확인한다. 검토한 마이그레이션의 소유 테이블과만 비교한다. 상관없는 relation은 지우지 않는다.
-
실패를 분류한다(Classify the failure).
-
락·문장 시간 초과: 막는 쪽을 없애거나 rollout 동시성을 줄이고 다시 돌린다. 이미 쓰는 테이블을 잠그는 마이그레이션은 자기
SET LOCAL lock_timeout(5 s, SQLState55P03lock_not_available)이 지나면 포기하고 통째로 롤백한다. 그래서 이력은 그 버전 바로 아래에서 끝난다. 막는 쪽은 그 테이블을 건드린 뒤 아직 열려 있는 트랜잭션이다. 흔히 idle-in-transaction 세션이다. 그 테이블에 쥔 락으로 찾는다(<table>은 실패한 문장이 잠그는 테이블이다.REFERENCES면 참조하는 테이블도 본다).SELECT DISTINCT a.pid, a.state, a.xact_start, a.query FROM pg_locks l JOIN pg_stat_activity a USING (pid) WHERE l.relation = '<table>'::regclass AND l.granted AND a.pid <> pg_backend_pid() ORDER BY a.xact_start;query는 그 세션의 마지막 문장일 뿐 테이블을 건드린 문장이 아니므로, 거기서 테이블 이름을 찾지 않는다. 대신 긴 트랜잭션을 모두 나열하면 막는 쪽 옆에 상관없는 것(리포트, 배치)도 나온다. 막는 쪽을 끝낸 뒤 다시 돌린다(docs/jpa/migration-guide.md"Bound the lock wait"). -
SQL·데이터 전제 조건: 전제 조건을 드러내는 새 forward 마이그레이션을 만든다. 중복된 outbox 순서 키가 V21(
ux_outbox_event_aggregate_order)을 막는 것이 알려진 경우다.outbox-dead-letter.md§8로 정리하고 다시 돌린다. 마이그레이션은 그대로 둔다. -
checksum 불일치: repair를 생각하기 전에 배포한 산출물과 이미 적용된 스크립트를 비교한다.
-
동시 인덱스 마이그레이션 실패(Flyway가 트랜잭션 밖에서 돌린
CREATE [UNIQUE] INDEX CONCURRENTLY,DROP INDEX CONCURRENTLY,REINDEX … CONCURRENTLY): unique 인덱스의 중복 값, 교착,statement_timeout, 또는 열린 트랜잭션을 기다리다 취소된 문장이다. 트랜잭션 밖이라 아무것도 롤백되지 않았다. 마이그레이션은 무효 인덱스와, 그 버전의success = false이력 행을 남겼다. 그 행이 사라질 때까지 뒤의 배포는 모두 검증에서 실패한다("Detected failed migration to version …"). 인덱스만 지워서는 풀리지 않는다. 아래 「실패한 동시 인덱스 마이그레이션 복구」를 따른다. -
연결·TLS 실패: Flyway 이력을 바꾸지 않고 전송이나 자격 증명을 고친다.
-
조치
-
forward 복구를 먼저 쓴다. 환경 쪽 막힘을 고치거나 바뀌지 않는 새 마이그레이션을 더한 뒤, 같은 소유 stream을 그 정확한 이력 테이블로 다시 돌린다.
-
한 번도 성공적으로 설치되지 않은 선택 stream은 마이그레이션이 성공할 때까지 capability 표시를 두지 않고 런타임 어댑터를 꺼 둔다.
-
마이그레이션이 성공하면 확인한다.
- 이력에 기대한 버전의 성공 행만 있다.
core_epoch와feature_revision이 readiness registry와 같다.- 표시가
INSTALLED_INACTIVE다. - 소유 객체와 제약이 있다.
-
맞는 애플리케이션 revision이 배포되고 그 readiness 검사가 성공한 뒤에만 표시를
ACTIVE로 바꾼다. 애플리케이션 코드를 끄거나 되돌리면 표시가INSTALLED_INACTIVE로 바뀐다. 이력이나 소유 데이터는 지우지 않는다. -
승격 전에 readiness lane을 다시 돌린다(모든 card의 시나리오, 건너뜀 없음).
cd src ./gradlew :adapter:outbound:persistence-jpa:integrationTestLaneCheck --console=plain -
실패한 revision, stream·이력 테이블, 근본 원인, 복구 마이그레이션, 걸린 시간, 검증 산출물을 장애 기록에 남긴다.
하지 않을 것:
- 이미 적용된 마이그레이션을 고친다.
- 검증을 통과시키려고 Flyway 이력을 지우거나 다시 쓴다. 예외는 하나다. 실패한 동시 인덱스 마이그레이션의 실패 행을 아래 「실패한 동시 인덱스 마이그레이션 복구」대로 지운다. 그 행 말고는 아무것도 지우지 않는다.
- checksum의 출처가 증명되고 검토되기 전에
flyway repair를 돌린다. - 첫 대응으로
clean, 파괴적 롤백, 스키마 전체 복원을 쓴다. - 마이그레이션과 어댑터 readiness가 성공하기 전에 capability를
ACTIVE로 표시한다.
장애 중에 커밋 결과를 알 수 없었으면, 업무 작업을 다시 하기 전에 애플리케이션의 OperationId·멱등성 참조로
맞춘다. 결과를 모르는 커밋을 그냥 다시 시도하지 않는다.
실패한 동시 인덱스 마이그레이션 복구 (Recover a failed concurrent index migration)
이 runbook이 Flyway 이력을 바꾸는 유일한 경우다(소유자 결정, 2026-11-06). Flyway가 트랜잭션 밖에서 돌린 동시
인덱스 문장 하나만 담은 마이그레이션에 쓴다. 가이드가 요구하는 executeInTransaction=false로 돌렸거나,
CREATE/DROP INDEX CONCURRENTLY라서 Flyway가 알아서 그렇게 돌린 경우다(docs/jpa/migration-guide.md
"Concurrent index builds"). 그리고 stream 이력 테이블의 이 버전 행이 success = false여야 한다. 다른 문장을 섞은
마이그레이션은 그 문장을 이미 커밋했다. 그 상태는 DB 소유자와 함께 다시 맞춘다.
- 아직 도는 빌드가 없는지 확인한다. 아직 만드는 중인 인덱스도 카탈로그에서는 무효로 보이고, 그것을 지우면 빌드와 경합한다. 도는 빌드가 없으면 이 쿼리는 행을 돌려주지 않는다.
SELECT pid, relid::regclass AS table_name, index_relid::regclass AS index_name, phase
FROM pg_stat_progress_create_index
WHERE datname = current_database();
- 원인을 없앤다. unique 인덱스면 데이터 소유자와 중복 행을 정리한다(forward 수정이다. 마이그레이션을 고치지
않는다). 교착, 시간 초과, 취소된 문장이면 그것을 쥔 트랜잭션을 끝내거나 끝나기를 기다린다. 빌드와 재빌드는
자기보다 오래된 트랜잭션을 모두 기다리고, 삭제는 그 테이블에 락을 쥔 트랜잭션을 모두 기다린다. 3단계 전에
한다. 3단계의
DROP INDEX CONCURRENTLY도 같은 트랜잭션을 기다린다. - 실패한 빌드나 재빌드가 남긴 무효 인덱스를 지운다.
CREATE [UNIQUE] INDEX CONCURRENTLY가 이름 붙인 인덱스, 또는REINDEX … CONCURRENTLY가 만든 사본이다. 사본은 인덱스 이름 끝에_ccnew(또는_ccold)가 붙는다 (docs/jpa/runbooks.md"An invalid index exists"가 그 목록을 준다).BEGIN안이 아니라 따로 돌린다.CONCURRENTLY는 트랜잭션 블록을 거부한다. 실패한 문장이DROP INDEX CONCURRENTLY면 이 단계를 건너뛴다. 그것이 남긴 무효 인덱스는 마이그레이션이 지우는 인덱스이고, 5단계의 배포가 같은 문장을 돌려 그것을 지운다. 먼저 손으로 지우면 그 문장이42704("index … does not exist")로 실패하고 새 실패 행을 남긴다.
DROP INDEX CONCURRENTLY IF EXISTS <invalid_index>;
- stream 이력 테이블에서 그 버전의 실패 행을 지운다. 그 밖에는 아무것도 지우지 않는다.
<version>은 진단 쿼리가 보여 주는 실패 행의version칸이다(V22_1__…이면22.1). 정확히 한 행을 지워야 한다. 한 행도 지우지 않으면 이 절이 다루는 실패가 아니므로 다시 분류한다.
DELETE FROM <owned_history_table>
WHERE version = '<version>' AND NOT success;
- 다시 배포한다. Flyway가 같은 마이그레이션을 처음부터 돌린다. 인덱스를 만들거나, 다시 만들거나, 실패한 삭제가 남긴 인덱스를 지운다.
실패 행은 한 번도 적용되지 않은 버전의 기록이다. 그래서 지워도 적용된 모든 버전의 순서와 checksum은 그대로다.
이 일에 flyway repair를 쓰지 않는다. repair는 남은 행의 checksum과 description도 디스크의 스크립트에 맞춰 다시
쓰므로, checksum 불일치가 담은 증거를 지운다.
:adapter:outbound:persistence-jpa:postgresqlConcurrentIndexMigrationIntegrationTest가 위의 SQL 블록 셋을 이
파일에서 읽어, 이 절이 다루는 문장마다 실제 PostgreSQL에 돌린다. 중복으로 실패하는 unique 빌드, 열린 트랜잭션을
기다리다 취소된 재빌드와 삭제다. 1~4단계를 차례로 돌리고(3단계는 빌드와 재빌드만), 다음 배포가 무효 인덱스 없이
그 버전을 적용하며 앞 버전의 checksum은 바뀌지 않는다.
에스컬레이션
- P1 즉시: 필요한 애플리케이션 revision이 ready가 되지 못한다.
- Flyway 이력 repair, 파괴적 DDL, 시점 복구(PITR), primary failover 전에 DB 소유자에게 넘긴다.
- R3 복원·PITR과 failover 예행연습에는 대상과 비슷한 백업 구성이 필요하다. 로컬 Testcontainers 증거로 대신하지 않는다.
이 runbook은 forward 방향만 다룬다. 감사 근거는 검토한 마이그레이션 산출물과 CI의 readiness lane JUnit 결과다.