From 3549f382955c88539cbdf8d224b3fa89159bd4d9 Mon Sep 17 00:00:00 2001
From: kappa <kappa@inouter.com>
Date: Sun, 5 Apr 2026 09:45:38 +0900
Subject: [PATCH] Add NFS StorageClass docs, update backup with soft mount
 notes

---
 infra/backup.md      |   4 +-
 infra/nfs-storage.md | 102 +++++++++++++++++++++++++++++++++++++++++++
 2 files changed, 105 insertions(+), 1 deletion(-)
 create mode 100644 infra/nfs-storage.md

diff --git a/infra/backup.md b/infra/backup.md
index 431b17d..b833801 100644
--- a/infra/backup.md
+++ b/infra/backup.md
@@ -1,6 +1,6 @@
 ---
 title: 백업 파이프라인
-updated: 2026-03-25
+updated: 2026-04-05
 tags: [infra, backup]
 ---
 
@@ -45,6 +45,8 @@ tags: [infra, backup]
 - Synology sudo PATH 문제: `/etc/sudoers.d/path`에 `secure_path` 추가 (2026-03-17)
 - NAS `/volume1/incus/inbest/` 소유자: `kaffa:users` (rsync 쓰기용)
 - btrfs subvolume: `/volume1/incus` (ID 741)
+- 모든 백업 스크립트에 NAS 접근 불가 시 스킵/로컬 보관 로직 추가 (2026-04-05)
+- NFS 마운트는 반드시 `soft,timeo=50,retrans=3` 사용 (hard 금지, [[nfs-storage]] 참조)
 
 ### 복구 시나리오
 
diff --git a/infra/nfs-storage.md b/infra/nfs-storage.md
new file mode 100644
index 0000000..1884bca
--- /dev/null
+++ b/infra/nfs-storage.md
@@ -0,0 +1,102 @@
+---
+title: NFS StorageClass (NAS)
+updated: 2026-04-05
+tags: [infra, k3s, storage, nfs, synology]
+---
+
+## 개요
+
+Synology NAS를 K3s NFS StorageClass로 사용. Longhorn(블록)과 병행하여 파일 저장소, 웹소스 등 대용량/RWX 워크로드에 사용.
+
+## NAS 정보
+
+| 항목 | 값 |
+|------|-----|
+| 장비 | Synology NAS |
+| IP (kr1/kr2) | 192.168.205.100 |
+| IP (hp2) | 192.168.9.100 (현재 미연결, 해결 예정) |
+| 디스크 | 11TB (사용 2%) |
+| NFS export | `/volume1/k3s-nfs` |
+| NFS 옵션 | `rw,async,no_wdelay,crossmnt,no_root_squash,insecure_locks,sec=sys,anonuid=1025,anongid=100` |
+
+## K3s 설정
+
+| 항목 | 값 |
+|------|-----|
+| StorageClass | `nfs` (default 아님, 명시 지정 필요) |
+| Provisioner | nfs-subdir-external-provisioner (Helm) |
+| Namespace | `nfs-provisioner` |
+| NFS 경로 | `/volume1/k3s-nfs` |
+| 마운트 옵션 | `soft,timeo=50,retrans=3` |
+| archiveOnDelete | true (PVC 삭제 시 데이터 archived- 접두사로 보존) |
+| nodeAffinity | incus-kr1, incus-kr2만 (hp2 NAS 연결 해결 전까지) |
+
+### Helm 설치 명령
+
+```bash
+export KUBECONFIG=/etc/rancher/k3s/k3s.yaml
+helm repo add nfs-subdir-external-provisioner https://kubernetes-sigs.github.io/nfs-subdir-external-provisioner
+helm install nfs-provisioner nfs-subdir-external-provisioner/nfs-subdir-external-provisioner \
+  --namespace nfs-provisioner --create-namespace \
+  --set nfs.server=192.168.205.100 \
+  --set nfs.path=/volume1/k3s-nfs \
+  --set storageClass.name=nfs \
+  --set storageClass.defaultClass=false \
+  --set storageClass.reclaimPolicy=Delete \
+  --set storageClass.archiveOnDelete=true \
+  --set nfs.mountOptions[0]=soft \
+  --set nfs.mountOptions[1]=timeo=50 \
+  --set nfs.mountOptions[2]=retrans=3
+```
+
+### PVC 사용 예시
+
+```yaml
+apiVersion: v1
+kind: PersistentVolumeClaim
+metadata:
+  name: my-data
+spec:
+  storageClassName: nfs
+  accessModes: [ReadWriteMany]
+  resources:
+    requests:
+      storage: 10Gi
+```
+
+## 성능 (fio 벤치마크, 2026-04-05)
+
+| 테스트 | IOPS | 대역폭 | 레이턴시 |
+|--------|------|--------|---------|
+| Random Read 4K | 20.6K | 84 MB/s | 1.5 ms |
+| Random Write 4K | 18.1K | 74 MB/s | 1.8 ms |
+| Seq Read 1M | 263 | 276 MB/s | 30 ms |
+| Seq Write 1M | 275 | 288 MB/s | 29 ms |
+
+## 용도별 StorageClass 선택
+
+| 용도 | StorageClass | 이유 |
+|------|-------------|------|
+| DB (PostgreSQL, etcd, Redis) | longhorn | 저레이턴시 블록 필요 |
+| 파일 업로드, 사용자 데이터 | nfs | 대용량, RWX 지원 |
+| 웹소스, 정적 파일 | nfs | 대용량, 여러 Pod 공유 |
+| 로그, 임시 데이터 | longhorn/local-path | 빠른 쓰기 |
+
+## 파일 소유권
+
+- `no_root_squash` 설정으로 root 컨테이너는 소유권 문제 없음
+- 비-root 컨테이너는 Pod `securityContext.fsGroup`으로 제어
+
+## NFS hard vs soft 교훈 (2026-04-04)
+
+kr2에서 NAS NFS가 `hard` 마운트 + NAS 연결 끊김으로 load 1959까지 폭주한 사건 발생. D-state 프로세스(mountpoint, NFS manager)가 커널 전체를 잠식.
+
+- **hard**: NAS 끊기면 무한 대기 → 서버 먹통
+- **soft**: 타임아웃 후 에러 반환 → 서버 생존
+
+모든 NFS 마운트는 `soft,timeo=50,retrans=3` 필수.
+
+## 관련 문서
+
+- [[backup]] — 백업 파이프라인 (NAS 활용)
+- [[infra-hosts]] — 서버 목록