Files
clean-architecture-backend-…/docs/mongodb/advanced/multi-tenancy.md
T
DongHyeonka 24eb1be36d docs(mongodb): MongoDB 운영 문서를 한국어로 옮기고 코드와 맞춘다
문제: 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 문서의 파일 존재만 본다.
2026-11-07 17:29:57 +09:00

5.9 KiB

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