---
title: NAS StorageClass (NFS + iSCSI)
updated: 2026-04-05
tags: [infra, k3s, storage, nfs, iscsi, 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` 필수.

## iSCSI StorageClass (democratic-csi)

Synology NAS의 iSCSI를 K3s 블록 스토리지로 사용. democratic-csi가 PVC 생성/삭제 시 자동으로 iSCSI Target + LUN을 관리.

| 항목 | 값 |
|------|-----|
| StorageClass | `synology-iscsi` |
| CSI Driver | democratic-csi (Helm) |
| Namespace | `democratic-csi` |
| iSCSI Portal | 192.168.205.100:3260 |
| Base IQN | `iqn.2000-01.com.synology:NAS.k3s.` |
| LUN 타입 | BLUN (Btrfs thin provisioning) |
| Volume | /volume1 |
| 인증 | kaffa 계정 (HTTPS API) |
| 자동 관리 | PVC 생성 → Target+LUN 생성, PVC 삭제 → Target+LUN 삭제 |

### Helm 설치

values 파일: `/tmp/democratic-csi-values.yaml` (kr1)

```bash
export KUBECONFIG=/etc/rancher/k3s/k3s.yaml
helm repo add democratic-csi https://democratic-csi.github.io/charts/
helm install synology-iscsi democratic-csi/democratic-csi \
  --namespace democratic-csi --create-namespace \
  -f /tmp/democratic-csi-values.yaml
```

### 전체 StorageClass 요약

| StorageClass | 방식 | 용도 | HA |
|---|---|---|---|
| longhorn | 로컬 NVMe 블록 | DB, 고성능 블록 | 노드 간 레플리카 |
| synology-iscsi | NAS iSCSI 블록 | 블록 스토리지 (NAS) | RAID5 |
| nfs | NAS NFS 파일 | 파일, 웹소스, RWX | RAID5 |
| local-path | 로컬 디스크 | 캐시, 임시 | 없음 |

## 관련 문서

- [[backup]] — 백업 파이프라인 (NAS 활용)
- [[storage-plan]] — NVMe NAS + 2.5G iSCSI 기획
- [[infra-hosts]] — 서버 목록