문제: infra/ 43개 중 12개는 코드·테스트·workflow·스크립트 어디서도
읽지 않는다(httpclient·jpa·messaging·notification의 toxiproxy compose와
README). nginx 설정, Kubernetes PVC 인증 job, DB 역할 SQL 셋은 운영
인프라라 개발 repo에 둘 것이 아니다(소유자 결정 2026-11-07). release.yml
의 fileserver-pvc-certification job은 그 매니페스트 문자열만 grep했다.
고른 방법:
- 15개를 지운다.
- 운영 조건만 그 기능 문서에 한국어로 남긴다.
docs/fileserver/operations.md 「운영 환경이 지켜야 할 조건」(nginx
internal location·alias·X-Accel-Redirect 헤더 제거·스트리밍, PVC
ReadWriteOnce·fsGroup), storage-certification.md(인증 절차),
docs/jpa/security.md 「역할과 권한」·「서버 설정」(역할 SQL과
jpa/postgres README 내용), docs/messaging/security.md(인증서 SAN).
httpclient TLS README 내용은 docs/httpclient/security.md에 이미 있다.
- release.yml job과 needs 줄, fileserver-pr.yml·pr-adapters.yml의 지운
경로 필터를 지운다.
- fileserver 지원 표의 "Kubernetes ReadWriteOnce PVC — Limited" 행은
근거 job이 없어져 「주장하지 않음」으로 옮긴다.
버린 대안: 인프라 파일을 project-infra로 옮기기(설계 Q6). 그 repo는
특정 프로젝트용이라 범용 템플릿 파일을 받을 자리가 없다.
위험·한계: 지원 표에서 PVC 주장이 빠진다. 파생 서비스가 그 파일을
배포에 썼다면 병합이 지운다(B-50). 클러스터 인증은 이제 배포하는 쪽이
문서 절차로 한다.
검증(desktop, 트리 749a3328, ~/t1-layout-logs/):
- :composition:fileserver-platform:check :app-bootstrap:check
:app-bootstrap:documentContractTest rc=0 (repositoryContractTest,
FileserverDocumentationCoverageTest 실행)
- :verifyStrictLaneStages --dry-run rc=0
- scripts/verify-compose-profile-contracts.sh rc=0 (18 lane)
- check-work-docs.py, 상대 링크 검사 rc=0
Refs: design-docs repo-structure/01-backend-layout.md 4.4, 6.3
BREAKING CHANGE: infra/fileserver/nginx, infra/fileserver/kubernetes, infra/jpa, infra/httpclient, infra/messaging, infra/notification/toxiproxy와 release.yml fileserver-pvc-certification job이 없어진다. docs/upgrade/2026-11-maturity-review.md B-50.
3.4 KiB
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에서 아래를 차례로 확인한다.
staging과content폴더를 만들고,staging의 파일을content로mv해 원자적 rename이 되는지 본다.- 두 폴더의 장치 번호(
stat -c %d)가 같은지 본다. 다르면 rename이 복사가 된다. set -o noclobber상태에서 같은 파일을 두 번 만들어O_EXCL생성이 막히는지 본다.- 결과와 함께 묶음(Kubernetes 버전, CSI driver, StorageClass, 접근 모드, backend, mount 옵션)을 기록한다.
결과는 묶음 전체를 담은 기계가 읽는 형식으로 그 volume에 남긴다:
{
"kubernetesVersion": "...",
"csiDriver": "...",
"storageClass": "...",
"accessMode": "ReadWriteOnce",
"backend": "ext2/ext3",
"mountOptions": "rw,relatime",
"atomicMove": true,
"sameFileStore": true,
"atomicCreate": true
}
2번이 실패하면 인증하지 않는다. staging과 content가 다른 저장소인 volume은 게시가 소리 없이 복사로 바뀐다.
Network filesystems
docker compose -f infra/fileserver/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, inapplication-fileservertestFixtures (testImplementation testFixtures(project(':application-fileserver'))). The application'sFakeUploadStorageGatewayextends 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 internalBlockingContentStoreSPI, 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.