문체 규칙(「~한다」, 「~합니다」와 섞지 않음)은 docs/README.md에 있지만 지키는 검사가 없어서, 번역 뒤에도 runbook 열 개에 높임 문장이 남았다. 그리고 결정 기록 머리 블록의 둘째 줄은 「본문은 결정한 때의 원문이다」인데, 2026-11-07에 본문을 한국어로 옮긴 ADR에는 맞지 않는다. - check-docs.py `style`: 살아 있는 문서의 문장 끝이 높임(습니다·합니다· 입니다·됩니다·십시오·하세요·주세요)이면 실패. 코드 블록, 인라인 코드, 따옴표·낫표 안 인용, 「이력」 인용 블록은 보지 않는다. - runbook 열 개의 「이 runbook은 다음 alert에서 발동됩니다.」를 「다음 alert가 울리면 쓴다.」로 고쳤다. 지금 걸리는 곳은 이것뿐이었다. - 결정 기록 표시 줄을 「본문은 결정한 때의 내용이다(번역은 뜻을 바꾸지 않았다)」로 바꿨다: check-docs.py의 DECISION_LABEL, docs/README.md 설명, docs/adr의 머리 블록 33개(기록은 머리 블록만 고친다는 규칙 안). - docs/README.md 「문서 검사」에 앞 커밋이 더한 `link`와 이번 `style`을 적고, 링크 검사 설명을 바로잡았다. 「모듈 README」 절(design-docs docs-system.md 6.2절 다섯 칸)을 더했다. 버린 대안: 문체를 리뷰로만 보기(번역 묶음 네 개를 거쳐도 남았다). 위험: design-docs docs-system.md 4.1절과 프론트의 같은 문구는 이 repo 밖이라 고치지 않았다(총괄에게 알린다). 검증: python3 -m unittest discover -s scripts/tests(문체 시험 5 포함), check-docs.py, check-work-docs.py 모두 rc=0. 이 커밋의 트리만 얹은 임시 worktree에서 돌렸다. 검사 조건을 끈 사본 둘에서 문체 시험이 각각 2건, 1건 실패했다.
85 lines
5.8 KiB
Markdown
85 lines
5.8 KiB
Markdown
<!-- 머리 블록: 이 블록을 빼면 원문이다. 형식은 docs/README.md 「기록 문서의 머리 블록」 -->
|
|
> **결정 기록** 본문은 결정한 때의 내용이다(번역은 뜻을 바꾸지 않았다). 지금도 유효한지는 「상태」를, 지금 동작은 「현재 정본」을 읽는다.
|
|
|
|
- 상태: 채택(보완)
|
|
- 작성일: 2026-08-13
|
|
- 요약: MongoDB 고급 기능의 승격 기준을 정한 결정이다. 2026-09-25 보완이 있다.
|
|
- 현재 정본: `docs/mongodb/support-matrix.md`
|
|
<!-- 머리 블록 끝 -->
|
|
|
|
# ADR-MONGO-ADV-001 — Advanced capability 승격
|
|
|
|
- **상태:** 채택
|
|
- **날짜:** 2026-08-13
|
|
- **설계 출처:** 설계 §2 (D-15), §3.2–§3.3. Advanced 확장 계획 Task 15
|
|
- **2026-09-25 보완:** `ca-skeleton.persistence-mongo.advanced.*.enabled` 바인딩(`MongoAdvancedConfiguration`/
|
|
`MongoAdvancedSettings`)은 아무것도 import하지 않아서 어떤 배포 속성도 flag에 닿지 않았다. `propertyFor`와 함께 지웠다. flag는
|
|
이제 entry point를 만드는 어댑터가 코드로 만든다. `MongoAdvancedPromotionGate`, `MongoAdvancedPromotionEvidence`,
|
|
`MongoVectorSearchBenchmarkGate`, 그리고 search, vector, time series, GridFS 패키지(구현 없는 인터페이스)를 지웠다. 아래 증거
|
|
category는 리뷰 의무로 남는다. 그것을 검사하는 클래스는 없다.
|
|
|
|
## 배경
|
|
|
|
sharding, time series, CSFLE, Queryable Encryption, search, vector search, multi-tenancy는 하나같이 오후 한나절이면 demo에서
|
|
동작한다. 하지 않는 것은 운영에서 같은 방식으로 동작하는 것이고, 그 차이는 기능 시험으로 찾지 못한다:
|
|
|
|
- sharding은 어떤 query가 효율적인지 바꾼다. shard key를 놓친 query는 scatter-gather가 되는데, shard 하나짜리 cluster에서는
|
|
모든 시험을 통과한다.
|
|
- 암호화의 실패 방식은 KMS의 실패 방식이다 — 틀린 키, 거둬들인 권한, 교체 중 — 로컬 키 provider에 대고는 하나도 일어나지 않는다.
|
|
- search와 vector search는 기능상 맞으면서 쓸모없을 수 있다: index는 결과를 돌려주는데 결과가 관련이 없다. recall은 통과·실패
|
|
단언에 보이지 않는다.
|
|
- 테넌트마다 데이터베이스는 테넌트 수가 연결·파일 handle 예산이 받쳐 주는 수를 넘을 때까지 동작한다. 그것은 코드가 아니라 운영의
|
|
성질이다.
|
|
|
|
이 ADR이 막는 실패 방식은 그것이 돌 환경을 한 번도 건드리지 않은 초록 시험을 근거로 capability를 「끝남」으로 표시하는 것이다.
|
|
|
|
## 결정
|
|
|
|
모든 Advanced·Experimental capability는 **자기 flag 뒤의 골라 쓰는 모듈**이고, 승격에는 자신감이 아니라 증거가 필요하다.
|
|
|
|
### 켜기
|
|
|
|
`MongoAdvancedCapabilityFlags`가 모든 Advanced entry point의 생성을 막는다. 꺼진 capability는 런타임 경고를 내지 않는다 — 타입이
|
|
그것을 켜는 속성 이름을 대며 만들어지기를 거절한다(`MongoAdvancedCapabilityFlags.propertyFor(capability)`). classpath에 있다고
|
|
켜진 것이 아니고, `stableNeverDependsOnAdvanced`(ArchUnit)가 Stable surface에서 그것을 떼어 둔다.
|
|
|
|
### 승격 증거
|
|
|
|
`MongoAdvancedPromotionGate.verify(evidence)`는 모든 category를 요구한다:
|
|
|
|
| category | 뜻 |
|
|
|---|---|
|
|
| `stable-platform` | 같은 revision에서 Stable 릴리스 gate가 통과했다. |
|
|
| `actual-topology` | capability가 실제 topology에서 돌았다 — 실제 sharded cluster, 실제 KMS, 실제 대상 배포. Atlas Local은 pull request용 편의이고 릴리스 증거가 아님을 명시한다(`MongoAtlasCapabilityContractSuite.Environment.ATLAS_LOCAL`). |
|
|
| `security` | 권한을 리뷰했다. capability의 admin role은 애플리케이션 role과 따로다. |
|
|
| `migration` | 들어가는 길을 적었고, capability가 되돌릴 수 없으면 돌아오는 길이 없다고 명시했다. |
|
|
| `failure` | 부정 경우가 실패하면 닫힌다: 틀린 키, 빠진 권한, 교체, 준비되지 않은 index, 라우팅되지 않은 query. |
|
|
| `runbook` | capability의 대표 사고를 위한 runbook이 있다. |
|
|
|
|
### capability별 추가 요구
|
|
|
|
- **search / vector search:** 기능 성공만이 아니라 관련성과 성능 증거. `MongoVectorSearchBenchmarkGate`는 지연 시간·index 크기와
|
|
함께 recall을 요구한다. 지연 시간만 재는 gate는 빠른 틀린 답을 인증한다.
|
|
- **테넌트마다 데이터베이스와 reshard 조율은 운영 규모 증거가 생길 때까지 Experimental로 남는다.** 둘 다 작게는 맞고 크게는
|
|
한계가 없다.
|
|
- **reshard에는 명시한 `ReshardApproval`이 필요하다** — 이름 있는 승인자와 밝힌 시간 창. reshard는 collection을 다시 쓴다.
|
|
|
|
### 승격은 의존 경계를 바꾸지 않는다
|
|
|
|
Stable로 승격한 capability도 나중의 starter ADR이 의존 경계를 바꾸지 않는 한 **골라 쓰는 모듈로 남는다**. 승격은 증거에 대한
|
|
진술이지, 모든 서비스에 전이 의존을 더하라는 초대가 아니다.
|
|
|
|
## 결과
|
|
|
|
**좋은 점.** container 전용 시험을 근거로 운영에 닿는 capability는 없다. 증거 목록이 모든 capability에 같으므로, 승격은 흥정이
|
|
아니라 리뷰할 수 있는 것이 된다.
|
|
|
|
**나쁜 점.** 승격에는 실제 기반 시설 — sharded cluster, 실제 KMS, 대상 배포 — 에 대한 접근이 필요하다. 그것이 보장의 비용이다:
|
|
대안은 운영에서 알게 되는 것이고, 거기서는 암호화와 sharding 둘 다 되돌리기 비싸다.
|
|
|
|
## 검증
|
|
|
|
`scripts/verify-mongodb-advanced.sh`가 2026-08-15에 지워질 때까지 이 ADR을 강제했다. 그래서 이 ADR이 요구하는 승격 증거
|
|
category는 이제 어떤 자동 gate도 검사하지 않는다. 다시 만들 때까지 리뷰 의무다. 그 script가 감싸던 Gradle lane은
|
|
`docs/mongodb/repository-adaptation.md` §5를 본다.
|