ブロックストレージCSIのご利用ガイド

当該コンテンツは、ローカリゼーションサービスを準備しております。早急にローカライズサービスをご提供できるよう、努めております。

Classic環境で利用できます。

ご利用の前に

全てのコンテナーは、ビルドの時点で追加されたファイルを利用して駆動されます。その後、コンテナーのファイルシステム内に新しく追加されたファイルは、プロセスが終了したり、Kubernetesのliveness Probeのステータスチェックに失敗し、コンテナーが再起動される場合に全て削除されます。

コンテナーが再起動される場合でも、上述した追加されたファイルを継続して維持させることを希望するなら、配布の際に作ることのできるPersistentVolumeClaim(PVC)を通じてデータの保存のために作ることができる永久なリポジトリであるブロックストレージを利用することができます。

NAVERクラウドプラットフォームのNcloud Kubernetes Serviceは、ボリュームドライバーとして、Container Storage Interface(CSI)を提供します。このボリュームドライバーは、Kubernetesと連携され、ブロックストレージの生成と削除及びattaching、detachingのような作業をサポートします。

制限事項

対応バージョン

NAVERクラウドプラットフォームのKubernetes Serviceは、ブロックストレージのボリュームドライバーとしてCSIを提供します。CSIドライバーとKubernetesとの間の連携のためには、互換性のあるバージョンを確認する必要があります。

現在、NAVERクラウドプラットフォームから提供している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を配布する

1. 発行されたトークンで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

Namespace kube-systemに作られたSecertを確認することができます。

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

CSIドライバー及びSidecarを配布する

1. 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.0と互換性があります。

$ 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コマンドを再度実行して漏れたresourceが再度反映されるようにします。

CSI Driver Object

Kubernetesのクラスターは、永続データ(Persistent data)を読み取り及び書き込み作業が必要な場合、CSIドライバーを用いてブロックストレージをコンテナーにマウントすることができます。必要なストレージサイズをPersistentVolumeClaim(PVC)を通じてリクエストすることができます。CSIドライバーは、作られたPVCを確認し、ブロックストレージを作った後で割り当てをリクエストしたコンテナーをマウントさせます。

Storage Class

KubernetesにおいてStorageClassは、性能及び目的に応じて多様なストレージを抽象化した概念です。それを通じて、各ストレージに対して任意のポリシーやタイプなどを設定することができます。NAVERクラウドプラットフォームでは、ブロックストレージを利用する基本的なStorageClassを提供します。

Namespace 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

ボリュームの生成、削除、割り当て、割り当て解除、snapshotなどのコントロールと管理とを担当します。Namespace 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のワーカーノード毎に1つずつ動作しており、ボリュームのフォーマット、マウント、アンマウントなどの動作を担当します。Namespace 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) resourceは、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

NAVERクラウドプラットフォームのブロックストレージに対応するAccessModeは、次の通りです。

• ReadWriteOnce: 単一ノードがボリュームを読み取り/書き込みできるようにマウントされることができます。

Resources

必要なストレージのサイズを入力します。入力しなければ20GB値が基本値として利用されます。ストレージサイズは、10GB単位で入力することができ、最小10GBから最大2000GBまでの間の値が許容されます。

Podに単一の新規ボリュームを割り当て

新しいブロックストレージを1つ作り、それをボリュームでマウントします。

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にNAVERクラウドプラットフォームのストレージクラスである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に複数のボリュームを割り当て

2つの新規のブロックストレージを作り、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で定義したユーザー指定のresource(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のようなresourceを削除するとしても一緒に削除されません。

次のコマンドを利用し、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