Files
clean-architecture-backend-…/docs/fileserver/storage-certification.md
T
DongHyeonka a025f244c7 refactor(repo)!: 쓰지 않는 파일과 운영 인프라 파일을 지운다
문제: 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.
2026-11-07 12:22:47 +09:00

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에서 아래를 차례로 확인한다.

  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에 남긴다:

{
  "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, 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.