---
title: "NAS 볼륨 CSI"
slug: "k8s-k8suse-nascsi"
tags: ["kubernetes", "NAS", "Ncloud Kubernetes Service"]
updated: 2026-07-23T09:02:32Z
published: 2026-07-23T09:02:32Z
canonical: "guide-fin.ncloud-docs.com/k8s-k8suse-nascsi"
---

> ## Documentation Index
> Fetch the complete documentation index at: https://guide-fin.ncloud-docs.com/llms.txt
> Use this file to discover all available pages before exploring further.

# NAS 볼륨 CSI

구동 중인 컨테이너에 파일을 새로 추가할 경우 해당 파일들은 프로세스가 종료되거나 Kubernetes Liveness Probe의 상태 체크에 실패하여 컨테이너가 재시작될 때 모두 삭제됩니다. 이 때 NAS 볼륨을 사용하여 새로 추가된 파일들이 프로세스 종료 또는 컨테이너 재시작 후에도 유지되도록 설정할 수 있습니다.

Kubernetes NAS 볼륨 컨테이너를 배포할 때 PersistentVolumeClaim(PVC)를 생성하여 추가할 수 있습니다.

네이버 클라우드 플랫폼의 Ncloud Kubernetes Service는 볼륨 드라이버로 Container Storage Interface(CSI)를 제공합니다. 이 드라이버는 Kubernetes와 연동되어 NAS 볼륨 생성, 삭제, 리사이징 등의 작업을 지원합니다.

## 지원되는 버전 및 용량<a name="지원되는버전및용량"></a>

### 지원되는 버전<a name="지원되는버전"></a>
네이버 클라우드 플랫폼에서 제공하는 NAS CSI 버전과 호환 Kubernetes 버전은 다음과 같습니다.

| Ncloud NAS CSI Driver\Kubernetes Version | 1.18   | 1.19   | 1.20   | 1.21   | 1.22 | 1.23+ |
| ---------------------------------------- | ------ | ------ | ------ | ------ | ---- | ---- |
| v1.0.x | 지원 | 지원 | 지원 | 지원 | 지원 | 지원 |
| v2.0.x | 미지원 | 미지원 | 미지원 | 미지원 | 지원 | 지원 |
| v2.1.x  | 미지원 | 미지원 | 미지원 | 미지원 | 지원 | 지원 |
| v2.2.x | 미지원  | 미지원 | 미지원 | 미지원 | 지원 | 지원 |

Kubernetes 버전에서 지원하는 스토리지 서비스는 다음과 같습니다.

| Service\Kubernetes Version | 1.18+  | 1.22+ |
| -------------------------- | --- | --- | 
| 볼륨 생성 | 지원 | 지원 |
| 볼륨 삭제 | 지원 | 지원 |
| 볼륨 확장(리사이즈) | 지원 | 지원 |
| 서버에 볼륨 할당 | 지원 | 지원 |
| 서버에 볼륨 해제 | 지원 | 지원 |
| 스냅샷 생성 | 미지원 | 미지원 |
| 스냅샷 삭제 | 미지원 | 미지원 |
| 서브디렉터리 생성 | 미지원 | 지원 |

### 할당 가능한 용량<a name="할당가능한용량"></a>
Kubernetes NAS 볼륨은 CSI를 통해 100 GB 단위로 용량을 할당할 수 있습니다. 볼륨 크기를 별도로 정의하지 않는 경우 기본값인 500 GB로 NAS 볼륨이 생성됩니다. 할당 가능한 최소 용량과 최대 용량은 다음과 같습니다.

* 최소: 500 GB
* 최대: 10,000 GB

## NAS CSI 드라이버 설치 (기존 미설치 클러스터용)
NAS CSI 드라이버는 Kubernetes가 설치될 때 기본으로 배포됩니다. 이 절에서는 기존 미설치 클러스터에서 NAS CSI를 설치하는 방법을 설명합니다. NAS CSI가 이미 설치되어 있는 경우에는 아래의 작업을 수행하지 않아도 됩니다.

### NAS CSI Driver 배포
아래 파일들은 최신의 안정 버전을 가리킵니다. 설치 과정 중 문제가 생긴 경우 kubectl apply -f 명령을 다시 실행하여 누락된 리소스가 다시 반영되도록 합니다.
```bash
# kubernetes version >= 1.22
$ kubectl --kubeconfig=$KUBE_CONFIG apply -f https://kr.object.ncloudstorage.com/nks-download/nas-csi/fin/kr/v2.2.0/nas-csi.yaml

# kubernetes version < 1.22
$ kubectl --kubeconfig=$KUBE_CONFIG apply -f https://kr.object.ncloudstorage.com/nks-download/nas-csi/fin/kr/v1.0.2/nas-csi.yaml
```

## NAS CSI 드라이버 상세 사항<a name="CSI드라이버상세사항"></a>

### StorageClass<a name="StorageClass"></a>
StorageClass는 각 스토리지의 정책과 타입을 설정한 오브젝트입니다. 네이버 클라우드 플랫폼에서는 NAS 볼륨을 사용하는 StorageClass를 제공합니다.
NAS 볼륨의 StorageClass 오브젝트를 확인하려면 nks-nas-csi 이름을 가진 오브젝트를 확인해 주십시오. 아래와 같이 표시됩니다.
```yaml
apiVersion: storage.k8s.io/v1
kind: StorageClass
metadata:
  name: nks-nas-csi
mountOptions:
- hard
- nolock
- nfsvers=3
parameters:
  csi.storage.k8s.io/provisioner-secret-name: mount-options
  csi.storage.k8s.io/provisioner-secret-namespace: kube-system
provisioner: nas.csi.ncloud.com
reclaimPolicy: Delete
volumeBindingMode: WaitForFirstConsumer
allowVolumeExpansion: true
```
* `volumeBindingMode`: 볼륨 바인딩과 동적 프로비저닝이 동작하는 시점을 설정할 수 있습니다. 기본값은 `Immediate`입니다.

| 모드 | 설명 |
| --- | --- |
| `Immediate` | PVC가 생성되는 시점에 동작 |
| `WaitForFirstConsumer` | Pod가 생성되는 시점에 동작 |

* `reclaimPolicy`: 사용이 끝난 PVC가 삭제될 때 사용 중이던 `PersistentVolume`을 재확보 또는 삭제하도록 정책을 설정할 수 있습니다. 기본값은 `Delete`입니다.

| 정책 | 설명 |
| --- | --- |
| `Retain` | PVC가 삭제될 때 사용 중인 PV는 재사용이 가능한 상태로 변경되며, NAS 볼륨 내부 데이터를 유지 |
| `Delete` | PVC가 삭제될 때 사용 중인 PV를 함께 삭제하며, NAS 볼륨 반납 |
* `allowVolumeExpansion`: 값을 `true`로 설정하여 `PersistentVolumeClaim`을 확장할 수 있습니다.
:::(Info) (참고)
`Retain` 정책을 통해 재확보한 NAS 볼륨은 네이버 클라우드 플랫폼 콘솔이나 API를 통해 반납할 수 있습니다.
:::

* `parameters.subDir`: 하나의 NAS 볼륨 내에 서브디렉터리를 생성하여, 여러 PVC가 동일한 NAS 볼륨을 공유할 수 있도록 NFS 공유 경로 하위의 서브디렉터리 경로를 설정할 수 있습니다. 미지정 시 PV 이름으로 서브디렉터리가 생성됩니다. `[NAS CSI v2.2.0+]`

`parameters.subDir` 값에 다음 패턴을 사용하면 PVC/PV 메타데이터로 자동 치환됩니다.

| 패턴 | 치환되는 값 |
|---|---|
| `${pvc.metadata.name}` | PVC 이름 |
| `${pvc.metadata.namespace}` | PVC 네임스페이스 |
| `${pv.metadata.name}` | PV 이름 |

:::(warning) (주의)
`parameters.subDir` 값에 **#** 문자는 사용할 수 없습니다.
:::

* `parameters.deleteOnlySubdir`: PVC 삭제 시 서브디렉터리만 삭제할지 여부를 설정할 수 있습니다. 기본값은 **false**입니다. `[NAS CSI v2.2.0+]`

:::(Info) (참고)
`parameters.deleteOnlySubdir`은 reclaimPolicy가 **Delete** 인 경우에만 유효합니다.
NAS 볼륨과 서브디렉터리를 모두 유지하려면 StorageClass의 reclaimPolicy를 **Retain**으로 설정하세요.
:::

#### Default Storage Class 변경<a name="DefaultStorageClass변경"></a>
생성된 StorageClass 오브젝트의 기본 Storage Class 내용을 변경하려면 [Changing the default StorageClass](https://kubernetes.io/docs/tasks/administer-cluster/change-default-storage-class/#changing-the-default-storageclass){target="_blank"}를 참조해 주십시오.

### CSI Controller<a name="CSIController"></a>
CSI Controller는 볼륨의 생성, 삭제, 할당, 할당 해제, 스냅샷 등 각종 제어와 관리를 담당하는 인터페이스입니다.

NAS CSI Controller를 확인하려면 아래 명령어를 통해 네임스페이스 kube-system 내의 관련 파드를 확인해 주십시오.

```yaml
$ kubectl --kubeconfig $KUBE_CONFIG get pods -n kube-system -l app=nks-nas-csi-controller
```

### CSI Node<a name="CSINode"></a>
CSI 노드는 Kubernetes의 워커 노드마다 하나씩 동작하는 노드로, 볼륨의 포맷, 마운트, 언마운트 등의 동작을 담당합니다.

NAS CSI Node를 확인하려면 아래 명령어를 통해 네임스페이스 kube-system 내의 관련 파드를 확인해 주십시오.

```yaml
$ kubectl --kubeconfig $KUBE_CONFIG  get pods -n kube-system -l app=nks-nas-csi-node
```
## NAS-CSI 드라이버 사용<a name="NAS-CSI드라이버사용"></a>
NAS-CSI 드라이버 사용에 대한 자세한 예제는 [NAS 볼륨 CSI 예제](/docs/k8s-k8sexamples-nascsi)를 참조해 주십시오.