문제: 앞 커밋이 Gradle 루트를 저장소 루트로 옮기고 계층 폴더를 묶었다.
빌드 스크립트·build-logic·시험·workflow·스크립트·문서가 아직 옛 배치
(Gradle 루트 = src/)를 가정해 빌드가 되지 않는다.
고른 방법:
- Gradle 경로와 registry id는 그대로 둔다(:app-bootstrap, :application-core,
:composition:*). registry의 source_path만 새 폴더를 가리킨다. 폴더에 맞춘
이름(:domain:core, :application:core)은 프로젝트 이름 core가 둘이 되어
boot jar의 BOOT-INF/lib와 기본 capability가 겹치고, 파생 서비스의 모든
project(':…') 줄을 바꾸게 한다.
- registry는 gradle/modules.json, 시험 이미지 목록은
gradle/container-images.properties: 버전 카탈로그 옆, 빌드가 고정하는 것.
config/는 코드 검사 도구 설정만 둔다.
- build-logic: settings·architecture 플러그인의 저장소 루트를 Gradle 루트로
(getParentFile 제거). config contract의 파일 트리는 src/만 훑는다(루트를
훑으면 docs·.claude/worktrees까지 줍는다).
- 빌드 스크립트: rootProject.projectDir.parentFile → rootProject.projectDir,
rootProject.file('../…') → rootProject.file('…'), 옛 src 기준 include에
src/를 붙인다. notification API surface의 application-notification 소스
루트를 새 폴더로(놓치면 272개 타입이 surface에서 말없이 빠진다).
- 시험: 옛 src 기준 모듈 목록과 ../ 개수를 고친다. 없는 폴더를 말없이
건너뛰던 목록(MessagingAuthority, NotificationPayloadAtRest 등)을 새
폴더로, FileserverDocumentationCoverageTest는 Gradle 경로 → 폴더를
registry로 찾는다. Docker 계약은 WORKDIR /build, 새 jar 경로.
- Docker: 빌드 context를 저장소 루트로, .dockerignore는 허용 목록으로 다시
써서 전에 context였던 것만 들어가게 한다. compose의 build.context는 .,
env_file은 ./.env.
- workflow: working-directory: src 기본값과 그것을 되돌리던 줄을 지운다.
- scripts: verify.sh, ci/*, bootstrap-local, new-feature,
verify-feature-scaffold, mongo 검증, hooks, check-repo-layout 허용 목록.
check-docs의 경로 검사는 build-logic/·gradle/로 시작하는 경로도 본다.
- 문서: AGENTS.md 지도, README 구조 표, leaf AGENTS.md의 cd src, gates·
operate·결정 색인, src/bootstrap/AGENTS.md를 조립 계층 family 규칙으로
다시 쓴다. 기록 문서(docs/design·history·reviews, 지난 upgrade 안내,
capability-status 제거 표)는 머리 블록만 고친다. 파생 서비스용 안내
docs/upgrade/2026-11-relayout.md를 더한다.
위험: bootRun working dir가 저장소 루트가 되어 .env와 상대 경로 설정이
루트 기준이다. 루트 .env는 compose 보간에도 읽힌다(upgrade 안내 5절).
파생 서비스는 태그 pre-relayout-2026-11까지 받은 뒤 이 묶음을 받는다.
검증: desktop에서 캐시 없이 scripts/verify.sh docs·pr·main·release,
compose smoke 18 lane, 빠른 시작(scripts/verify.sh app). 결과는 PR 본문.
구조 리뷰(arch-reviewer) 지적 5건을 반영했다.
BREAKING CHANGE: Gradle은 저장소 루트에서 돈다(cd src 없음). registry는
gradle/modules.json, 이미지 빌드 context는 저장소 루트다. 옛 경로 → 새 경로
표는 docs/upgrade/2026-11-relayout.md.
Refs: design-docs repo-structure/01-backend-layout.md 6.1절 가-2·가-3
141 lines
7.8 KiB
Markdown
141 lines
7.8 KiB
Markdown
# 보안과 관측
|
|
|
|
설계서 §26–§28, 결정 D-05. 애플리케이션 plane과 admin plane은 다른 client 위의 다른 credential이다.
|
|
그리고 telemetry는 절대 데이터 유출 경로가 되지 않는다.
|
|
|
|
## 1. Role
|
|
|
|
`MongoPrincipalRole` — role마다 credential 하나, 최소 권한:
|
|
|
|
| Role | 주는 권한 |
|
|
|---|---|
|
|
| `APP_READ` | 허용 목록 collection의 `find` |
|
|
| `APP_WRITE` | 허용 목록 collection의 `insert`, `update`, `delete` |
|
|
| `CHANGE_STREAM` | `changeStream`, `find` |
|
|
| `MIGRATION` | 대상 collection의 index·validator 관리 |
|
|
| `SEARCH_ADMIN` | 검색 index 관리 |
|
|
| `SHARD_ADMIN` | shard key 작업 |
|
|
| `ENCRYPTION_ADMIN` | key vault 접근 |
|
|
| `DBA` | 사람의 plane. 애플리케이션은 절대 쓰지 않는다 |
|
|
|
|
`MongoSecurityProfileValidator`가 시작할 때 profile을 검사한다. `forbiddenPrivilegesHeld()`는 profile이 갖고
|
|
있으면 안 되는데 가진 권한의 이름을 댄다. validator가 *어느* 권한인지 말하는 이유는, 이름 없이 「credential
|
|
권한이 너무 크다」고만 하면 대응할 수 없는 발견이기 때문이다.
|
|
|
|
애플리케이션 credential에 절대 있으면 안 되는 권한: `dropDatabase`, `dropCollection`, `shutdown`, `killop`,
|
|
`root`, `__system`, `dbOwner`, `userAdminAnyDatabase`.
|
|
|
|
## 2. Credential은 값이 아니라 참조다
|
|
|
|
`MongoCredentialReference`는 `secret://…` 참조와 role을 가진다. 참조는 연결할 때 secret provider가 푼다.
|
|
비밀번호는 속성 값, 로그 필드, stack trace에 남을 수 있는 생성자 인자가 절대 되지 않는다.
|
|
|
|
`MongoCredentialRotationPolicy`가 교체 계약을 말한다: 유효 기간이 겹치고, 비우는 구간(drain window)이 있고,
|
|
교체에 재시작이 필요 없다. `MongoClientGenerationRegistry`가 바꿔 끼우기를 구현한다. 새
|
|
`MongoClientGeneration`이 새 연산을 받는 동안 앞 세대는 `markDraining()` 상태로 처리 중인 연산이 끝날 때까지
|
|
남는다. 옛 client를 바로 죽이면 처리 중인 요청이 모두 실패한다. 세대 없는 교체가 장애인 이유다.
|
|
|
|
교체는 릴리스 게이트의 failover 시나리오(`MongoFailoverScenario.CREDENTIAL_ROTATION`)다. 잘 되기를 바라는
|
|
runbook 단계가 아니다.
|
|
|
|
## 3. TLS와 연결 정책
|
|
|
|
`MongoSecurityProfile.production(...)`은 TLS를 요구하고 `tlsAllowInvalidCertificates` /
|
|
`tlsAllowInvalidHostnames`를 거부한다. `MongoSecurityProfile.local(...)`이 있는 것은 개발자가 container에
|
|
붙으려고 production factory를 약하게 만들지 않게 하려는 것이다. 시작 validator는 운영 runtime profile에서
|
|
local profile을 거부한다.
|
|
|
|
## 4. Admin plane (D4)
|
|
|
|
`MongoAdminGateway`가 `MongoAdminOperation`으로 가는 유일한 길이고, 애플리케이션 것이 아니라 DBA 범위
|
|
credential을 쓰는 D4 client에서 돈다.
|
|
|
|
- `MongoAdminAuthorization`이 호출자의 role을 연산과 대조한다.
|
|
- `MongoAdminRuntimeGuard`는 runtime profile이 명시적으로 허락하지 않으면 위험한 연산(`highRisk()`)을
|
|
거부한다. 실행 중인 애플리케이션에서 닿을 수 있는 `dropCollection`은 호출 코드를 아무리 잘 검토했어도
|
|
데이터 손실 경로다.
|
|
- `MongoAdminAuditRecord`가 누가 무엇을, 언제, 어느 collection profile에 돌렸는지 실행 *전에* 기록한다.
|
|
그래서 실패한 시도도 남는다.
|
|
|
|
native capability gateway(D3)는 admin 분류의 명령을 모두 거부한다. 그래서 애플리케이션 plane에서 admin
|
|
plane으로 가는 길은 없다.
|
|
|
|
## 5. 관측 tag
|
|
|
|
`MongoObservationConvention`은 tag 이름을 정확히 여덟 개만 허용한다.
|
|
|
|
```
|
|
mongoProfile, databaseProfile, collectionProfile, operationName,
|
|
operationType, result, failureCategory, consistencyProfile
|
|
```
|
|
|
|
그리고 다음을 명시적으로 금지한다.
|
|
|
|
```
|
|
documentId, rawTenantId, tenantId, dynamicCollectionName, queryParameter,
|
|
query, fullBson, resumeToken, shardKeyValue, plaintextPII, credential
|
|
```
|
|
|
|
이유는 둘이고 둘 다 중요하다. 가짓수: 값이 문서 id인 tag는 문서마다 시계열 하나를 만들고, 그렇게 metric
|
|
저장소가 쓰러진다. 기밀성: metric label은 DB와 접근 모델이 다른 시스템이 저장하고, 보내고, 보관한다.
|
|
`requireAllowed(tagName)`는 목록 밖의 것에 예외를 던진다. 그래서 새 tag는 서비스 코드의 한 줄이 아니라
|
|
convention의 의도적인 변경이 된다.
|
|
|
|
`MicrometerMongoOperationObserver`가 `MongoOperationObserver` port를 구현한다. 기본값은
|
|
`NoOpMongoOperationObserver`라서 관측은 켜야 생기고 필수 의존이 되지 않는다.
|
|
|
|
## 6. Driver 자체 listener
|
|
|
|
`MongoDriverObservabilityConfiguration`은 driver listener 셋을 등록한다. 애플리케이션 수준 timer로는 답할 수
|
|
없는 질문에 답하기 때문이다.
|
|
|
|
| Listener | 답하는 질문 |
|
|
|---|---|
|
|
| `MongoCommandObservationListener` | *서버*가 걸린 시간과 호출자가 기다린 시간은 각각 얼마인가? |
|
|
| `MongoPoolObservationListener` | 기다린 시간이 query 실행이 아니라 connection checkout이었나? |
|
|
| `MongoSdamObservationListener` | 그 구간에 토폴로지가 바뀌었나 — 선출, 노드 빠짐? |
|
|
|
|
pool과 SDAM 이벤트가 없으면 모든 failover가 「DB가 느려졌다」로 보이고, 「pool을 늘려야 한다」와
|
|
「primary를 잃었다」의 차이가 보이지 않는다.
|
|
|
|
## 7. 명령 가리기
|
|
|
|
`MongoObservationRedactor.describe(commandName)`:
|
|
|
|
- 인증·사용자 관리 명령(`authenticate`, `saslStart`, `saslContinue`, `getnonce`, `createUser`,
|
|
`updateUser`, `copydb*`)은 `<redacted>`로 보인다. 인자에 credential과 key 재료가 있다.
|
|
- 구조 명령(`ping`, `hello`, `buildInfo`, `listCollections`, `listIndexes`, `collStats`)은 이름으로
|
|
보인다. 인자에 데이터가 없다.
|
|
- 나머지는 모두 `name(...)`으로 보인다. 명령은 보이고 filter나 문서는 보이지 않는다.
|
|
|
|
`isAlwaysRedacted(...)`는 테스트가 어떤 로그 경로도 인증 명령의 인자를 그리지 못함을 증명하는 단언 hook이다.
|
|
|
|
## 8. 시작 검증
|
|
|
|
`MongoStartupValidator`는 context refresh 때, 첫 요청 전에 돈다.
|
|
|
|
1. `MongoTopologyProbe`가 실제 `MongoTopology`와 그 `MongoCapabilitySet`을 보고한다.
|
|
2. profile마다 선언한 토폴로지가 그것과 맞아야 하고, `STANDALONE` 위의 production profile은 실패한다.
|
|
3. `platform.transactions=true`이면 probe가 `TRANSACTION`을 `STABLE`로 보고해야 한다. `STANDALONE`에서는
|
|
그렇지 않으므로 시작이 실패한다.
|
|
4. `MongoSecurityProfileValidator`가 credential과 TLS, 그리고 admin credential이 runtime credential과
|
|
다른지를 검사한다. `MongoSchemaVersionRange`는 거꾸로면 안 된다.
|
|
5. `MongoPlatformHealthIndicator`가 readiness probe에 토폴로지 불일치와 secondary 가용성을 보고한다.
|
|
|
|
시작할 때 발견한 설정 오류는 배포 한 번 실패로 끝난다. 같은 오류를 실행 중에 발견하면 장애가 되고, 실패한
|
|
연산이 원인을 드러내는 일은 드물다.
|
|
|
|
## 9. 보안 lane이 이것을 어떻게 증명하나
|
|
|
|
```bash
|
|
./gradlew :adapter:outbound:persistence-mongo:mongoSecurityIntegrationTest --console=plain
|
|
```
|
|
|
|
이 lane은 `MongoAuthenticatedReplicaSetContainer`에서 돈다. 이것은 `--auth`와 생성한 keyfile로 mongod를
|
|
띄운다. 그 세부가 lane의 전부다. Testcontainers의 `MongoDBContainer`는 mongod를 `--auth` *없이* 띄운다.
|
|
그 위에서 만든 사용자는 모두 모든 권한을 가지므로, role이 아무리 틀려도 최소 권한 단언이 통과한다. 실패할
|
|
수 없는 보안 테스트는 보안 테스트가 아니다.
|
|
|
|
lane이 단언하는 것은 거부다. `read` role의 insert가 거부되고, 애플리케이션 role의 `dropDatabase`가
|
|
거부된다. 그다음 `MongoSecurityProfileValidator`가 서버가 방금 거부한 바로 그 권한을 이름으로 대는지 본다.
|