pr / done (pull_request) Canceled after 0s
S3 control 저장소는 SDK가 응답을 잃고 다시 보낸 조건부 PUT의 412를 충돌로 본다. MongoDB 집계는 결과 바이트 예산을 보지 않고 전부 메모리에 올린다. tenant client registry는 쓰는 중인 client를 내보내고, 내보내다 닫기에 실패하면 다른 tenant의 acquire가 실패한다. migration lease를 잃은 runner가 그 뒤에도 checkpoint를 쓴다. HTTP client는 SOCKS proxy를 HTTP로 붙이고, 압축을 켜면 Apache는 스스로 풀어 max-wire-bytes가 푼 크기를 세며, JDK transport는 그 설정을 읽지 않는다. 고른 방법: S3는 412에서 다시 읽어 이 호출이 쓴 record 그대로면 성공으로 본다. 집계는 $limit(maxResults + 1)과 maxResultBytes를 집행한다. registry acquire는 Lease를 돌려주고 쓰는 중에는 내보내지 않으며 idle은 마지막 close부터 잰다. 상한·lease 수·내보내기는 registry 밖에서 잡을 수 없는 전용 lock 하나로 묶는다. 닫기 실패는 evictionCloseFailures가 센다. migration ledger는 lock 문서의 현재 fence로 쓴다. ProxyType은 HTTP만 남긴다. 압축은 RestClient 기본 헤더로 보내고 ContentDecoding이 버퍼·스트리밍 본문을 모두 푼다(겹친 coding과 그 밖의 coding은 거부, 빈 본문은 빈 본문). Jetty HTTP/3는 기동 뒤 decoder를 비운다. 버린 대안: SOCKS 지원 (transport 셋 중 하나만 된다), transport마다 자동 풀기(크기 상한이 transport마다 달라진다), 집계를 RawBsonDocument로 재기(converter를 거치지 않으면 반환 타입 mapping이 갈라진다). 위험·한계: MongoTenantClientRegistry.acquire 반환형과 ProxyType이 바뀐다. S3에서 두 writer가 같은 버전에서 같은 record를 쓰면 둘 다 성공으로 본다 (Javadoc과 안내 3절). 집계 결과는 converter로만 바뀌어 entity callback이 돌지 않는다. evictionCloseFailures 지표는 지표 묶음에 넘긴다. 검증: desktop RED(pr2-red2). GREEN은 PR 본문의 verify.sh pr 결과. Refs: RR9-01-08, RR9-01-11, RR9-01-19, RR9-01-20, RR9-01-27, RR9-01-28, RR9-01-30, RR9-01-31 BREAKING CHANGE: MongoTenantClientRegistry.acquire가 Lease를 돌려주고, migration lease를 잃은 refresh가 MongoOperationRejectedException을 던진다. HTTP client ProxyType.SOCKS가 없어져 그 설정은 바인딩이 실패한다. request.compression이 모든 transport에서 같은 coding만 받는다. docs/upgrade/2026-11-round9-outbound.md
93 lines
6.3 KiB
Markdown
93 lines
6.3 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에 대응시킬지는 도입하는 쪽의 코드가 정한다. `acquire`는 `Lease`를 돌려주고,
|
|
그 client는 lease를 모두 닫을 때까지 쓰는 중이다. 쓰는 중인 client는 얼마나 오래전에 받았든 내보내지 않는다.
|
|
내보낸 client를 닫다가 실패하면 그 tenant 대신 `evictionCloseFailures()`가 센다. 닫기를 부른 다른 tenant의
|
|
`acquire`는 실패하지 않는다(round9 리뷰 2026-11-12, RR9-01-27).
|
|
|
|
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이다.
|