From a025f244c7384b623b92bfb70e910a5d32040337 Mon Sep 17 00:00:00 2001 From: DongHyeonka Date: Sat, 7 Nov 2026 12:22:47 +0900 Subject: [PATCH] =?UTF-8?q?refactor(repo)!:=20=EC=93=B0=EC=A7=80=20?= =?UTF-8?q?=EC=95=8A=EB=8A=94=20=ED=8C=8C=EC=9D=BC=EA=B3=BC=20=EC=9A=B4?= =?UTF-8?q?=EC=98=81=20=EC=9D=B8=ED=94=84=EB=9D=BC=20=ED=8C=8C=EC=9D=BC?= =?UTF-8?q?=EC=9D=84=20=EC=A7=80=EC=9A=B4=EB=8B=A4?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 문제: 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. --- .github/workflows/fileserver-pr.yml | 2 - .github/workflows/pr-adapters.yml | 1 - .github/workflows/release.yml | 22 --- docs/ci-cd/boundary.md | 10 +- docs/fileserver/operations.md | 40 +++++- docs/fileserver/storage-certification.md | 16 ++- docs/fileserver/support-matrix.md | 9 +- docs/jpa/repository-adaptation.md | 2 +- docs/jpa/runbooks.md | 6 +- docs/jpa/security.md | 36 ++++- docs/messaging/security.md | 4 + docs/upgrade/2026-11-maturity-review.md | 3 +- docs/work/reference/decisions.md | 1 + .../compose/docker-compose.fileserver.yml | 4 +- .../kubernetes/pvc-certification-job.yaml | 127 ------------------ infra/fileserver/nginx/nginx.conf | 67 --------- infra/httpclient/README.md | 12 -- infra/httpclient/oauth2/README.md | 12 -- infra/httpclient/proxy/README.md | 12 -- infra/httpclient/tls/README.md | 16 --- infra/httpclient/toxiproxy/compose.yaml | 17 --- infra/jpa/postgres/README.md | 39 ------ infra/jpa/roles/runtime-roles.sql | 54 -------- infra/jpa/toxiproxy/docker-compose.yml | 43 ------ infra/messaging/kafka/docker-compose.yml | 33 ----- infra/messaging/postgres/docker-compose.yml | 27 ---- infra/messaging/tls/README.md | 35 ----- infra/messaging/toxiproxy/docker-compose.yml | 18 --- .../notification/toxiproxy/docker-compose.yml | 94 ------------- src/composition/fileserver-platform/README.md | 2 +- 30 files changed, 99 insertions(+), 665 deletions(-) delete mode 100644 infra/fileserver/kubernetes/pvc-certification-job.yaml delete mode 100644 infra/fileserver/nginx/nginx.conf delete mode 100644 infra/httpclient/README.md delete mode 100644 infra/httpclient/oauth2/README.md delete mode 100644 infra/httpclient/proxy/README.md delete mode 100644 infra/httpclient/tls/README.md delete mode 100644 infra/httpclient/toxiproxy/compose.yaml delete mode 100644 infra/jpa/postgres/README.md delete mode 100644 infra/jpa/roles/runtime-roles.sql delete mode 100644 infra/jpa/toxiproxy/docker-compose.yml delete mode 100644 infra/messaging/kafka/docker-compose.yml delete mode 100644 infra/messaging/postgres/docker-compose.yml delete mode 100644 infra/messaging/tls/README.md delete mode 100644 infra/messaging/toxiproxy/docker-compose.yml delete mode 100644 infra/notification/toxiproxy/docker-compose.yml diff --git a/.github/workflows/fileserver-pr.yml b/.github/workflows/fileserver-pr.yml index 780ab5f2..be41d5fc 100644 --- a/.github/workflows/fileserver-pr.yml +++ b/.github/workflows/fileserver-pr.yml @@ -25,8 +25,6 @@ on: - 'docs/registries/env-keys.yaml' - 'src/Dockerfile' - 'docker-compose.yml' - - 'infra/fileserver/nginx/**' - - 'infra/fileserver/kubernetes/**' - 'infra/fileserver/nfs/**' - '.github/workflows/fileserver-pr.yml' # Every Gradle job here installs its toolchain through this composite action, so a change to diff --git a/.github/workflows/pr-adapters.yml b/.github/workflows/pr-adapters.yml index 11f0633a..da1ca9f6 100644 --- a/.github/workflows/pr-adapters.yml +++ b/.github/workflows/pr-adapters.yml @@ -123,7 +123,6 @@ jobs: '^src/config/architecture/modules\.json$' \ '^docs/jpa/' \ '^docs/adr/ADR-JPA-' \ - '^infra/jpa/' \ "${common}" # The servlet system contract on both containers the template supports (Tomcat, Jetty). Real diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml index 654739fe..e1c5b2d7 100644 --- a/.github/workflows/release.yml +++ b/.github/workflows/release.yml @@ -326,27 +326,6 @@ jobs: :composition:fileserver-platform:test --tests '*FileserverDocumentationCoverageTest' --stacktrace - fileserver-pvc-certification: - runs-on: ubuntu-latest - timeout-minutes: 45 - steps: - - uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # actions/checkout@v4.2.2 - # This job checks the manifest, and only the manifest; it applies nothing to a cluster. The - # cluster result comes from an operator running infra/fileserver/kubernetes/ - # pvc-certification-job.yaml and recording it in docs/fileserver/storage-certification.md, - # where the absence of a cluster result is stated rather than hidden behind a green check. - - name: Check the certification manifest still says what the claim depends on - run: | - set -euo pipefail - manifest=infra/fileserver/kubernetes/pvc-certification-job.yaml - test -f "$manifest" - grep -q 'kind: PersistentVolumeClaim' "$manifest" - grep -q 'kind: Job' "$manifest" - # ReadWriteMany is explicitly not claimed; a manifest that quietly widened the access - # mode would certify a topology the support matrix says is uncertified. - grep -q 'ReadWriteOnce' "$manifest" - ! grep -q 'ReadWriteMany' "$manifest" - fileserver-sensitive-telemetry-scan: runs-on: ubuntu-latest timeout-minutes: 20 @@ -372,7 +351,6 @@ jobs: - jpa-registry-and-docs - fileserver-full-verification - fileserver-documentation-gate - - fileserver-pvc-certification - fileserver-sensitive-telemetry-scan # Job-level, because a job that declares `permissions:` replaces the workflow set entirely: this # job and app-image-signing are the only ones that write anything anywhere, and diff --git a/docs/ci-cd/boundary.md b/docs/ci-cd/boundary.md index 3869355f..1281e831 100644 --- a/docs/ci-cd/boundary.md +++ b/docs/ci-cd/boundary.md @@ -60,12 +60,10 @@ GitHub Actions 워크플로는 `kubectl apply`, `helm upgrade`, `argocd app sync | Argo CD Application 정의 | **없음.** GitOps 저장소에 둘 예정 | | CI에서의 클러스터 접근 | 없음 — 유일했던 `kubectl apply`는 제거됨 | -`release.yml`의 fileserver certification 잡(`fileserver-pvc-certification` 등, 예전 -`fileserver-certification.yml`)은 예외처럼 보이지만 아니다. PVC 매니페스트가 여전히 ReadWriteOnce를 -선언하는지 **파일만** 확인하고, 클러스터에는 아무것도 적용하지 않는다. 실제 클러스터에서의 인증은 -운영자가 `infra/fileserver/kubernetes/pvc-certification-job.yaml`을 직접 실행하고 -`docs/fileserver/storage-certification.md`에 기록한다. 잡 이름이 "release"가 아니라 "certification"인 -이유가 이것이다 — 이 잡은 릴리스하지 않는다. +PVC 매니페스트와 그 파일을 검사하던 `release.yml` 잡(`fileserver-pvc-certification`)은 2026-11-07에 +지웠다(소유자 결정: Kubernetes·프록시 설정은 이 repo 밖). 클러스터 인증은 배포하는 쪽이 +`docs/fileserver/storage-certification.md` 절차로 하고, volume 조건은 `docs/fileserver/operations.md` +「운영 환경이 지켜야 할 조건」에 있다. ## 규칙 diff --git a/docs/fileserver/operations.md b/docs/fileserver/operations.md index 33fd2cfb..f3930451 100644 --- a/docs/fileserver/operations.md +++ b/docs/fileserver/operations.md @@ -83,13 +83,13 @@ The volume was remounted somewhere the probe can no longer prove a required capa application refuses traffic rather than serving from storage it cannot publish to atomically. ```bash -kubectl apply -f infra/fileserver/kubernetes/pvc-certification-job.yaml -kubectl logs job/fileserver-pvc-certification +# staging과 content가 같은 파일 저장소(같은 장치 번호)인지 pod 안에서 본다 +kubectl exec -- stat -c %d /var/lib/backend/files/staging /var/lib/backend/files/content ``` -Compare the printed tuple with the certified one in `docs/fileserver/storage-certification.md`. A -mismatch in CSI driver, StorageClass, access mode, or mount options is the cause; the certification -does not carry across it. +`docs/fileserver/storage-certification.md`의 인증 절차로 지금 volume의 묶음(CSI driver, StorageClass, +접근 모드, backend, mount 옵션)을 다시 적고, 인증한 묶음과 비교한다. 하나라도 다르면 그것이 원인이다. +인증은 그 차이를 넘어 옮겨지지 않는다. ## Nginx delegation failure @@ -97,9 +97,9 @@ does not carry across it. The internal location is misconfigured, so the proxy cannot resolve the redirect it was handed. +프록시 설정의 내부 location(기본 `/__files/`)이 아래 「운영 환경이 지켜야 할 조건」을 지키는지 본다. + ```bash -# The internal prefix must resolve to the content root and must be marked `internal`. -grep -A5 '__files' infra/fileserver/nginx/nginx.conf curl -s $ADMIN/internal/fileserver/capabilities | jq '.capabilities.delegatedDownload' ``` @@ -110,6 +110,32 @@ slower but correct. app.fileserver-platform.nginx.enabled=false ``` +## 운영 환경이 지켜야 할 조건 + +이 repo는 프록시 설정 파일과 Kubernetes 매니페스트를 두지 않는다(2026-11-07 소유자 결정). 그 파일은 서비스를 +배포하는 쪽의 인프라 repo가 갖는다. 그 파일이 지켜야 할 조건은 아래다. + +**프런트 프록시(nginx `X-Accel-Redirect` 위임)** — `app.fileserver-platform.nginx.enabled=true`일 때 + +1. 내부 location(`app.fileserver-platform.nginx.internal-prefix`, 기본 `/__files/`)은 `internal`이다. 클라이언트가 + 그 경로를 직접 부르면 404이고 content 폴더에 닿지 않는다. 애플리케이션이 준 내부 redirect로만 닿는다. +2. 그 location의 `alias`는 저장 루트의 content 폴더다(기본 `/var/lib/backend/files/content/`). 애플리케이션은 + 절대 경로를 내보내지 않고 내부 접두사 아래 상대 URI만 내보낸다. 경로가 실제 위치가 되는 곳은 이 `alias`뿐이다. +3. 앱으로 넘기는 요청에서 클라이언트가 보낸 `X-Accel-Redirect` 헤더를 지운다. 남기면 호출자가 임의의 내부 + 객체를 가리킬 수 있다. +4. 업로드는 스트리밍으로 넘긴다(`proxy_request_buffering off`, 본문 크기 제한은 애플리케이션이 정하므로 프록시는 + 막지 않는다). 프록시가 큰 본문을 디스크에 버퍼링하면 쓰기가 두 번 일어난다. +5. 내부 location 응답에 `X-Content-Type-Options: nosniff`를 붙이고, 앱이 정한 `Content-Disposition`· + `Cache-Control`·`ETag`를 그대로 넘긴다. 올라온 내용이 자기 형식을 스스로 정하게 두지 않는다. + +**Kubernetes 저장 volume** + +1. PersistentVolumeClaim을 저장 루트(`/var/lib/backend/files`)에 마운트하고, 접근 모드는 `ReadWriteOnce`다. + `ReadWriteMany`(여러 노드의 동시 쓰기)는 인증하지 않았다(`support-matrix.md`). +2. pod `securityContext.fsGroup`을 이미지의 앱 그룹으로 둔다. 그래야 앱 계정이 volume에 쓸 수 있다. +3. 그 volume이 `storage-certification.md`의 인증 항목(같은 파일 저장소, 원자적 rename, `O_EXCL` 생성)을 + 통과해야 한다. 기동 때 `FileserverStartupValidator`도 같은 probe를 다시 돌린다. + ## Cleanup backlog **Signal** — `fileserver.cleanup{result="deferred"}` rising, or reclaimed bytes flat while deletes diff --git a/docs/fileserver/storage-certification.md b/docs/fileserver/storage-certification.md index b6788738..885a7974 100644 --- a/docs/fileserver/storage-certification.md +++ b/docs/fileserver/storage-certification.md @@ -19,12 +19,15 @@ certification that does not name all five is not transferable. ## Running the certification -```bash -kubectl apply -f infra/fileserver/kubernetes/pvc-certification-job.yaml -kubectl logs job/fileserver-pvc-certification -``` +이 repo는 인증 job 매니페스트를 두지 않는다(2026-11-07 소유자 결정). 배포하는 쪽이 대상 volume을 저장 +루트(`/var/lib/backend/files`)에 마운트한 일회성 pod에서 아래를 차례로 확인한다. -The job writes a machine-readable result to the claim itself, carrying the full tuple: +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 { @@ -40,8 +43,7 @@ The job writes a machine-readable result to the claim itself, carrying the full } ``` -The job fails closed: a volume whose staging and content areas are on different stores is not -certified, because its publish would silently degrade to a copy. +2번이 실패하면 인증하지 않는다. staging과 content가 다른 저장소인 volume은 게시가 소리 없이 복사로 바뀐다. ## Network filesystems diff --git a/docs/fileserver/support-matrix.md b/docs/fileserver/support-matrix.md index d50f0db0..8e1c90ff 100644 --- a/docs/fileserver/support-matrix.md +++ b/docs/fileserver/support-matrix.md @@ -29,7 +29,6 @@ that does not exist, so a level can never outlive the test that justified it. | NFSv4 ambiguity handling | Beta | `fileserver-nfs-ambiguity` | | Large-file and slow-client performance | Beta | `fileserver-large-file-performance` | | Multi-instance writer lease | Beta | `fileserver-multi-instance-lease` | -| Kubernetes ReadWriteOnce PVC | Limited | `fileserver-pvc-certification` (manifest checks in CI; cluster run is operator-driven) | | Nginx `X-Accel-Redirect` delegation | Limited | `fileserver-http-contract` | | Telemetry sensitive-data suppression | Stable | `fileserver-sensitive-telemetry-scan` | | Documentation and support-claim coverage | Stable | `fileserver-documentation-gate` | @@ -46,10 +45,10 @@ leaf puts `DispatcherServlet` on the classpath, so Boot resolves SERVLET. These have no job, and therefore no claim: -- An automated Kubernetes cluster result. `fileserver-pvc-certification` validates the manifest on - every release and applies it only when a release cluster is configured; without one it warns and - records that nothing was certified. The cluster tuple is produced by an operator and read from - [storage-certification.md](storage-certification.md). +- Kubernetes PVC(ReadWriteOnce 포함). 이 repo는 클러스터 매니페스트와 그것을 검사하던 release job을 + 2026-11-07에 지웠다. volume이 지켜야 할 조건은 [operations.md](operations.md) 「운영 환경이 지켜야 할 + 조건」, 인증 절차는 [storage-certification.md](storage-certification.md)다. 클러스터 결과는 배포하는 쪽이 + 만든다. - Kubernetes ReadWriteMany PVC. Concurrent writers across nodes are not certified. - Windows NTFS as a production storage root. The filename policy strips the characters NTFS diff --git a/docs/jpa/repository-adaptation.md b/docs/jpa/repository-adaptation.md index 4e6973b0..38e6f1bb 100644 --- a/docs/jpa/repository-adaptation.md +++ b/docs/jpa/repository-adaptation.md @@ -100,7 +100,7 @@ Docker-dependent lanes fail closed rather than skipping, matching the existing | Hibernate ORM 7.4 is the Stable provider | Boot 4.0.0 resolves `org.hibernate.orm:hibernate-core:7.1.8.Final` | The *declared* Stable provider baseline of the design stays 7.4 in `HibernateProviderPolicy`; the runtime provider version is read from Hibernate itself and reported. The collection-fetch-pagination gate runs against whatever provider the BOM resolves, and `HibernateProviderPolicy.driftsFromDeclaredBaseline()` makes the difference visible instead of hiding it behind a green check. | | PostgreSQL 16·17·18 Stable matrix | This leaf's existing evidence image is `postgres:16-alpine` | `PostgreSqlVersion` declares exactly PG 16, 17, 18. The default lane runs the repository's existing 16 image; 17 and 18 are selected by `-Pjpa.matrix.versions=16,17,18`, and an unknown or empty selection is an error rather than a skip. | | `settings.gradle.kts` module registration | Fail-closed 19-leaf registry | No registry change: leaf identity, Gradle path, allowed dependencies, and runtime memberships are unchanged. | -| `infra/jpa/{postgres,roles,toxiproxy}` | Repository already owns `infra/` | Created at the same repository-relative paths. | +| `infra/jpa/{postgres,roles,toxiproxy}` | Repository already owns `infra/` | 2026-11-07에 지웠다(쓰는 곳이 없거나 운영 인프라 파일). 운영 DB 조건은 `docs/jpa/security.md`로 옮겼다. | | `docs/jpa/**`, `docs/adr/ADR-JPA-*`, `.github/workflows/jpa-*.yml` | Repository already owns `docs/` and `.github/workflows/` | Created at the same repository-relative paths. | | release blocking aggregate | `jpaReleaseQualification` (persistence-jpa `build.gradle`) over `config/jpa/release-registry.json`, run per PostgreSQL major by the `jpa-release-gate` job in `.github/workflows/release.yml` | The registry names the blocking lanes; Gradle defines how each lane runs; CI only schedules the matrix. | | | Per-task `git add` + `git commit` | `AGENTS.md`: commit policy is `human-only`; agents do not stage, commit, amend, or push | Implementation is delivered unstaged. This is the only plan step intentionally not executed, and it is recorded here. | diff --git a/docs/jpa/runbooks.md b/docs/jpa/runbooks.md index 2a9ad30d..6e954dc7 100644 --- a/docs/jpa/runbooks.md +++ b/docs/jpa/runbooks.md @@ -91,6 +91,6 @@ drop an index another instance was about to finish building. Startup refused because the runtime credential holds `CREATE`, or `search_path` contains an unapproved schema. -This is not a false positive to be worked around. Re-provision from -`infra/jpa/roles/runtime-roles.sql`; the application's credential having DDL is the condition that -makes every other schema guarantee unenforceable. +This is not a false positive to be worked around. `docs/jpa/security.md` 「역할과 권한 — 운영 DB가 +갖춰야 할 것」대로 권한을 다시 맞춘다. 애플리케이션 자격 증명이 DDL을 가지면 다른 schema 보장을 하나도 +지킬 수 없다. diff --git a/docs/jpa/security.md b/docs/jpa/security.md index 2d0813f4..dbf5fa92 100644 --- a/docs/jpa/security.md +++ b/docs/jpa/security.md @@ -14,7 +14,41 @@ The separation is what makes "Flyway owns schema change" enforceable rather than the application's own credential cannot execute DDL, then no code path, no library, and no injected statement can alter the schema at runtime, regardless of what the application intended. -`infra/jpa/roles/runtime-roles.sql` provisions them. +### 역할과 권한 — 운영 DB가 갖춰야 할 것 + +이 repo는 역할을 만드는 SQL 파일을 두지 않는다(2026-11-07 소유자 결정. 운영 DB 준비는 배포하는 쪽의 +일이다). 운영 DB는 아래 조건을 지켜야 한다. 기동 때 `PostgreSqlRuntimeRoleVerifier`가 그중 런타임 역할의 +`CREATE` 권한과 `search_path`를 다시 본다. + +1. 애플리케이션 schema(예: `app`)는 migration 역할이 소유한다. 런타임 역할이 소유하지 않는다. +2. `PUBLIC`에서 데이터베이스 권한 전체와 `public` schema의 `CREATE`를 거둔다. PostgreSQL 15 전에는 + `PUBLIC`이 `public` schema에 `CREATE`를 가져, 권한 없는 역할이 `search_path`로 진짜 객체를 가리는 + 객체를 만들 수 있었다. +3. 런타임 역할에는 `CONNECT`, 애플리케이션 schema의 `USAGE`, 그 schema 테이블의 + `SELECT`·`INSERT`·`UPDATE`·`DELETE`, sequence의 `USAGE`·`SELECT`만 준다. +4. migration 역할이 앞으로 만들 테이블·sequence에도 같은 권한이 가도록 `ALTER DEFAULT PRIVILEGES`를 + 건다. 빠뜨리면 새 테이블을 더한 첫 배포가 런타임 권한 오류로 실패한다. +5. 런타임 역할에서 schema와 데이터베이스의 `CREATE`를 명시적으로 거둔다. 기동 검사가 보는 두 권한이다. +6. 관리 역할(COPY·backfill·정비용)은 런타임 역할과 같은 행 권한을 갖되 schema를 소유하지 않는다. 요청 + 경로는 이 역할을 쓰지 않는다. +7. 런타임·관리 역할의 `search_path`를 `app, pg_catalog`처럼 고정한다. + +비밀번호는 배포 환경의 비밀 저장소에서 넣는다. repo에 두지 않는다. + +### 서버 설정 — 플랫폼의 보장이 기대는 것 + +계약 테스트는 자기 컨테이너를 띄우므로(`PostgreSqlContainerFactory`) 이 설정이 필요 없다. 운영 DB에서 +플랫폼의 보장이 성립하려면 아래 설정이 있어야 한다. 값은 출발점이다. 가장 느린 정상 쿼리를 재 보고 정한다. + +| 설정 | 출발 값 | 왜 필요한가 | +| --- | --- | --- | +| `statement_timeout` | `30s` | 트랜잭션 안의 문장 하나가 요청보다 오래 사는 것을 막는 마지막 상한 | +| `idle_in_transaction_session_timeout` | `60s` | 열어 둔 채 쉬는 트랜잭션이 잠금과 snapshot을 붙잡아 쓰기와 vacuum을 막는 시간을 줄인다 | +| `lock_timeout` | `10s` | `PostgreSqlLockOptions`의 요청별 잠금 상한 아래에 까는 바닥 | +| `max_connections` | 배포 수에 맞춤 | 모든 인스턴스의 pool 합과, `REQUIRES_NEW`가 두 번째 연결을 잡는 경우를 함께 견딘다 | +| `default_transaction_isolation` | `read committed` | 바꾸면 격리 수준을 고르지 않은 모든 트랜잭션이 조용히 달라진다 | + +확장(extension)은 필요 없다. JSONB, 배열, 범위, `SKIP LOCKED`, `ON CONFLICT`는 모두 PostgreSQL 본체 기능이다. ## Startup verification diff --git a/docs/messaging/security.md b/docs/messaging/security.md index a8472055..16e8359b 100644 --- a/docs/messaging/security.md +++ b/docs/messaging/security.md @@ -21,6 +21,10 @@ runtime이 admin 자격 증명을 아예 보유하지 않으므로, 침해된 ha - broker authentication 활성 - topology auto-create 비활성 +broker 인증서는 `subjectAltName`에 접속 이름을 가져야 한다. hostname verification은 SAN을 보므로, SAN이 +없는 인증서는 실패하는 것이 맞다. 검사를 끄지 않는다. 키와 인증서는 배포 환경의 PKI가 발급해 실행 때 +마운트하고, repo에 두지 않는다. + Kafka는 추가로 `enable.idempotence=true`, `acks=all`, `max.in.flight.requests.per.connection <= 5`, consumer auto-commit 금지. diff --git a/docs/upgrade/2026-11-maturity-review.md b/docs/upgrade/2026-11-maturity-review.md index 79dd2d15..0c6a5b62 100644 --- a/docs/upgrade/2026-11-maturity-review.md +++ b/docs/upgrade/2026-11-maturity-review.md @@ -131,7 +131,8 @@ | # | 무엇이 바뀌었나 | 파생 서비스 증상 | 할 일 | 근거 | |---|---|---|---|---| -| B-49 | 샘플 모듈 삭제: `src/sample-portfolio`, `src/Dockerfile.sample`, registry `sample-portfolio` 행, 루트 `build.gradle`의 샘플 태스크·단계(`sampleWebContractCheck`, `:sample-portfolio:*` 의존, strict lane 단계 `:sample-portfolio:check`), `ci-quality-gates.yml`의 `sample-portfolio` job, `SampleRuntimeDefaultsContractTest`, spotbugs 제외의 샘플 클래스. 샘플에만 있던 검사(OpenAPI 스냅숏 `openapiCheckSnapshot`, Date 헤더, 가상 스레드 MDC 전파)도 함께 없어졌다 | 샘플을 고쳐 쓰던 서비스: 병합 때 "수정 대 삭제" 충돌. 샘플을 이미 지운 서비스: 충돌 없음 | 샘플을 이미 지웠으면 할 일 없음. 고쳐 쓰고 있으면 자기 leaf로 옮기고 registry 행·빌드 줄을 자기 것으로 둔다. 위 검사가 필요하면 자기 기능 leaf에 둔다 | 커밋 「샘플 모듈을 지운다」 | +| B-49 | 샘플 모듈 삭제: `src/sample-portfolio`, `src/Dockerfile.sample`, registry `sample-portfolio` 행, 루트 `build.gradle`의 샘플 태스크·단계(`sampleWebContractCheck`, `:sample-portfolio:*` 의존, strict lane 단계 `:sample-portfolio:check`), `ci-quality-gates.yml`의 `sample-portfolio` job, `SampleRuntimeDefaultsContractTest`, spotbugs 제외의 샘플 클래스. 샘플에만 있던 검사(OpenAPI 스냅숏 `openapiCheckSnapshot`, Date 헤더, 가상 스레드 MDC 전파)도 함께 없어졌다 | 샘플을 고쳐 쓰던 서비스: 병합 때 "수정 대 삭제" 충돌. 샘플을 이미 지운 서비스: 충돌 없음 | 샘플을 이미 지웠으면 할 일 없음. 고쳐 쓰고 있으면 자기 leaf로 옮기고 registry 행·빌드 줄을 자기 것으로 둔다. 위 검사가 필요하면 자기 기능 leaf에 둔다 | `ab5982e9` | +| B-50 | `infra/`에서 15개 삭제. 쓰는 곳이 없던 12개(`infra/httpclient/**`, `infra/jpa/postgres/README.md`, `infra/jpa/toxiproxy/`, `infra/messaging/{kafka,postgres,toxiproxy,tls}/`, `infra/notification/toxiproxy/`)와 운영 인프라 셋(`infra/fileserver/nginx/nginx.conf`, `infra/fileserver/kubernetes/pvc-certification-job.yaml`, `infra/jpa/roles/runtime-roles.sql`). `release.yml`의 `fileserver-pvc-certification` job도 지웠고, fileserver 지원 표에서 "Kubernetes ReadWriteOnce PVC — Limited" 주장을 「주장하지 않음」으로 옮겼다 | 그 파일을 배포에 쓰던 서비스: 병합이 파일을 지운다. 고쳐 쓰던 서비스: "수정 대 삭제" 충돌 | 그 파일은 자기 인프라 repo로 옮긴다. 지켜야 할 조건은 `docs/fileserver/operations.md` 「운영 환경이 지켜야 할 조건」, `docs/fileserver/storage-certification.md`, `docs/jpa/security.md` 「역할과 권한」·「서버 설정」에 있다 | 커밋 「쓰지 않는 파일과 운영 인프라 파일을 지운다」 | ## 4. DB 마이그레이션 diff --git a/docs/work/reference/decisions.md b/docs/work/reference/decisions.md index 1eb07b45..87ed1dd4 100644 --- a/docs/work/reference/decisions.md +++ b/docs/work/reference/decisions.md @@ -74,6 +74,7 @@ | 생성 명령 | JPA adapter를 만들지 않음(서비스 전용 persistence leaf가 기본), 생성된 쓰기 API는 역할 매핑 전 403 | 위임 | `1101` 15절(r2-10) | | `@SystemInvoked` | bean으로 등록돼 있으면 기동 실패, inbound adapter가 직접 부르지 못하게 ArchUnit | 위임 | `1103` 4절(RR-01-02) | | 시스템 호출 경로 | 사용자가 닿는 전송(web·GraphQL·gRPC·WebSocket)만 `@SystemInvoked`에 닿지 못한다. 메시지 소비자·스케줄러는 `@SystemCaller(reason)` 표시로 허용 | 위임 | `1103` 9.1절(RR-01-12), 10절 r5-b | +| 인프라 실행 파일 | nginx 설정, Kubernetes PVC job, DB 역할 SQL은 이 repo에서 지우고, 기능이 운영 환경에 요구하는 조건만 그 기능 문서에 적는다. 아무도 쓰지 않는 `infra/` 파일도 지운다 | 소유자(2026-11-07) | design-docs `repo-structure/README.md` 3.1절, `repo-structure/01-backend-layout.md` 6.3절 | | 샘플 모듈 | `src/sample-portfolio`와 `src/Dockerfile.sample`을 폴더째 지운다. 역할은 옮기지 않는다. 샘플 안에만 있던 템플릿 검사(OpenAPI 스냅숏, Date 헤더, 가상 스레드 MDC)도 함께 지운다. 예시는 매뉴얼과 생성 명령 출력이 맡는다 | 소유자(2026-11-07) | design-docs `repo-structure/README.md` 3.1절, `repo-structure/01-backend-layout.md` 6.2절 | ### 2.3 계약·오류 diff --git a/infra/fileserver/compose/docker-compose.fileserver.yml b/infra/fileserver/compose/docker-compose.fileserver.yml index 726c3288..6018ad74 100644 --- a/infra/fileserver/compose/docker-compose.fileserver.yml +++ b/infra/fileserver/compose/docker-compose.fileserver.yml @@ -14,8 +14,8 @@ # # The volume is a named volume, not a tmpfs and not the read-only root: published content must # outlive the container that wrote it. Back it with real storage in any deployment that keeps files. -# Kubernetes does the same job with a PersistentVolumeClaim and the pod's fsGroup -# (infra/fileserver/kubernetes/pvc-certification-job.yaml). +# Kubernetes does the same job with a PersistentVolumeClaim and the pod's fsGroup; the conditions +# are in docs/fileserver/operations.md. # # Ownership. The application runs as the image's non-root `app` account (src/Dockerfile). Docker # seeds a fresh named volume's owner from the image directory at the mount point, and the image has diff --git a/infra/fileserver/kubernetes/pvc-certification-job.yaml b/infra/fileserver/kubernetes/pvc-certification-job.yaml deleted file mode 100644 index 09a9ba38..00000000 --- a/infra/fileserver/kubernetes/pvc-certification-job.yaml +++ /dev/null @@ -1,127 +0,0 @@ -# Storage certification job. -# -# A PersistentVolumeClaim is not a filesystem contract. Whether an atomic rename, a same-file-store -# guarantee, or symlink refusal actually holds depends on the CSI driver, the StorageClass, the -# access mode, the backend, and the mount options — so this job records all five alongside the probe -# result. A certification without that tuple is not transferable to another cluster. -# -# The job writes a machine-readable result to the claim itself so the evidence lives with the volume -# it describes. -# -# kubectl apply -f infra/fileserver/kubernetes/pvc-certification-job.yaml -# kubectl logs job/fileserver-pvc-certification ---- -apiVersion: v1 -kind: PersistentVolumeClaim -metadata: - name: fileserver-certification - labels: - app.kubernetes.io/name: fileserver - app.kubernetes.io/component: certification -spec: - accessModes: - - ReadWriteOnce - resources: - requests: - storage: 1Gi - # Left unset on purpose: the certification is only meaningful for the class it actually ran on, - # so the operator names it explicitly rather than inheriting a cluster default. - storageClassName: "" ---- -apiVersion: batch/v1 -kind: Job -metadata: - name: fileserver-pvc-certification - labels: - app.kubernetes.io/name: fileserver - app.kubernetes.io/component: certification -spec: - backoffLimit: 0 - template: - metadata: - labels: - app.kubernetes.io/name: fileserver - app.kubernetes.io/component: certification - spec: - restartPolicy: Never - securityContext: - runAsNonRoot: true - runAsUser: 10001 - fsGroup: 10001 - containers: - - name: certify - image: eclipse-temurin:21-jdk - env: - - name: FILESERVER_STORAGE_ROOT - value: /var/lib/backend/files - - name: KUBERNETES_VERSION - valueFrom: - fieldRef: - fieldPath: metadata.annotations['certification.fileserver/kubernetes-version'] - - name: CSI_DRIVER - valueFrom: - fieldRef: - fieldPath: metadata.annotations['certification.fileserver/csi-driver'] - - name: STORAGE_CLASS - valueFrom: - fieldRef: - fieldPath: metadata.annotations['certification.fileserver/storage-class'] - - name: ACCESS_MODE - value: ReadWriteOnce - command: - - /bin/bash - - -c - - | - set -euo pipefail - ROOT="${FILESERVER_STORAGE_ROOT}" - mkdir -p "${ROOT}/staging" "${ROOT}/content" - - # Atomic rename within one file store is the property the publish path depends on. - echo probe > "${ROOT}/staging/probe" - if mv "${ROOT}/staging/probe" "${ROOT}/content/probe" 2>/dev/null; then - ATOMIC_MOVE=true - else - ATOMIC_MOVE=false - fi - - # Same device means a rename is a metadata operation rather than a copy. - STAGING_DEV=$(stat -c %d "${ROOT}/staging") - CONTENT_DEV=$(stat -c %d "${ROOT}/content") - [ "${STAGING_DEV}" = "${CONTENT_DEV}" ] && SAME_STORE=true || SAME_STORE=false - - # O_EXCL create is what makes a publish create-only rather than an overwrite. - if (set -o noclobber; echo x > "${ROOT}/content/excl") 2>/dev/null; then - ATOMIC_CREATE=true - else - ATOMIC_CREATE=false - fi - - cat > "${ROOT}/certification-result.json" </dev/null 2>&1"] - interval: 5s - timeout: 10s - retries: 20 diff --git a/infra/messaging/postgres/docker-compose.yml b/infra/messaging/postgres/docker-compose.yml deleted file mode 100644 index 05bc5435..00000000 --- a/infra/messaging/postgres/docker-compose.yml +++ /dev/null @@ -1,27 +0,0 @@ -# PostgreSQL 16 for the Outbox and Inbox. -# -# logical replication stays enabled so a CDC relay can be tried against the same database the polling -# relay uses. The repository ships no CDC relay (the Debezium mapping was removed on 2026-09-25). -services: - postgres: - image: postgres:16-alpine - container_name: messaging-postgres - ports: - - "5432:5432" - environment: - POSTGRES_DB: messaging - POSTGRES_USER: messaging - POSTGRES_PASSWORD: messaging - command: - - "postgres" - - "-c" - - "wal_level=logical" - - "-c" - - "max_replication_slots=4" - - "-c" - - "max_wal_senders=4" - healthcheck: - test: ["CMD-SHELL", "pg_isready -U messaging -d messaging"] - interval: 5s - timeout: 5s - retries: 20 diff --git a/infra/messaging/tls/README.md b/infra/messaging/tls/README.md deleted file mode 100644 index e57113c6..00000000 --- a/infra/messaging/tls/README.md +++ /dev/null @@ -1,35 +0,0 @@ -# TLS material - -Production profiles require TLS **and** hostname verification; `MessageSecurityValidator` fails -startup without either. - -No key material is committed here, and none should be. Certificates are issued by the deployment's -own PKI and mounted at runtime; a keystore in a repository is a credential in a repository, and -rotating it means a commit. - -## Local development - -The compose files in the sibling directories run plaintext listeners deliberately. They exist to -reproduce the *messaging* semantics locally, not the transport security, and running them with -`production: false` in the destination profile is what keeps the validator honest — a profile marked -`production: true` against a plaintext broker must fail, and that is a test, not an inconvenience. - -## Generating a local CA for TLS testing - -```bash -openssl req -x509 -newkey rsa:4096 -sha256 -days 30 -nodes \ - -keyout ca.key -out ca.crt -subj "/CN=messaging-local-ca" - -openssl req -newkey rsa:4096 -nodes -keyout broker.key -out broker.csr \ - -subj "/CN=localhost" - -openssl x509 -req -in broker.csr -CA ca.crt -CAkey ca.key -CAcreateserial \ - -out broker.crt -days 30 -sha256 \ - -extfile <(printf "subjectAltName=DNS:localhost,IP:127.0.0.1") -``` - -The `subjectAltName` is not optional. Hostname verification is required in production profiles, and -a certificate without a SAN fails it — which is the correct outcome, not something to work around by -disabling the check. - -Generated files are ignored by `.gitignore` in this directory. diff --git a/infra/messaging/toxiproxy/docker-compose.yml b/infra/messaging/toxiproxy/docker-compose.yml deleted file mode 100644 index e271af36..00000000 --- a/infra/messaging/toxiproxy/docker-compose.yml +++ /dev/null @@ -1,18 +0,0 @@ -# Toxiproxy, for the failures that matter most. -# -# The platform's hardest guarantee is that a lost confirmation is reported as AMBIGUOUS rather than -# guessed. A healthy broker will not lose one on request, so the chaos suite puts a proxy in front of -# it and severs the connection after the record was accepted but before the acknowledgement arrives. -services: - toxiproxy: - image: ghcr.io/shopify/toxiproxy:2.12.0 - container_name: messaging-toxiproxy - ports: - - "8474:8474" # control API - - "19092:19092" # proxied Kafka - - "15433:15433" # proxied PostgreSQL - healthcheck: - test: ["CMD", "/toxiproxy-cli", "list"] - interval: 5s - timeout: 5s - retries: 20 diff --git a/infra/notification/toxiproxy/docker-compose.yml b/infra/notification/toxiproxy/docker-compose.yml deleted file mode 100644 index ac103cad..00000000 --- a/infra/notification/toxiproxy/docker-compose.yml +++ /dev/null @@ -1,94 +0,0 @@ -# Toxiproxy fault injection for the notification delivery platform. -# -# Scope, stated up front: this is the *nightly and release* fault suite, not the PR gate. The PR -# suite runs against a loopback socket harness in-process — deterministic, no Docker, no provider -# sandbox — because a gate that needs infrastructure is a gate people learn to skip. What lives -# here are the faults that harness cannot produce: real TCP behaviour under latency, bandwidth -# starvation, and connection resets at a point the JVM's own socket layer decides. -# -# Usage: -# docker compose -f infra/notification/toxiproxy/docker-compose.yml up -d -# ./gradlew :adapter:outbound:notification:test -Dnotification.faultProxy=http://127.0.0.1:8474 -# -# The proxies below front *stub* upstreams, never a provider's real API. Pointing a toxic proxy at -# a live provider sends real notifications to real people from a test run, and adds a rate-limit -# incident on an account the team shares. -services: - toxiproxy: - image: ghcr.io/shopify/toxiproxy:2.11.0 - container_name: notification-toxiproxy - ports: - - "8474:8474" # control API - - "18081:18081" # -> ses-stub - - "18082:18082" # -> twilio-stub - - "18083:18083" # -> push-stub (APNs / FCM / Web Push) - networks: [notification-fault] - healthcheck: - test: ["CMD", "/toxiproxy-cli", "list"] - interval: 5s - timeout: 3s - retries: 10 - - # Deterministic upstreams. Each returns the provider's success shape and nothing else; the - # interesting behaviour is injected by the proxy in front of it, not by the stub. - ses-stub: - image: mendhak/http-https-echo:35 - environment: - HTTP_PORT: "8080" - networks: [notification-fault] - - twilio-stub: - image: mendhak/http-https-echo:35 - environment: - HTTP_PORT: "8080" - networks: [notification-fault] - - push-stub: - image: mendhak/http-https-echo:35 - environment: - HTTP_PORT: "8080" - networks: [notification-fault] - - # Creates the proxies and the toxics once the control API is up. Kept as a job rather than a - # README step so the topology is reproducible and reviewable rather than typed from memory. - provision: - image: ghcr.io/shopify/toxiproxy:2.11.0 - depends_on: - toxiproxy: - condition: service_healthy - networks: [notification-fault] - entrypoint: - - /bin/sh - - -c - - | - set -e - CLI="/toxiproxy-cli -h toxiproxy:8474" - $$CLI create -l 0.0.0.0:18081 -u ses-stub:8080 ses - $$CLI create -l 0.0.0.0:18082 -u twilio-stub:8080 twilio - $$CLI create -l 0.0.0.0:18083 -u push-stub:8080 push - - # Response loss after the request was committed: the provider received and acted on the - # message, and the answer never came back. This is the AMBIGUOUS case, and it is the one - # fault no provider's documentation describes. - $$CLI toxic add -t timeout -a timeout=0 -n response_loss --downstream --toxicity 0 ses - $$CLI toxic add -t timeout -a timeout=0 -n response_loss --downstream --toxicity 0 twilio - $$CLI toxic add -t timeout -a timeout=0 -n response_loss --downstream --toxicity 0 push - - # Latency past the adapter's own timeout, to prove the timeout is the adapter's decision - # rather than the socket's. - $$CLI toxic add -t latency -a latency=8000 -n slow --toxicity 0 ses - $$CLI toxic add -t latency -a latency=8000 -n slow --toxicity 0 twilio - $$CLI toxic add -t latency -a latency=8000 -n slow --toxicity 0 push - - # Partial write: the connection dies mid-body. Distinct from response loss, because the - # provider never got a complete request and the attempt is genuinely retryable. - $$CLI toxic add -t limit_data -a bytes=64 -n partial_write --upstream --toxicity 0 ses - $$CLI toxic add -t limit_data -a bytes=64 -n partial_write --upstream --toxicity 0 twilio - $$CLI toxic add -t limit_data -a bytes=64 -n partial_write --upstream --toxicity 0 push - - echo "proxies ready; toxics are registered at toxicity=0 and enabled per test" - $$CLI list - -networks: - notification-fault: - driver: bridge diff --git a/src/composition/fileserver-platform/README.md b/src/composition/fileserver-platform/README.md index 3f4304e6..68f771be 100644 --- a/src/composition/fileserver-platform/README.md +++ b/src/composition/fileserver-platform/README.md @@ -59,7 +59,7 @@ volume을 붙인다. | 실행 환경 | 붙이는 방법 | | --- | --- | | Compose | `-f infra/fileserver/compose/docker-compose.fileserver.yml`을 더한다. `fileserver-data` named volume을 마운트하고, 앱보다 먼저 `fileserver-storage-init`이 앱 이미지 안에서 root로 한 번 돌아 volume 소유자를 이미지의 `app` 계정으로 바꾼다(0750). 새 volume, 재사용한 volume, bind mount 모두 같다 | -| Kubernetes | PersistentVolumeClaim을 같은 경로에 마운트하고 pod `securityContext.fsGroup`을 앱 그룹으로 둔다(`infra/fileserver/kubernetes/pvc-certification-job.yaml`) | +| Kubernetes | PersistentVolumeClaim을 같은 경로에 마운트하고 pod `securityContext.fsGroup`을 앱 그룹으로 둔다(조건: `docs/fileserver/operations.md` 「운영 환경이 지켜야 할 조건」) | | `docker run` | `-v :/var/lib/backend/files`. volume 소유자를 이미지의 `app` 계정으로 먼저 맞춘다 | 소유자가 맞지 않으면 모든 쓰기가 거부되고, 저장소 probe가 기동 때 `storage root is not writable`로