---
title: "블록 스토리지 CSI 예제"
slug: "k8s-k8sexamples-bscsi"
updated: 2026-08-20T09:03:27Z
published: 2026-08-20T09:03:27Z
canonical: "guide-gov.ncloud-docs.com/k8s-k8sexamples-bscsi"
---

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

# 블록 스토리지 CSI 예제

VPC 환경에서 이용 가능합니다.

[블록 스토리지 CSI](/docs/k8s-k8suse-bscsi)에서 설명한 CSI 사용법을 바탕으로 다양한 방식을 통해 볼륨을 할당하는 예제입니다.

## Pod에 복수의 볼륨을 할당

두 개의 신규 블록 스토리지를 생성하여 Pod에 마운트하고, 생성 요청할 볼륨에 대해 각각 `PersistentVolumeClaim`을 요청하는 예제는 다음과 같습니다.

```
apiVersion: v1
kind: PersistentVolumeClaim
metadata:
  name: csi-pod-1
spec:
  accessModes:
  - ReadWriteOnce
  resources:
    requests:
      storage: 10Gi
  storageClassName: nks-block-storage
---
apiVersion: v1
kind: PersistentVolumeClaim
metadata:
  name: csi-pod-2
spec:
  accessModes:
  - ReadWriteOnce
  resources:
    requests:
      storage: 10Gi
  storageClassName: nks-block-storage
---
kind: Pod
apiVersion: v1
metadata:
  name: my-csi-app
spec:
  containers:
    - name: my-csi-app
      image: busybox
      volumeMounts:
      - mountPath: "/data/pod-1/"
        name: my-volume-1
      - mountPath: "/data/pod-2/"
        name: my-volume-2
      command: [ "sleep", "1000000" ]
  volumes:
    - name: my-volume-1
      persistentVolumeClaim:
        claimName: csi-pod-1
    - name: my-volume-2
      persistentVolumeClaim:
        claimName: csi-pod-2
```

---

## Deployment에서 PersistentVolume 이용

`PersistentVolumeClaim`을 생성하여 신규 볼륨 생성을 요청할 때, Deployment의 `template`에서 `claimName`을 명시함으로써 생성된 볼륨을 마운트하는 예제는 다음과 같습니다.

```
apiVersion: v1
kind: PersistentVolumeClaim
metadata:
  name: csi-deployment-pvc
spec:
  accessModes:
  - ReadWriteOnce
  resources:
    requests:
      storage: 10Gi
  storageClassName: nks-block-storage
---
apiVersion: apps/v1
kind: Deployment
metadata:
  name: my-csi-app
spec:
  selector:
    matchLabels:
      app: my-csi-app
  replicas: 1
  template:
    metadata:
      labels:
        app: my-csi-app
    spec:
      containers:
        - name: my-frontend
          image: busybox
          volumeMounts:
          - mountPath: "/data"
            name: my-volume
          command: [ "sleep", "1000000" ]
      volumes:
        - name: my-volume
          persistentVolumeClaim:
            claimName: csi-deployment-pvc
```

## StatefulSet에서 PersistentVolume 이용하기

`StatefulSet`에서 `volumeClaimTemplates`를 정의하여 각 replica마다 새로운 `PersistentVolumeClaim`을 자동으로 생성하는 예제는 다음과 같습니다.

```
apiVersion: apps/v1
kind: StatefulSet
metadata:
  name: my-csi-app
spec:
  serviceName: my-csi-app
  selector:
    matchLabels:
      app: my-csi-app
  replicas: 1
  template:
    metadata:
      labels:
        app: my-csi-app
    spec:
      containers:
        - name: my-frontend
          image: busybox
          volumeMounts:
          - mountPath: "/data"
            name: my-volume
          command: [ "sleep", "1000000" ]
  volumeClaimTemplates:
    - metadata:
        name: my-volume
      spec:
        accessModes: ["ReadWriteOnce"]
        resources:
          requests:
            storage: 10Gi
```

## 특정 Zone에 볼륨 할당

주의

allowedTopologies는 Kubernetes 버전 1.33 이상부터 사용 가능합니다.

StorageClass의 `allowedTopologies` 설정을 통해 Multi-Zone 클러스터 환경에서 볼륨이 생성될 Zone을 제한할 수 있습니다. 아래 예시로 사용된 yaml 코드를 통해 허용할 Zone을 지정하여 블록 스토리지 볼륨을 생성할 수 있습니다.

```
kind: StorageClass
apiVersion: storage.k8s.io/v1
metadata:
  name: nks-block-storage-zone
provisioner: blk.csi.ncloud.com
volumeBindingMode: WaitForFirstConsumer
reclaimPolicy: Delete
allowVolumeExpansion: true
parameters:
  type: CB1
allowedTopologies:
  - matchLabelExpressions:
    - key: topology.kubernetes.io/zone
      values:
        - "2"
        - "3"
---
apiVersion: v1
kind: PersistentVolumeClaim
metadata:
  name: block-csi-pvc
spec:
  accessModes:
    - ReadWriteOnce
  resources:
    requests:
      storage: 20Gi
  storageClassName: nks-block-storage-zone
---
kind: Pod
apiVersion: v1
metadata:
  name: my-csi-app
spec:
  containers:
    - name: my-frontend
      image: busybox
      volumeMounts:
        - mountPath: "/data"
          name: my-volume
      command: [ "sleep", "1000000" ]
  volumes:
    - name: my-volume
      persistentVolumeClaim:
        claimName: block-csi-pvc
```

| 필드 | 설명 |
| --- | --- |
| allowedTopologies.matchLabelExpressions.key | `topology.kubernetes.io/zone` 입력 |
| allowedTopologies.matchLabelExpressions.values | 볼륨 생성을 허용할 Zone 번호 입력. 복수의 Zone 지정 가능 |

클러스터에서 사용 가능한 Zone 번호를 확인하려면 다음 명령어를 실행해 주십시오.

```
kubectl get nodes -L topology.kubernetes.io/zone
```

참고

`volumeBindingMode`가 `WaitForFirstConsumer`인 경우, Pod가 스케줄링된 노드의 Zone이 `allowedTopologies`에 포함되어 있어야 합니다. 해당 Zone에 노드가 존재하지 않으면 Pod가 Pending 상태로 대기할 수 있습니다.

## xfs 파일시스템 타입으로 PersistentVolume 이용

주의

xfs 파일시스템은 Kubernetes 버전 1.33 이상부터 사용 가능합니다.

네이버 클라우드 플랫폼에서는 NAVIX 환경에서 xfs 파일시스템을 사용하도록 권장하고 있습니다. 아래 예시의 StorageClass를 통해 xfs 타입 파일시스템으로 볼륨을 생성할 수 있습니다.

```
kind: StorageClass
apiVersion: storage.k8s.io/v1
metadata:
  name: nks-block-storage-xfs
provisioner: blk.csi.ncloud.com
volumeBindingMode: WaitForFirstConsumer
reclaimPolicy: Delete
allowVolumeExpansion: true
parameters:
  type: CB1
  csi.storage.k8s.io/fstype: xfs
mountOptions:
- nouuid
---
apiVersion: v1
kind: PersistentVolumeClaim
metadata:
  name: block-csi-pvc
spec:
  accessModes:
    - ReadWriteOnce
  resources:
    requests:
      storage: 20Gi
  storageClassName: nks-block-storage-xfs
---
kind: Pod
apiVersion: v1
metadata:
  name: my-csi-app
spec:
  containers:
    - name: my-frontend
      image: busybox
      volumeMounts:
        - mountPath: "/data"
          name: my-volume
      command: [ "sleep", "1000000" ]
  volumes:
    - name: my-volume
      persistentVolumeClaim:
        claimName: block-csi-pvc
```

| 필드 | 설명 |
| --- | --- |
| parameters.csi.storage.k8s.io/fstype | xfs 입력 |
| mountOptions | 마운트 옵션 지정. xfs 파일시스템의 경우 `nouuid` 옵션을 통해 uuid 중복 문제를 예방함 |