문제:
- 루트 compose 6개와 infra/ 아래 12개가 개발 환경, 테스트 lane fixture,
보조 파일을 가리지 않고 섞여 있다. 이름 모양도 셋이다.
- README 빠른 시작 scripts/bootstrap-local.sh는 docker-compose.yml과
.local.yml만 합친 뒤, 둘 어디에도 없는 db 서비스를 띄우려다 멈춘다.
- compose smoke all-adapters lane은 앱이 mem_limit 512m를 넘어 커널에
죽고(OOM), restart: unless-stopped로 다시 떠서 죽는 때가 smoke 요청과
겹칠 때만 실패한다. smoke는 재시작을 보지 않아 나머지 실행은 거짓 통과다.
고른 방법(소유자 결정 2026-11-07):
- 루트에 개발용 compose.yaml 하나. app(local 런타임)과 뒷단 서비스를
capability profile(jpa, redis, kafka, mongo, objectstorage, auth, mail)로
고른다. 마운트하는 보조 파일은 compose/(keycloak, minio init, Redis ACL,
mailpit 인증서 폴더).
- lane fixture는 lane을 가진 leaf로: dev·prod-smoke·tls overlay, fileserver
overlay, smoke·스키마 적용 서비스(lane-services.yaml)와 스크립트, lane
계약 JSON → src/app-bootstrap/compose-lanes/. Redis topology →
redis-sdk/compose/, NFS → fileserver/compose/nfs/. infra/는 없어진다.
- 계약의 composeProfile(문자열)을 composeProfiles(목록)로 바꾼다. lane이
backing profile과 lane profile을 함께 켠다. 18 lane의 서비스 집합은
전과 같다(verify-compose-profile-contracts.sh가 정확히 대조).
- smoke: lane이 끝나기 전에 그 project의 모든 컨테이너가 재시작 0,
OOMKilled false인지 보고 아니면 실패한다. 앱의 memory.peak를 증거로
남긴다. all-adapters만 appMemoryLimit 1g(계약 칸, smoke가 overlay에 씀).
- bootstrap-local.sh는 compose.yaml로 db와 app을 띄운다(인자 없음).
- 개발 compose와 lane 바탕이 같은 파일이라, app healthcheck는 모든
런타임에서 답하는 관리 포트 readiness로 둔다.
버린 대안: lane을 Testcontainers로 옮기기(설계 다-2, 별도 판단), lane마다
기본 메모리를 올리기(배포 기본값 512m 계약을 흐림).
위험·한계:
- 개발 compose의 app이 src/.env를 읽으므로, 개발자 src/.env가 dev·prod
lane에도 들어간다. lane 값은 생성 overlay의 environment가 이기고, CI에는
src/.env가 없다.
- MinIO 이미지 기본값이 compose.yaml과 lane-services.yaml 두 곳에 있다
(YAML anchor는 파일을 넘지 못한다). ComposeMinioImageMatchesEvidenceTest가
둘 다 evidence digest와 대조한다.
- env 키 검사(verifyEnvKeys)는 compose.yaml과 lane overlay를 읽고
lane-services.yaml(smoke client 변수)은 뺀다.
검증(desktop, 트리 6d1e9f9d → 주석·문서만 고친 d0703901, ~/t1-layout-logs/):
- verify-compose-profile-contracts.sh rc=0 (18 lane 정확히 일치)
- :app-bootstrap:check :app-bootstrap:documentContractTest
:app-bootstrap:verifyEnvKeys와 objectstorage·cache-redis·redis-sdk·
redis-runtime·fileserver·composition:fileserver-platform check rc=0
- :app-bootstrap:integrationTest(ComposeMergeCharacterizationTest 포함),
:adapter:outbound:cache-redis:redisContainerContractTest rc=0
- -p build-logic check rc=0, :verifyStrictLaneStages --dry-run rc=0
- scripts/run-compose-runtime-smoke.sh --matrix(18 lane) rc=0, 794초.
모든 lane 컨테이너 재시작 0·OOMKilled false. 앱 memory.peak 최고
all-adapters 532MiB(512m 한도를 넘는 값이라 1g의 근거), 나머지 244~422MiB
- scripts/bootstrap-local.sh rc=0(db·app 기동, /api/healthcheck 200 UP).
기준 ac03192d의 base+local 조합은 config --services가 app뿐이고
up --wait db가 "no such service: db"로 rc=1
- 정리할 때 `docker compose down`은 profile 서비스(db)를 남겨
README·compose.yaml 안내를 `--profile '*' down`으로 고치고 다시 확인
- 주석·문서 수정 뒤 :app-bootstrap:repositoryContractTest
:app-bootstrap:documentContractTest, verify-compose rc=0
Refs: design-docs repo-structure/README.md 3.1, repo-structure/01-backend-layout.md 6.3
BREAKING CHANGE: 루트 docker-compose*.yml과 infra/가 없어지고 compose.yaml(profile)·compose/·leaf 안 lane fixture로 옮겨졌다. lane 계약은 src/app-bootstrap/compose-lanes/compose-profile-contracts.json, composeProfile → composeProfiles. docs/upgrade/2026-11-maturity-review.md B-51.
76 lines
3.4 KiB
Markdown
76 lines
3.4 KiB
Markdown
# Storage certification
|
|
|
|
## Why a certification is per-volume
|
|
|
|
Atomic rename, same-file-store guarantees, and symlink refusal are properties of a specific
|
|
filesystem behind a specific mount — not of "Kubernetes" or "a PVC". Change the CSI driver, the
|
|
StorageClass, the access mode, the backend, or the mount options and any of them can differ. A
|
|
certification that does not name all five is not transferable.
|
|
|
|
## What is certified
|
|
|
|
| Property | Why it matters |
|
|
|---|---|
|
|
| Same file store for staging and content | A rename across stores is a copy, so publication stops being atomic. |
|
|
| Atomic rename | The publish path's default strategy. |
|
|
| Atomic create (`O_EXCL`) | Makes a publish create-only rather than a silent overwrite. |
|
|
| Symlink refusal | Stops a replaced parent from redirecting a write outside the root. |
|
|
| Ranged read | The download contract depends on it. |
|
|
|
|
## Running the certification
|
|
|
|
이 repo는 인증 job 매니페스트를 두지 않는다(2026-11-07 소유자 결정). 배포하는 쪽이 대상 volume을 저장
|
|
루트(`/var/lib/backend/files`)에 마운트한 일회성 pod에서 아래를 차례로 확인한다.
|
|
|
|
1. `staging`과 `content` 폴더를 만들고, `staging`의 파일을 `content`로 `mv`해 원자적 rename이 되는지 본다.
|
|
2. 두 폴더의 장치 번호(`stat -c %d`)가 같은지 본다. 다르면 rename이 복사가 된다.
|
|
3. `set -o noclobber` 상태에서 같은 파일을 두 번 만들어 `O_EXCL` 생성이 막히는지 본다.
|
|
4. 결과와 함께 묶음(Kubernetes 버전, CSI driver, StorageClass, 접근 모드, backend, mount 옵션)을 기록한다.
|
|
|
|
결과는 묶음 전체를 담은 기계가 읽는 형식으로 그 volume에 남긴다:
|
|
|
|
```json
|
|
{
|
|
"kubernetesVersion": "...",
|
|
"csiDriver": "...",
|
|
"storageClass": "...",
|
|
"accessMode": "ReadWriteOnce",
|
|
"backend": "ext2/ext3",
|
|
"mountOptions": "rw,relatime",
|
|
"atomicMove": true,
|
|
"sameFileStore": true,
|
|
"atomicCreate": true
|
|
}
|
|
```
|
|
|
|
2번이 실패하면 인증하지 않는다. staging과 content가 다른 저장소인 volume은 게시가 소리 없이 복사로 바뀐다.
|
|
|
|
## Network filesystems
|
|
|
|
```bash
|
|
docker compose -f src/adapter/outbound/fileserver/compose/nfs/compose.yml up -d
|
|
FILESERVER_NFS_TESTS=true ./gradlew :adapter:outbound:fileserver:test
|
|
```
|
|
|
|
The mount is `hard`, deliberately. A `soft` mount converts a slow server into a short write, which
|
|
is exactly the corruption this design refuses to accept.
|
|
|
|
## Startup enforcement
|
|
|
|
`FileserverStartupValidator` re-runs the probe at boot and refuses to accept traffic when a required
|
|
capability is missing — `ATOMIC_MOVE_REQUIRED` on a filesystem that cannot prove an atomic move
|
|
fails closed rather than degrading silently.
|
|
|
|
## Adding a new store
|
|
|
|
Pass two executable contracts. A prose claim of compatibility is not accepted.
|
|
|
|
- `UploadStoragePortContract` — the application port's contract, in `application-fileserver`
|
|
testFixtures (`testImplementation testFixtures(project(':application-fileserver'))`). The
|
|
application's `FakeUploadStorageGateway` extends it too, so use case tests and the real store obey
|
|
the same offset, chunk-checksum and size-ceiling rules (a declared 0-byte upload refuses its first
|
|
byte).
|
|
- `ContentStoreContract` — the local adapter's internal `BlockingContentStore` SPI, in this
|
|
adapter's tests. That SPI stays in the adapter by design (review S1-#12: the application never
|
|
calls it), so its contract stays with it; a store that reuses the SPI extends it as well.
|