문제: docs/mongodb 아래 살아 있는 문서 14개가 영어였고(문서 검사 language 예외), 몇 가지 주장이 지금 코드와 달랐다. - repository-adaptation.md가 registry의 leaf 수(19)와 Spring Boot 버전을 옮겨 적었다(number 예외 두 줄). - 같은 문서와 advanced/signoff/README.md가 scripts/verify-mongodb-platform.sh· verify-mongodb-advanced.sh를 2026-08-15에 지웠다고 했다. 두 스크립트는 지금도 있고 lane을 돌린다. - testkit을 `testkit` source set에 둔다고 했다. 지금은 `testFixtures`(ADR-BUILD-001)와 `mongoProviderTestkit`이다. `…mongo.architecture`도 main이 아니라 testFixtures에 있다. - ArchUnit 규칙 이름 `stableNeverDependsOnAdvanced`·`productionNeverDependsOnTestkit`은 없다. 실제는 MongoModuleBoundaryTest의 `noStablePackageDependsOnAnAdvancedCapability`· `noProductionPackageDependsOnTheTestkit`이다. - support-matrix.md의 Boot·Spring Data·driver·Micrometer·Testcontainers 버전이 lockfile과 달랐다(예: driver 5.6.1 → 5.6.5). - consumer-leaf-guide.md가 템플릿에 없는 Gradle 경로를 인라인 코드로 적었다 (reference 예외). - document-modeling-guide.md가 타입 metadata를 bson-mapping-guide §4로 가리켰다(§5). 고친 방법: 뜻을 그대로 옮기고 식별자·명령·경로·표 구조는 원문으로 둔다. 버전과 leaf 수는 숫자 대신 정본(src/gradle/libs.versions.toml, registry, gradle.lockfile, container-images.properties)을 가리킨다. 서비스가 만들 leaf의 확인 명령은 다른 단계와 같이 코드 블록에 두고 템플릿에 없는 경로라고 밝힌다. 버린 대안: support-matrix 버전을 lockfile 값으로 고쳐 적기. 다음 업그레이드에서 다시 틀리고, 같은 시간에 도는 의존성 세션과 같은 줄을 고치게 된다. 위험·한계: 내용 감사는 하지 않았다. 번역하며 본 불일치만 고쳤다. 설계 번호(§, D-xx)는 그대로 두었다. 검증: python3 scripts/check-docs.py rc=0(이 폴더 language·reference·number 예외 줄 0). docs/mongodb를 읽는 테스트는 주석뿐이다(`grep -rn 'docs/mongodb' src --include=*.java` — package-info.java·MongoModuleBoundaryTest 주석). scripts/verify-mongodb-advanced.sh는 advanced 문서의 파일 존재만 본다.
81 lines
4.9 KiB
Markdown
81 lines
4.9 KiB
Markdown
# Advanced — Sharding
|
|
|
|
**Capability:** `MongoCapability.SHARDING`
|
|
**켜는 법:** 라이브러리 API다. 설정 속성은 없다. 서비스의 어댑터가 진입점을 만들 때
|
|
`MongoAdvancedCapabilityGuard`를 넘긴다. 이 guard는 그 capability를 켠 `MongoAdvancedCapabilityFlags`로
|
|
만든다. 켜지 않았으면 생성 자체가 거부된다.
|
|
**상태:** Advanced. reshard 진행 관리는 Experimental로 남는다.
|
|
|
|
## 요구 사항
|
|
|
|
| | |
|
|
|---|---|
|
|
| 토폴로지 | 실제 sharded cluster. replica set으로는 라우팅을 시험할 수 없다. |
|
|
| 서버 | MongoDB 7.0 또는 8.0. |
|
|
| 권한 | admin plane에는 `MongoPrincipalRole.SHARD_ADMIN`. 애플리케이션 role은 바뀌지 않는다. |
|
|
| 게이트 | **승격하지 않았다.** 등록된 `mongoShardedTest` lane이 없고, sharded cluster는 이 repo가 띄우는 환경이 아니다. `src/adapter/outbound/persistence-mongo/release/release-contracts.json`의 `experimental_contracts`에 있다. 승격하려면 lane, 그 lane이 요구하는 클래스, 보호된 환경의 증거가 먼저 있어야 한다. |
|
|
|
|
## Shard key
|
|
|
|
`ShardKeyDescriptor`는 key를 `ShardKeyPart`의 순서 있는 목록과 `ShardStrategy`로 선언한다.
|
|
|
|
| 전략 | 나누는 기준 | 비용 |
|
|
|---|---|---|
|
|
| `RANGE` | 값의 범위 | 범위 조회가 특정 shard로 간다. 계속 커지는 key(timestamp, `ObjectId`)는 모든 insert를 shard 하나로 보낸다. |
|
|
| `HASHED` | key의 hash | insert가 고르게 퍼진다. 모든 범위 조회가 scatter-gather가 된다. |
|
|
|
|
둘 다 잘하는 전략은 없다. 그래서 기본값으로 두지 않고 선언하게 한다.
|
|
|
|
## 라우팅 분류
|
|
|
|
`ShardAwareQueryValidator`는 실행 전에 query마다 분류한다.
|
|
|
|
| `MongoRoutingClassification` | 뜻 |
|
|
|---|---|
|
|
| `TARGETED` | shard key 전체가 있다. shard 하나가 답한다. |
|
|
| `PREFIX_TARGETED` | 복합 key의 앞부분이 있다. shard 일부가 답한다. |
|
|
| `SCATTER_GATHER` | shard key 조건이 없다. 모든 shard가 답한다. |
|
|
| `REJECTED` | profile이 금지한 곳의 scatter-gather. |
|
|
|
|
scatter-gather는 오류가 아니다. 모든 shard가 필요한 query도 있다. 다만 선언해야 한다. 선언하지 않은
|
|
scatter-gather는 `MongoShardRoutingException`을 던진다. 이유는 이렇다. scatter-gather는 shard 하나짜리
|
|
개발 cluster에서는 모든 테스트를 통과하고 cluster가 커진 뒤에야 느려진다. 그때는 query가 이미 운영에
|
|
있고, 고치려면 schema를 바꿔야 한다.
|
|
|
|
## 지원하지 않는 조합
|
|
|
|
- shard key의 앞부분이 아닌 필드의 unique index. MongoDB가 shard를 넘어 강제할 수 없다. 조회 때가
|
|
아니라 index를 만들 때 실패한다.
|
|
- 여러 shard의 문서를 건드리는 transaction은 지원하지만 shard를 넘는 two-phase commit 비용이 든다.
|
|
transaction의 문서를 한곳에 모으는 shard key를 고른다.
|
|
- sharded collection의 CSFLE: 거부하는 조합은 [encryption.md](encryption.md)를 본다.
|
|
|
|
## Admin plane
|
|
|
|
`MongoShardingAdminGateway`(D4, `SHARD_ADMIN` credential)가 shard-collection, refine-shard-key,
|
|
reshard를 맡는다.
|
|
|
|
`ShardKeyAnalyzer`는 collection을 shard하기 전에 `ShardKeyReadinessReport`를 만든다: 값의 가짓수,
|
|
빈도 치우침, 단조 증가 여부. 가짓수가 적은 key는 나눌 수 없는 jumbo chunk를 만든다. 단조 증가하는
|
|
key는 한 shard에 부하를 몰아준다. 둘 다 보고서에는 보이고 기능 테스트에는 보이지 않는다.
|
|
|
|
reshard에는 `ReshardApproval`이 필요하다: 승인한 사람 이름과 작업 시간대. reshard는 collection을 다시
|
|
쓴다. 작업 중에 데이터를 복제하고 IO를 가득 채운다. 실행 중에 하는 작업이 아니고, 타입도 그런 척하지
|
|
않는다.
|
|
|
|
## 실패 복구
|
|
|
|
| 증상 | 원인 | 조치 |
|
|
|---|---|---|
|
|
| `MongoShardRoutingException` | 선언하지 않은 scatter-gather | 조건에 shard key를 넣는다. 아니면 검토를 거쳐 그 query를 profile에서 scatter-gather로 선언한다. |
|
|
| Jumbo chunk | 가짓수가 적은 shard key | reshard를 생각하기 전에 shard key를 다듬는다(뒷부분을 더한다. 데이터를 지우지 않는다). |
|
|
| 한 shard에 부하가 몰린다 | 단조 증가하는 range key | 가짓수가 많은 앞부분으로 다듬거나, 범위 조회가 필요 없으면 hashed로 reshard한다. |
|
|
| balancer가 끝나지 않는다 | 오래 도는 작업이 chunk 이동을 막는다 | 긴 transaction과 cursor를 찾는다. balancer는 그것들을 기다린다. |
|
|
|
|
## 승격 증거
|
|
|
|
[ADR-MONGO-ADV-001](../../adr/ADR-MONGO-ADV-001-capability-promotion.md)에 따라: 실제 sharded cluster
|
|
증거, `SHARD_ADMIN` role의 보안 검토, 이미 있는 unsharded collection의 마이그레이션 경로, 실패 사례(선언하지
|
|
않은 scatter-gather 거부, jumbo chunk 감지), 그리고 runbook으로서 이 문서. reshard 진행 관리는 운영
|
|
규모 증거가 생길 때까지 Experimental이다.
|