Files
clean-architecture-backend-…/docs/fileserver/storage-certification.md
DongHyeonka 914c320799 ci(main): NFS nightly가 nfs·nfsd 두 모듈을 보고 실패 로그를 남긴다
문제: nightly `fileserver-nfs-ambiguity`의 호스트 확인 step은
`/proc/filesystems`에서 `nfsd`만 보고, 실패 안내도 `nfsd`만 올린다.
서버 이미지 erichough/nfs-server 2.2.1의 entrypoint
(`init_runtime_assertions`)는 `nfs`와 `nfsd`를 둘 다 요구하고, `nfsd`를
올려도 `nfs`는 따라오지 않는다. 그래서 안내대로 한 호스트는 확인 step을
지나 compose에서 `exited (1)`로 빨강이 된다. 그 이유는 서버 컨테이너
로그에만 있는데, job에는 로그 step이 없고 `if: always()` 정리 step이
`down -v`로 컨테이너를 지운다(run 52·63에서 서버 출력 줄 0). 시험 step은
`--rerun` 없이 빌드 캐시를 쓰는데, `FILESERVER_NFS_TESTS`는 Java가 실행
중에 읽는 env라 태스크 입력이 아니다. fileserver 입력이 같은 두 번째
run은 `FROM-CACHE`로 NFS 없이 초록일 수 있다.

고친 것:
- 확인 step이 `for module in nfs nfsd`로 둘 다 보고, 빠진 모듈 이름과
  `modprobe -a nfs nfsd`(둘을 주려면 `-a`가 있어야 한다. 없으면 둘째가
  첫째의 모듈 인자가 된다) 명령을 찍는다. 주석도 같은 명령.
- 시험 step에 `--rerun`.
- `if: failure()` step이 `down`보다 앞에서 compose 로그를 찍는다.
- `docs/fileserver/storage-certification.md` 「네트워크 파일 시스템」에
  호스트 모듈 줄과 `--rerun`(이유 한 줄).
- `DeveloperExperienceContractTest`에 시험 셋(tag `repository-contract`,
  `.gitea/**`는 이미 이 lane의 입력이다): 확인 step의 모듈 목록과 안내
  명령의 모듈 목록이 정확히 `nfs`·`nfsd`, 이 job의 Gradle step마다
  `--rerun`, compose `logs`를 부르는 `failure()` step이 `down`보다 앞.
  step 번호나 Gradle을 어디서 부르는지에 기대지 않게 썼다.

버린 안: 확인 step을 지우고 이미지 메시지에 맡기기(로그 step이 생겨도
첫 step이 몇 초 만에 정확한 명령을 주는 편이 낫다). 확인을 scripts/ci/
스크립트로 빼고 fixture로 시험하기(파일 둘이 늘고, 총괄이 고르지 않음).

위험·한계: job이 실제로 초록이 되는지, 고친 확인 step이 모듈을 올린
호스트에서 통과하는지는 소유자가 호스트에 모듈을 넣은 뒤 nightly에서만
볼 수 있다. compose.yml 머리 주석(11행)의 같은 명령에 `--rerun`이 없지만
그 주석은 QA-BE-0001 몫이라 두었다.

리뷰 반영(종류 B 1회, 렌즈 be-build-ci·be-testing·be-security):
- `--rerun`을 shell 낱말로만 봐서 `bash -c "… --rerun"`에서 거짓
  실패 → run 전체에서 `(?<![\w-])--rerun(?![\w-])`로 찾는다.
- `docker compose \` 줄 이음 뒤 `-f`를 놓침 → 백슬래시-줄바꿈을 먼저
  잇는 `scriptWords`를 compose 단계 helper에 쓴다.
- 안내의 부팅 목록(`printf … | sudo tee /etc/modules-load.d/`)을 안 봄
  → 단언을 더하고 모듈 목록 셋 다 `containsExactlyInAnyOrder`.
- then이 given 값을 단언 → when에서 logs step 조건을 만든다.
- `--rerun` 시험 DisplayName 문구.

검증(desktop 공유 잠금, detached worktree, `--no-build-cache`):
- RED: base 3bfefe69(트리 dfae7dc4) + 새 시험 파일(트리 fee22e62)에서
  `./gradlew :app-bootstrap:repositoryContractTest --tests
  'dev.caskeleton.bootstrap.contract.DeveloperExperienceContractTest'`
  rc=1. 이 커밋의 시험 셋이 모듈 목록 없음·`--rerun` 없음·logs step
  없음으로 실패(다음 커밋 시험 포함 4개 실패).
- 이 커밋 트리 85daf7dc에서 `:app-bootstrap:repositoryContractTest`
  rc=0(64개, skip 1).
- 변이(두 커밋 트리 d8fc8e09, 이 시험 class): 확인 step
  `for module in nfsd` rc=1, gradle step `--rerun` 지움 rc=1, logs
  step을 `down` 뒤로 rc=1, 안내 `modprobe nfsd` rc=1, 부팅 목록
  `echo nfsd | sudo tee` rc=1, `bash -c "… --rerun"` rc=0,
  `bash -c "…"`(`--rerun` 없음) rc=1.
- 문서 주장: env 없이 fileserver 시험을 돈 뒤 `FILESERVER_NFS_TESTS=true`로
  다시 돌면 `:adapter:outbound:fileserver:test UP-TO-DATE`.
- 트리 d8fc8e09: desktop `scripts/verify.sh leaf :app-bootstrap
  --no-cache` rc=0(334개), `scripts/verify.sh pr --no-cache` rc=0
  (7343개, 실패 0, skip 35), 노트북 `scripts/verify.sh docs` rc=0.

Refs: CI-BE-0007
2026-11-21 20:12:09 +09:00

4.3 KiB

저장소 인증

인증이 volume마다인 이유

원자적 rename, 같은 파일 저장소 보장, symlink 거부는 「Kubernetes」나 「PVC」의 성질이 아니라 특정 mount 뒤의 특정 파일 시스템의 성질이다. CSI driver, StorageClass, 접근 모드, backend, mount 옵션 중 하나만 바꿔도 그중 무엇이든 달라질 수 있다. 다섯을 모두 적지 않은 인증은 다른 곳으로 옮길 수 없다.

인증하는 것

성질 중요한 이유
staging과 content가 같은 파일 저장소 저장소를 넘는 rename은 복사라서 게시가 원자적이지 않게 된다.
원자적 rename 게시 경로의 기본 전략이다.
원자적 생성(O_EXCL) 게시를 조용한 덮어쓰기가 아니라 새로 만들기만 하게 한다.
symlink 거부 바뀐 부모 폴더가 쓰기를 root 밖으로 돌리는 것을 막는다.
범위 읽기 다운로드 계약이 기댄다.

인증 돌리기

이 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은 게시가 소리 없이 복사로 바뀐다.

네트워크 파일 시스템

호스트 커널에 nfs·nfsd 모듈이 둘 다 올라와 있어야 한다. 서버 이미지는 둘 중 하나라도 없으면 바로 끝나고, nfsd를 올려도 nfs는 따라오지 않는다. 올리는 명령은 .gitea/workflows/main.yml fileserver-nfs-ambiguity job 주석과 같다.

docker compose -f src/adapter/outbound/fileserver/compose/nfs/compose.yml up -d
FILESERVER_NFS_TESTS=true ./gradlew :adapter:outbound:fileserver:test --rerun

--rerun을 붙이는 이유: FILESERVER_NFS_TESTS는 시험이 실행 중에 읽는 환경 변수라 태스크 입력이 아니다. env 없이 한 번 돈 뒤 env를 켜고 다시 돌면 태스크가 UP-TO-DATE로 끝나 NFS 시험이 돌지 않는다.

mount는 일부러 hard다. soft mount는 느린 서버를 짧게 끝난 쓰기로 바꾼다. 이 설계가 받아들이지 않는 바로 그 손상이다.

시작 때 강제

FileserverStartupValidator가 부팅 때 probe를 다시 돌리고, 필수 capability가 없으면 요청을 받지 않는다. 원자적 move를 증명하지 못하는 파일 시스템에 ATOMIC_MOVE_REQUIRED를 두면 조용히 기능을 줄이지 않고 닫힌 쪽으로 실패한다.

새 저장소 더하기

실행되는 계약 둘을 통과해야 한다. 글로 쓴 호환 주장은 받지 않는다.

  • UploadStoragePortContract — 애플리케이션 port의 계약이다. application-fileserver testFixtures에 있다 (testImplementation testFixtures(project(':application-fileserver'))). 애플리케이션의 FakeUploadStorageGateway도 이것을 상속한다. 그래서 use case 테스트와 실제 저장소가 같은 offset, chunk checksum, 크기 상한 규칙을 지킨다(0바이트로 선언한 업로드는 첫 바이트를 거부한다).
  • ContentStoreContract — 로컬 어댑터의 내부 BlockingContentStore SPI 계약이다. 이 어댑터의 테스트에 있다. 그 SPI는 일부러 어댑터 안에 둔다(리뷰 S1-#12: 애플리케이션은 그것을 부르지 않는다). 그래서 계약도 어댑터에 있다. 그 SPI를 다시 쓰는 저장소도 이것을 상속한다.