블록 스토리지 CSI 이용 가이드

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

시작하기 전에

모든 컨테이너들은 빌드 시점에 추가된 파일들을 가지고 구동됩니다. 이후에 컨테이너의 파일 시스템 내에 새로 추가된 파일들은 프로세스가 종료되거나 Kubernetes의 liveness Probe의 상태 체크가 실패하여 컨테이너가 재시작되는 경우 모두 제거됩니다.

컨테이너가 재시작되는 경우에도 앞서 언급한 추가된 파일들을 계속 유지시키길 원한다면, 배포 시 생성할 수 있는 PersistentVolumeClaim(PVC)을 통해 데이터 저장을 위해 생성할 수 있는 영구 저장소인 블록 스토리지를 이용할 수 있습니다.

네이버 클라우드 플랫폼의 Ncloud Kubernetes Service는 볼륨 드라이버로서 Container Storage Interface(CSI)를 제공합니다. 이 볼륨 드라이버는
Kubernetes와 연동되어, 블록 스토리지 생성과 삭제 및 attaching, detaching과 같은 작업들을 지원합니다.

제약 사항

지원 버전

네이버 클라우드 플랫폼의 Kubernetes Service는 블록 스토리지 볼륨 드라이버로 CSI를 제공합니다. CSI 드라이버와 Kubernetes 간의 연동을 위해서는 호환되는 버전을 확인해야 합니다.

현재 네이버 클라우드 플랫폼에서 제공하고 있는 CSI 버전과 호환 Kubernetes 버전은 다음과 같습니다.

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

할당 가능한 용량

CSI를 통해 할당할 수 있는 블록 스토리지의 크기는 다음과 같으며, 10GB 단위로 할당이 가능합니다.
10GB 미만의 볼륨 크기를 요청한 경우, 최소 크기인 10GB로 생성됩니다. 필요한 볼륨 크기를 정의하지 않은 경우 기본값 20GB로 요청됩니다.

• 최소: 10GB
• 최대: 2000GB

CSI 시작하기(기존 미설치 클러스터용)

이 절은 Container Storage Interface(CSI)를 Kubernetes 클러스터에 설치하는 방법을 다룹니다. CSI가 이미 설치되어 있는 경우에는 아래의 작업들을 수행하지 않아도 됩니다.

요구 사항

• Kubernetes 클러스터의 버전과 호환되는 CSI 드라이버 배포
• 각 워커 노드의 kubelet에 --allow-privileged 플래그(flag)를 true로 설정
• 각 워커 노드의 kubelet에 --feature-gates=VolumeSnapshotDataSource=true,KubeletPluginsWatcher=true,CSINodeInfo=true,CSIDriverRegistry=true 값의 feature gate 플래그(flag)를 설정

Kubernetes 클러스터에 CSI Driver 배포하기

인증을 위한 토큰 획득

인증 토큰을 발급받기 위해 아래의 페이지로 이동합니다.

• 토큰 발급 페이지

토큰 발급을 위해서는 인증키가 필요합니다. 인증키는 포털 > 마이페이지 > 인증키 관리에서 확인할 수 있습니다.

1. 토큰 발급 페이지 상단의 [Authorize] 버튼을 클릭합니다.
2. 포털에서 발급받은 인증키를 Access Key, Secret Key 필드에 입력합니다. API Key 필드는 비워둡니다. 입력 후 아래의 [Authorize] 버튼을 클릭합니다. 인증키가 입력된 것을 확인한 후, Done을 클릭합니다.
3. 인증키 입력 후 /auth/token/issue 항목을 클릭합니다. 다음 화면에서 Try it out을 클릭합니다.
4. 아래 endpoint의 key에 해당하는 value에 Kubernetes Service에서 구동 중인 클러스터의 endpoint를 입력합니다. endpoint 값은 Kubernetes Service의 페이지에서 구동 중인 클러스터 항목을 클릭하면 확인할 수 있습니다.
5. endpoint 입력 후 [Execute] 버튼을 클릭합니다. 작업이 성공하였다면 아래 Response에서 발급된 토큰을 확인할 수 있습니다.
6. 발급된 토큰이 유효한지는 여부는 /auth/token/validate 항목에서 확인할 수 있습니다.

CSI Driver 배포

발급받은 토큰으로 Secret을 생성합니다.
아래 Secret 예제의 access-token key의 value에 발급받은 토큰을 입력하고, secret.yml라는 이름으로 저장합니다.

apiVersion: v1
kind: Secret
metadata:
  name: nks-access-token
  namespace: kube-system
stringData:
  access-token: "eyJhbGciO__REPLACE_ME____f9hJtQa4rb7A"

저장한 파일과 kubectl 명령어로 Secret을 생성합니다.

$ kubectl --kubeconfig=$KUBE_CONFIG create -f ./secret.yml
secret "nks-access-token" created

네임스페이스 kube-system에 생성된 Secert을 확인 할 수 있습니다.

$ kubectl --kubeconfig=$KUBE_CONFIG get secrets -n kube-system
NAME                  TYPE                                  DATA      AGE
nks-access-token      Opaque                                1         1m

CSI 드라이버 및 Sidecar 배포

CSI 드라이버 및 Sidecar들을 배포합니다. 운영되고 있는 Kubernetes Cluster와 호환되는 버전의 CSI 드라이버를 배포해야합니다. 호환되는 버전의 목록은 제약 사항에서 확인할 수 있습니다.

k8s 1.12 버전에서 배포

kubernetes 1.12버전은 CSI v0.4와 호환됩니다.

$ kubectl --kubeconfig=$KUBE_CONFIG apply -f http://nks-static.ncloud.com:8443/csi/0.4/latest/csi-nks-configmap.yaml
$ kubectl --kubeconfig=$KUBE_CONFIG apply -f http://nks-static.ncloud.com:8443/csi/0.4/latest/csi-nks-driver.yaml

k8s 1.17 버전에서 배포

kubernetes 1.17버전은 CSI v2.x와 호환됩니다.

$ kubectl --kubeconfig=$KUBE_CONFIG apply -f http://nks-static.ncloud.com:8443/csi/0.4/latest/csi-nks-configmap.yaml
$ kubectl --kubeconfig=$KUBE_CONFIG apply -f https://nks.apigw.ntruss.com/static/v1/csi/classic/2.0/latest/csi-nks-driver.yaml

이 파일들은 최신의 안정 버전을 가리킵니다. 설치 과정 중 문제가 생긴 경우 kubectl apply -f 명령을 다시 실행하여 누락된 리소스가 다시 반영되도록 합니다.

CSI Driver Object

Kubernetes 클러스터에서 영구 데이터(Persistent data)를 읽고 쓰는 작업이 필요할 때, CSI 드라이버를 이용하여 블록 스토리지를 컨테이너에 마운트할 수 있습니다. 필요한 스토리지 크기를 PersistentVolumeClaim(PVC)를 통해 요청할 수 있습니다. CSI 드라이버는 생성된 PVC를 확인하여, 블록 스토리지를 생성 후 할당을 요청한 컨테이너에 마운트합니다.

Storage Class

Kubernetes에서 StorageClass는 성능 및 목적에 따라 다양한 스토리지들을 추상화한 개념입니다. 이를 통해 각 스토리지에 대해 임의의 정책이나 타입 등을 설정할 수 있습니다. 네이버 클라우드 플랫폼에서는 블록 스토리지를 사용하는 기본 StorageClass를 제공합니다.

네임스페이스 kube-system 내의 StorageClass에서 nks-block-storage라는 이름의 object를 확인할 수 있습니다.

kind: StorageClass
apiVersion: storage.k8s.io/v1
metadata:
  name: nks-block-storage
  namespace: kube-system
  annotations:
    storageclass.kubernetes.io/is-default-class: "true"
provisioner: blk.csi.ncloud.com
volumeBindingMode: WaitForFirstConsumer
reclaimPolicy: Delete
allowVolumeExpansion: true
parameters:
  type: SSD

① Default Storage Class는 annotation의 storageclass.kubernetes.io/is-default-class 값을 true로 가집니다. 다른 값이거나 annotation이 없는 경우 false로 적용됩니다.

② volumeBindingMode 값을 통해 볼륨 바인딩과 동적 프로비저닝(Dynamic Provisioning)이 어느 시점에 동작할지를 제어할 수 있습니다. 정의되지 않았다면, 기본값으로 Immediate을 가집니다.

③ reclaimPolicy를 통해, 사용이 끝난 PVC가 삭제될 때 사용 중이던 PersistentVolume(PV)에 대한 재확보(Reclaim) 정책을 설정할 수 있습니다. 정의되지 않았다면, 기본값은 Delete입니다.

④ parameters의 type을 통해 생성될 블록 스토리지의 타입을 선택할 수 있습니다. SSD와 HDD 중 하나를 사용합니다. 정의되지 않았다면, 기본값은 SSD입니다.

⑤ allowVolumeExpansion 필드가 true인 경우 PVC(PersistentVolumeClaim)를 확장할 수 있습니다.

생성된 StorageClass Object의 내용을 변경하기 위해서는 아래의 문서를 참고합니다.

• Changing the default StorageClass

CSI Controller

볼륨의 생성, 삭제, 할당, 할당 해제, 스냅샷 등의 컨트롤과 관리를 담당합니다. 네임스페이스 kube-system 내의 statefulset에서 확인할 수 있습니다.

$ kubectl --kubeconfig=$KUBE_CONFIG get statefulset -n kube-system
NAME                 DESIRED   CURRENT   AGE
csi-nks-controller   1         1         37d

CSI Node

Kubernetes 워커 노드마다 하나씩 동작하고 있으며 볼륨의 포맷, 마운트, 언마운트 등의 동작을 담당합니다. 네임스페이스 kube-system 내의 daemonset에서 확인할 수 있습니다.

$ kubectl --kubeconfig=$KUBE_CONFIG get daemonset -n kube-system
NAME           DESIRED   CURRENT   READY   UP-TO-DATE   AVAILABLE   NODE SELECTOR                 AGE
csi-nks-node   3         3         3       3            3           <none>                        44d

CSI를 이용한 블록 스토리지 할당

PersistentVolumeClaim

필요한 PersistentVolume(PV) 리소스는 PersistentVolumeClaim(PVC)을 통해 요청할 수 있습니다. CSI Driver는 PVC를 확인하여, 필요한 PersistentVolume(PV)을 자동으로 생성합니다.

apiVersion: v1
kind: PersistentVolumeClaim
metadata:
  name: csi-pod-pvc
spec:
  accessModes:
  - ReadWriteOnce
  resources:
    requests:
      storage: 10Gi
  storageClassName: nks-block-storage

AccessMode

네이버 클라우드 플랫폼의 블록 스토리지가 지원하는 AccessMode는 다음과 같습니다.

• ReadWriteOnce: 단일 노드가 볼륨을 읽기/쓰기 가능하게 마운트될 수 있습니다.

Resources

필요한 스토리지의 크기를 입력합니다. 입력하지 않으면 20GB 값이 기본값으로 사용됩니다. 스토리지 크기는 10GB 단위로 입력할 수 있으며, 최소 10GB에서 최대 2000GB 사이의 값이 허용됩니다.

Pod에 단일 신규 볼륨 할당

새로운 블록 스토리지를 하나 생성하여, 이를 볼륨으로 마운트합니다.

apiVersion: v1
kind: PersistentVolumeClaim
metadata:
  name: csi-pod-pvc
spec:
  accessModes:
  - ReadWriteOnce
  resources:
    requests:
      storage: 10Gi
  storageClassName: nks-block-storage
---
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: csi-pod-pvc

Pod

Pod의 spec.volumes에 컨테이너와 바인딩될 스토리지들을 정의할 수 있습니다. 배열의 요소로 입력하며, 스토리지 이름과 생성된 PVC의 이름을 persistentVolumeClaim의 claimName에 입력합니다.

컨테이너에서 정의된 스토리지들을 마운트할 수 있습니다. spec.container에서 PersistentVolume이 필요한 컨테이너가 있다면 volumeMounts에 정의된 스토리지 이름을 입력합니다. 마운트될 경로는 mountPath에 입력합니다.

이미 생성된 블록 스토리지를 Pod에 마운트

본 방식은 사용자가 PersistentVolumeClaim(PVC)을 생성하여 필요한 스토리지 볼륨 자동 생성을 요청하는 방식이 아니라,
이미 생성되어 있는 블록 스토리지를 이용하여 PersistentVolume(PV)을 만드는 기능입니다.

이미 생성되어 있는 블록 스토리지 Instance ID를 이용하여 PersistentVolume(PV)을 만듭니다.

kind: PersistentVolume
apiVersion: v1
metadata:
  name: volume-existing-01
  annotations:
    pv.kubernetes.io/provisioned-by: blk.csi.ncloud.com # 블록 스토리지와 연동될 provisoner 이름
spec:
  storageClassName: nks-block-storage # 블록 스토리지의 스토리지 클래스 이름
  persistentVolumeReclaimPolicy: Retain
  capacity:
    storage: 10Gi # 블록 스토리지 크기
  accessModes:
    - ReadWriteOnce
  csi:
    driver: blk.csi.ncloud.com
    fsType: ext4
    volumeHandle: "952814" # Block Storage Instance ID
    volumeAttributes:
      blk.csi.ncloud.com/noformat: "true" # 블록스토리지를 포맷하지 않음
---
apiVersion: v1
kind: PersistentVolumeClaim
metadata:
  name: csi-pod-pvc
spec:
  accessModes:
  - ReadWriteOnce
  resources:
    requests:
      storage: 10Gi
  storageClassName: nks-block-storage
  volumeName: "volume-existing-01"
---
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: csi-pod-pvc

PersistentVolume

이미 존재하는 블록 스토리지를 Kubernetes 클러스터에서 사용하기 위해서는 PersistentVolume을 생성 시, 해당 정보를 입력합니다.

• storageClassName에 네이버 클라우드 플랫폼의 스토리지 클래스인 nks-block-storage를 입력합니다.
• capacity.storage에 이미 존재하는 블록 스토리지의 크기를 입력합니다.
• accessModes에 ReadWriteOnce를 입력합니다. 블록 스토리지를 지원하는 스토리지 클래스는 해당 설정만을 지원합니다.
• csi의 driver에 스토리지 클래스 드라이버 이름인 blk.csi.ncloud.com을 입력합니다.
• csi의 volumeHandle에 생성되어 있는 블록 스토리지의 Instance ID를 입력합니다.
• csi의 volumeAttributes에 blk.csi.ncloud.com/noformat: "true"를 입력합니다. 해당 설정은 포맷을 진행하지 않겠다는 의미이며, 기존에 저장된 내용을 유지한 상태로 마운트합니다.

PersistentVolumeClaim

생성된 PersistentVolume(PV)와 바인딩되는 PersistentVolumeClaim(PVC)을 생성합니다.

• resources의 storage에 이미 존재하는 블록 스토리지의 크기를 입력합니다.
• storageClassName에 블록 스토리지 클래스 이름인 nks-block-storage를 입력합니다.
• volumeName에 생성한 PersistentVolume(PV)의 이름을 입력합니다.

Pod

Pod 생성 시, 볼륨 요청인 PersistentVolumeClaim(PVC)를 지정하여 사용할 볼륨을 마운트합니다.

• spec의 volumes의 요소로 사용할 claimName을 입력합니다.

볼륨 할당 추가 예제

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(PVC)을 생성하여, 신규 볼륨 생성을 요청합니다. 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(PVC)을 자동으로 생성할 수 있습니다.

apiVersion: apps/v1
kind: StatefulSet
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" ]
  volumeClaimTemplates:
    - metadata:
        name: my-volume
      spec:
        accessModes: ["ReadWriteOnce"]
        resources:
          requests:
            storage: 10Gi

CSI를 이용하여 Snapshot 생성 및 볼륨 복구

볼륨 Snapshot 생성

VolumeSnapshot은 CSI에서 정의한 사용자 지정 리소스(Custom Resource Definition, CRD)입니다. 자세한 사항은 아래의 링크를 참고하세요.

• Snapshot-Restore-Feature

PersistentVolume(PV)과 바인딩되어 있는 PersistentVolumeClaim(PVC)을 이용하여, VolumeSnapshot을 생성합니다.

apiVersion: snapshot.storage.k8s.io/v1alpha1
kind: VolumeSnapshot
metadata:
  name: csi-nks-test-snapshot # 신규 생성될 VolumeSnapShot이 사용할 이름을 입력
spec:
  source:
    name: csi-pod-pvc # Snapshot을 생성할 PV와 바인딩 되어 있는 PVC의 이름을 입력
    kind: PersistentVolumeClaim

• metadata의 name에 새롭게 생성될 VolumeSnapShot이 사용할 이름을 입력합니다.
• spec의 source.name에 snapshot을 생성할 PV와 바인딩 되어 있는 PVC 이름을 입력합니다.
• spec의 source.kind에는 PersistentVolumeClaim을 입력합니다.

생성된 볼륨 snapshot 확인

생성된 볼륨 snapshot을 확인하기 위해, 다음의 kubectl 명령어를 이용합니다.
볼륨 snapshot의 resource 이름은 VolumeSnapShot입니다.

$ kubectl --kubeconfig=$KUBE_CONFIG get volumesnapshot
NAME                    AGE
csi-nks-test-snapshot   17h

생성된 볼륨 snapshot 삭제

생성된 볼륨 snapshot을 확인하기 위해, 다음의 kubectl 명령어를 이용합니다.
삭제할 볼륨 snapshot의 이름을 이용하여 해당 resource를 삭제합니다.

$ kubectl --kubeconfig=$KUBE_CONFIG get volumesnapshot
NAME                    AGE
csi-nks-test-snapshot   17h

$ kubectl --kubeconfig=$KUBE_CONFIG delete volumesnapshot csi-nks-test-snapshot
volumesnapshot.snapshot.storage.k8s.io "csi-nks-test-snapshot" deleted

생성된 볼륨 snapshot으로부터 볼륨 복구

볼륨 snapshot을 이용하여, 신규 볼륨 생성을 요청합니다. 생성된 snapshot의 내용이 신규 볼륨으로 복제됩니다.

apiVersion: v1
kind: PersistentVolumeClaim
metadata:
  name: csi-nks-test-pvc-restore
spec:
  dataSource:
    name: csi-nks-test-snapshot # 복구할 볼륨 snapshot의 이름
    kind: VolumeSnapshot
    apiGroup: snapshot.storage.k8s.io
  accessModes:
    - ReadWriteOnce
  resources:
    requests:
      storage: 10Gi
  storageClassName: nks-block-storage
---
kind: Pod
apiVersion: v1
metadata:
  name: csi-restore-app
spec:
  containers:
    - name: my-frontend
      image: busybox
      volumeMounts:
        - mountPath: "/data"
          name: my-volume
      command: [ "sleep", "1000000" ]
  volumes:
    - name: my-volume
      persistentVolumeClaim:
        claimName: csi-nks-test-pvc-restore

PersistentVolumeClaim

볼륨 snapshot으로부터 볼륨을 복구하기 위해서는 spec.dataSource에 대상 정보를 입력합니다.

• dataSource.name에 복구할 볼륨 snapshot의 이름을 입력합니다.
• dataSource.kind에 복구 대상의 resource 이름인 VolumeSnapshot을 입력합니다.
• dataSource.apiGroup에 snapshot의 apiGroup인 snapshot.storage.k8s.io를 입력합니다.
• resources.requests.storage에 볼륨 snapshot의 크기와 동일한 값을 입력합니다.

Pod

요청한 볼륨 정보인 PersistentVolumeClaim(PVC)의 이름을 claimName에 입력합니다.

PersistentVolumeClaim 제거

Kubernetes에서는 PersistentVolumeClaim(PVC)은 요청된 Deployment, StatefulSet, ReplicaSet, Pod와 같은 리소스를 삭제하더라도 함께 제거되지 않습니다.

다음의 명령어를 통해서 PersistentVolumeClaim(PVC)를 삭제할 수 있습니다.

# pvc 조회
$ kubectl --kubeconfig=$KUBE_CONFIG get pvc
NAME          STATUS   VOLUME                           CAPACITY   ACCESS MODES   STORAGECLASS        AGE
csi-pod-pvc   Bound    pvc-084a811bac4211e9842bf220cd   10Gi       RWO            nks-block-storage   2m8s

# pvc 삭제
$ kubectl --kubeconfig=$KUBE_CONFIG delete pvc csi-pod-pvc
persistentvolumeclaim "csi-pod-pvc" deleted