# 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이다.