문제: 앞 커밋이 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
7.8 KiB
보안과 관측
설계서 §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 때, 첫 요청 전에 돈다.
MongoTopologyProbe가 실제MongoTopology와 그MongoCapabilitySet을 보고한다.- profile마다 선언한 토폴로지가 그것과 맞아야 하고,
STANDALONE위의 production profile은 실패한다. platform.transactions=true이면 probe가TRANSACTION을STABLE로 보고해야 한다.STANDALONE에서는 그렇지 않으므로 시작이 실패한다.MongoSecurityProfileValidator가 credential과 TLS, 그리고 admin credential이 runtime credential과 다른지를 검사한다.MongoSchemaVersionRange는 거꾸로면 안 된다.MongoPlatformHealthIndicator가 readiness probe에 토폴로지 불일치와 secondary 가용성을 보고한다.
시작할 때 발견한 설정 오류는 배포 한 번 실패로 끝난다. 같은 오류를 실행 중에 발견하면 장애가 되고, 실패한 연산이 원인을 드러내는 일은 드물다.
9. 보안 lane이 이것을 어떻게 증명하나
./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가 서버가 방금 거부한 바로 그 권한을 이름으로 대는지 본다.