문제: 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 문서의 파일 존재만 본다.
90 lines
5.9 KiB
Markdown
90 lines
5.9 KiB
Markdown
# Advanced — Multi-tenancy
|
|
|
|
**Capability:** `MongoCapability.SHARED_COLLECTION_TENANCY`(Advanced),
|
|
`MongoCapability.DATABASE_PER_TENANT`(Experimental)
|
|
**켜는 법:** 라이브러리 API다. 설정 속성은 없다. 서비스의 어댑터가 진입점을 만들 때
|
|
`MongoAdvancedCapabilityGuard`를 넘긴다. 이 guard는 그 capability를 켠 `MongoAdvancedCapabilityFlags`로
|
|
만든다. 켜지 않았으면 생성 자체가 거부된다.
|
|
shared collection tenancy에는 진입점이 없다(타입이 모두 정책이다). 그래서 실제로 검사하는 것은
|
|
`DATABASE_PER_TENANT`뿐이다.
|
|
|
|
## 1. Shared collection
|
|
|
|
모든 tenant의 문서가 collection 하나에 있고, tenant 필드로 구분한다.
|
|
|
|
`MongoTenantContext`가 tenant를 들고 다닌다. `MongoTenantPredicateInjector`가 tenant 조건을 세 곳에
|
|
넣는다: 모든 query, 모든 atomic filter, aggregation의 **첫** stage. 도입하는 쪽의 repository가 tenant
|
|
범위의 모든 경로에서 이 injector를 부른다. 이 leaf에는 tenant 범위 작업을 대신해 주는 facade가 없다.
|
|
|
|
빠지면 안 되는 세부가 셋이다.
|
|
|
|
- **관례가 아니라 주입이다.** query마다 tenant 조건을 스스로 넣기를 기대하면 `where(...)` 하나만 빠져도
|
|
tenant 사이로 데이터가 샌다. injector는 조건을 구조적으로 넣는다.
|
|
- **aggregation 첫 stage.** `firstStageMatch(...)`는 tenant `$match`를 맨 앞에 둔다. tenant filter보다
|
|
먼저 도는 `$lookup`이나 `$group`은 뒤 stage가 결과를 걸러도 이미 경계를 넘은 것이다.
|
|
- **tenant가 없으면 「모든 tenant」가 아니다.** injector는 `Optional<MongoTenantContext>`를 받는다.
|
|
tenant가 빠진 경우를 정책이 명시적으로 정하게 하려는 것이다. 조건이 조용히 사라지면 안 된다.
|
|
|
|
`MongoTenantManifestValidator.validate(manifest, tenantScopedUniqueIndexes)`는 tenant별이어야 하는 unique
|
|
index가 정말 tenant 필드를 포함하는지 본다. shared collection에서 `email` 하나만으로 만든 unique index는
|
|
email을 모든 tenant에 걸쳐 유일하게 만든다. 그러면 tenant A가 쓴 주소를 tenant B가 등록할 수 없다.
|
|
결함이면서 정보 유출이다.
|
|
|
|
`requireShardKeyAnalysed(...)`는 shared collection tenant 모델을 shard하기 전에 shard key 준비 보고서를
|
|
요구한다. tenant id를 shard key 앞부분으로 쓰면 가장 큰 tenant가 shard 하나에 몰린다.
|
|
|
|
### 관측
|
|
|
|
`tenantId`와 `rawTenantId`는 `MongoObservationConvention`의 금지 tag 목록에 있다. 값의 가짓수가 고객
|
|
수만큼 늘고, tag가 tenant 식별자를 metric 저장소로 보낸다.
|
|
|
|
## 2. tenant마다 database (Experimental)
|
|
|
|
`MongoTenantClientRegistry`는 tenant마다 client를 하나 둔다. 개수 상한이 있고 쓰지 않는 client는
|
|
내보낸다. tenant를 어느 database에 대응시킬지는 도입하는 쪽의 코드가 정한다.
|
|
|
|
Experimental인 이유가 분명하다. 작을 때는 맞고, 클 때는 한계가 없다. tenant database마다 connection,
|
|
file handle, 모니터링 가짓수가 든다. tenant 20개에서는 잘 돌고 2,000개에서는 쓰러진다. 기능 테스트로는
|
|
둘을 구분할 수 없다. 승격하려면 운영 규모의 증거가 필요하다.
|
|
|
|
`MongoTenantLifecyclePolicy`:
|
|
|
|
- `requireActivationReady(tenantKey, schemaAndIndexesValidated)` — schema와 index를 검증하기 전에는
|
|
tenant를 켜지 않는다. 먼저 켜면 첫 고객 요청이 마이그레이션 시험이 된다.
|
|
- `requireDeleteAllowed(...)` — 삭제에는 보존 기간에 대한 명시적 결정이 필요하다. tenant database를 지우면
|
|
되돌릴 수 없고 백업 대상도 함께 사라진다.
|
|
|
|
`MongoTenantMigrationCoordinator`는 tenant database 전체에 마이그레이션을 돌리고 결과를 tenant별로 낸다.
|
|
일부 실패는 정상이고 tenant별로 보고해야 한다. database 500개에 대해 「마이그레이션 실패」 한 줄은 아무도
|
|
대응할 수 없는 보고다.
|
|
|
|
## 3. 고르기
|
|
|
|
| | Shared collection | tenant마다 database |
|
|
|---|---|---|
|
|
| 격리 | 논리적, 주입으로 강제 | 물리적 |
|
|
| tenant 수 | 제한 없음 | connection과 file handle이 제한 |
|
|
| tenant별 복구 | 어렵다 | 자연스럽다 |
|
|
| 시끄러운 이웃 | 자원을 나눠 쓴다 | 격리된다 |
|
|
| 마이그레이션 | collection 하나 | database N개, 일부 실패가 생긴다 |
|
|
| tenant를 넘는 query | 가능하다(그래서 막아야 한다) | 구조상 불가능하다 |
|
|
|
|
기본은 shared collection이다. tenant마다 database는 tenant 수가 적고, 계약상 격리나 tenant별 복구가
|
|
필요한 경우에 쓴다.
|
|
|
|
## 4. 실패 복구
|
|
|
|
| 증상 | 원인 | 조치 |
|
|
|---|---|---|
|
|
| 다른 tenant의 데이터가 보인다 | 어떤 작업이 `MongoTenantPredicateInjector`를 건너뛰었다 | 보안 사고로 다룬다. 그 경로를 찾아 막고 접근 기록을 감사한다. |
|
|
| tenant를 넘어 unique 제약이 걸린다 | unique index에 tenant 필드가 없다 | tenant 필드를 앞에 둔 index로 다시 만든다. validator가 배포 전에 잡는다. |
|
|
| shard 하나에 데이터 대부분이 있다 | tenant id가 shard key 앞부분이고 큰 tenant가 하나 있다 | 가짓수가 많은 뒷부분을 더해 shard key를 다듬는다. |
|
|
| connection이 바닥난다 | tenant마다 database가 connection 예산을 넘었다 | 규모 한계다. 합치거나 shared collection으로 옮긴다. |
|
|
| 마이그레이션이 tenant 일부에만 적용됐다 | 정상이다 | `MongoTenantMigrationCoordinator`가 tenant별로 보고한다. 실패한 것만 다시 돌린다. |
|
|
|
|
## 5. 승격 증거
|
|
|
|
shared collection tenancy: 실제 토폴로지 증거, tenant를 넘는 접근을 다룬 보안 검토, 마이그레이션 경로,
|
|
실패 사례(query·atomic filter·aggregation 첫 stage에서 주입이 되는지 증명), 이 runbook.
|
|
tenant마다 database는 여기에 **운영 규모 증거**가 더 필요하고, 그것이 생길 때까지 Experimental이다.
|