![func (ns *nodeServer) NodeGetCapabilities(ctx context.Context,
req *csi.NodeGetCapabilitiesRequest) (*csi.NodeGetCapabilitiesResponse, error) {
return &csi.NodeGetCapabilitiesResponse{
Capabilities: []*csi.NodeServiceCapability{
{
Type: &csi.NodeServiceCapability_Rpc{
Rpc: &csi.NodeServiceCapability_RPC{
Type: csi.NodeServiceCapability_RPC_STAGE_UNSTAGE_VOLUME,
},
},
},
...
},
}, nil
}
Capabilityの設定例
22https://github.com/kubernetes-csi/csi-driver-host-path/blob/v1.3.0/pkg/hostpath/nodeserver.go#L279-L299
CSIドライバで提供する機能に応じ、
capabilityを列挙する](https://image.slidesharecdn.com/csi-200613011932/85/Container-Storage-Interface-22-320.jpg)
Container Storage Interface のすべて
- 1. Container Storage Interface のすべて KubeFest Tokyo 2020 2020/06/13 サイボウズ株式会社 Yuji Ito
- 2. 自己紹介 ▌伊藤祐司 ⚫ 分散システムにかかわる仕事がしたく、2019年10月 からNecoチームでデータセンタの開発に参画している。 ▌サイボウズ株式会社 Necoチーム ⚫ 自社データセンタに1000ノード規模のKubernetes クラスタを構築する。 ⚫ ストレージ専従ではなく、約1ヵ月ごとに班を変えながら 満遍なく知識を蓄える。 2
- 3. 本発表の目的 ▌Container Storage Interface (CSI) について知ってもらう。 ⚫ 概要 ⚫ どのような機能が実装可能なのか ▌CSIドライバの開発を行うための情報を提供する。 ⚫ CSIドライバの開発方法 ⚫ CSIドライバのテスト方法 3
- 4. 発表の流れ ▌PV, PVC, SC のおさらい ▌CSIの概要 ▌CSI・CSIドライバの構造 ▌最小限のCSIドライバの実装 ▌CSIドライバのテスト ▌オプション機能の拡張方法 ▌ドキュメント・参考情報 ▌まとめ 4
- 5. metadata: name: pv01 spec: capacity: ... storageClassName: sc01 PV: Persistent Volume metadata: name: sc01 provisioner: ... parameters: ... SC: Storage Class metadata: name: pvc01 spec: resources: ... storageClassName: sc01 PVC: Persistent Volume Claim PV, PVC, SC のおさらい 5 metadata: name: pod01 spec: containers: volumes: - name: volume01 persistentVolumeClaim: claimName: pvc01 1. PodおよびPodが利用する volumeをPVCとして定義 0. (前準備) SCでPVをグループ分け することが可能 ストレージ システム 2. Podから利用可能なvolume (ファイルシステムまたはRawブロックデバイス) ごとにPVを定義し、関連付ける 4. PVCに関連付けられた PVのvolumeを用い、 Podが起動 3. PVCで定義した条件に マッチするPVがPVCに 関連付けられる
- 6. CSIの概要 6
- 7. CSIの定義に 従った拡張 CSIとはなんなのか ▌各種Container Orchestrators (CO)において、 ストレージ機能を拡張するための 統一されたインタフェース。 ▌PVCの変更に対し、PV・スト レージを自動で作成・拡張・削 除するなどの仕組みを追加可能。 7 ストレージ システム CSIドライバ K8s CSI sidecar container 開発対象となるCSIドライバはKubernetesから 独立しており (out of tree) 誰でも開発可能 監視 作成・変更 操作 Kubernetes プロジェクトから 提供されている CSIで定義されたgRPC Kubernetesに絞って説明
- 8. CSI関連の用語 ▌Volume CSIを通して利用可能になるストレージの単位。ファイルシステムまたはブロックデバイ スのこと。 KubernetesのPVから指示される実際に利用可能な領域に対応。 ▌CSIドライバ / CSIDriver オブジェクト CSIドライバ: CSIを利用するドライバ全体。 CSIDriver: KubernetesにCSIの情報を渡すためのオブジェクト。 ▌Node Plugin 各KubernetesのNode上で動く、CSIドライバのプログラム及びコンテナ。 8
- 9. CSIを利用して実現できる機能 ▌ファイルシステム, Rawブロックデバイスを扱う。 ▌PVCの作成・削除に対応し、PV・ストレージを自動で割当て、削除する。 - Dynamic Provisioning ▌PVCで定義される容量の変更に対応し、ストレージを拡張する。 - Volume Expansion ▌Podの終了とともに開放される短期的な領域の割り当て。 9
- 12. CSIドライバに関連する主な要素 12 CSIDriver (Object) 当該CSIドライバの存在と機能をKubernetes に伝える Controller Plugin の Pod (Deployment/StatefulSet) Node Plugin の Pod (DaemonSet) Controller Plugin コンテナ ・ Controller サービス ・ Identity サービス K8s CSI の sidecar コンテナ Node Plugin コンテナ ・ Node サービス ・ Identity サービス Kubernetes プロジェクトから 提供されている K8s CSI の sidecar コンテナ Kubernetes プロジェクトから 提供されている Kubernetes プロジェクトから 提供されている 開発対象
- 13. apiVersion: v1 kind: Pod metadata: name: pod-name spec: containers: - image: container1:latest name: container-1 volumeMounts: - mountPath: /mnt/share name: shared-volume - image: container2:latest name: container-2 volumeMounts: - mountPath: /mnt/share name: shared-volume volumes: - name: shared-volume emptyDir: {} sidecarのおさらい ▌複数のコンテナを内包するPod ▌コンテナ間で、Volumeの共有や Volume内の Unix Domain Socket (USD) を利用した通信 が可能 13 Pod Container#2Container#1 Container#1 Container#2 Volume
- 14. Kubernetesプロジェクトから提供される主要な CSI sidecar ▌external-provisioner Dynamic Provisioning 機能を提供する場合に利用する。 ▌livenessprobe CSIドライバの状態を Kubernetes に伝えるため、 Readiness Probe 機能と連 携する。 ▌node-driver-registrar Kubernetes がNodeを認識するための CSINode オブジェクトを作成する。 14
- 15. Kubernetes の Node CSIに関するコンポーネントの連携 15 Controller Plugin の Pod (Deployment/StatefulSet) Controller Plugin コンテナ ・ Controller サービス ・ Identity サービス K8s CSI の sidecar コンテナ Node Plugin の Pod (DaemonSet) Node Plugin コンテナ ・ Node サービス ・ Identity サービス K8s CSI の sidecar コンテナ API Server gRPC Unix Domain Socket gRPC Unix Domain Socket Kubelet Volume Volume詳しくは、CSI Volume Plugins in Kubernetes Design Doc を参照 作成 利用
- 17. CSIのspecについて ▌CSIドライバが実装するプロシージャの 細かい仕様が記載されている。 ⚫ 引数の内容 ⚫ 期待する戻り値 ⚫ エラー時の戻り値 ▌https://github.com/ container-storage-interface/ spec/blob/master/spec.md 17
- 19. サービスのスケルトンを生成 ▌各gRPCサービス用のコードを生成。 ⚫ gRPCの定義は以下のリポジトリで公開されている。 https://github.com/container-storage- interface/spec/blob/master/csi.proto ⚫ 言語について制限は無いが、Kubernetesの機能を利用する場合、ライブラリが 充実しているgo言語が無難。 19 ## protocコマンドをダウンロード・展開しておく ## csi.protoフィルをダウンロードしておく GO111MODULE=on go get github.com/golang/protobuf/protoc-gen-go protoc -I=. --go_out=plugins=grpc:. csi.proto
- 20. 生成されたスケルトンについて ▌csi.pb.goが生成される ▌Identity, Controller, Node の各サービスで実装するべきプロシー ジャが定義されている。 20 type IdentityServer interface { GetPluginInfo(context.Context, *GetPluginInfoRequest) (*GetPluginInfoResponse, error) ... type ControllerServer interface { CreateVolume(context.Context, *CreateVolumeRequest) (*CreateVolumeResponse, error) ... type NodeServer interface { NodeStageVolume(context.Context, *NodeStageVolumeRequest) (*NodeStageVolumeResponse, ... ...
- 21. ドライバが提供する機能とcapability ▌CSIドライバで提供したい機能に応じて実装するgRPCメソッドは異なる。 ▌gRPCのAPIを通じて、ドライバ・コンポーネントが提供する機能を Kubernetes や CSI sidecar に伝える。 ⚫ GetPluginCapabilities (Identityサービス) ⚫ ControllerGetCapabilities (Controllerサービス) ⚫ NodeGetCapabilities (Nodeサービス) 21
- 22. func (ns *nodeServer) NodeGetCapabilities(ctx context.Context, req *csi.NodeGetCapabilitiesRequest) (*csi.NodeGetCapabilitiesResponse, error) { return &csi.NodeGetCapabilitiesResponse{ Capabilities: []*csi.NodeServiceCapability{ { Type: &csi.NodeServiceCapability_Rpc{ Rpc: &csi.NodeServiceCapability_RPC{ Type: csi.NodeServiceCapability_RPC_STAGE_UNSTAGE_VOLUME, }, }, }, ... }, }, nil } Capabilityの設定例 22https://github.com/kubernetes-csi/csi-driver-host-path/blob/v1.3.0/pkg/hostpath/nodeserver.go#L279-L299 CSIドライバで提供する機能に応じ、 capabilityを列挙する
- 23. NodePublishVolumeの例 ▌領域をPodが利用可能な状態にする。 ⚫ ファイルシステムの場合、指定されたpathにファイルシステムをマウントする。 ⚫ Rawブロックデバイスの場合、指定されたpathにデバイスファイルを用意する。 23 targetPath := req.GetTargetPath() ... if req.GetVolumeCapability().GetBlock() != nil { ... loopDevice, err := volPathHandler.GetLoopDevice(vol.VolPath) ... mount.New("").Mount(loopDevice, targetPath, "", options) ... } ... return &csi.NodePublishVolumeResponse{}, nil https://github.com/kubernetes-csi/csi-driver-host-path/blob/v1.3.0/pkg/hostpath/nodeserver.go#L50-L189 loop deviceを作成している 引数で渡された場所に loop device をマウントしている
- 24. プロシージャ実装時の注意点 ▌CSIプロシージャは冪等性を満たすように実装する必要がある。 ⚫ Kubernetes 側でプロシージャの成否を取得できなかった場合などに、再度プロ シージャを呼び出すことを許容するため。 ⚫ capacityやparameterが許容可能であれば、正常終了のレスポンスを返す。 24
- 25. CSIDriverの例 ▌CSIドライバの存在と機能を Kubernetes に伝える 25 apiVersion: storage.k8s.io/v1beta1 kind: CSIDriver metadata: name: topolvm.cybozu.com spec: attachRequired: true podInfoOnMount: true volumeLifecycleModes: - Persistent - Ephemeral 該当CSIドライバが提供している機能についての定義 https://github.com/cybozu-go/topolvm/blob/v0.4.8/deploy/manifests/controller.yaml#L2-L11 該当CSIドライバが Kubernetes に要求する 挙動についての定義
- 26. CSIドライバのテスト 26
- 27. CSI Driver Sanity Tester ▌Kubernetes プロジェクトから提供されるCSIドライバのテストツール。 ⚫ https://github.com/kubernetes-csi/csi- test/tree/master/pkg/sanity ▌CSIドライバを起動した状態で、gRPC の応答が正しく実装されているか をテストしてくれる。 ▌コマンドラインから起動 / Ginkgo (Go言語のTesting Framework) から利用。 27 Tip: 手戻りをなくすため、最初からテストを実行できるようにする。
- 28. Sanity Testerの利用例 28 var _ = Describe("TopoLVM", func() { Context("CSI sanity", func() { ... テスト対象のCSIドライバを起動しておく sanity.GinkgoTest(&sanity.Config{ Address: "/tmp/topolvm/worker1/plugins/topolvm.cybozu.com/node/csi-topolvm.sock", ControllerAddress: "/tmp/topolvm/worker1/plugins/topolvm.cybozu.com/controller/csi-topolvm.sock", TargetPath: "/tmp/topolvm/worker1/plugins/topolvm.cybozu.com/node/mountdir", StagingPath: "/tmp/topolvm/worker1/plugins/topolvm.cybozu.com/node/stagingdir", TestVolumeSize: 1073741824, IDGen: &sanity.DefaultIDGenerator{}, }) }) }) https://github.com/cybozu-go/topolvm/blob/v0.4.8/e2e/suite_test.go#L99-L137 Controller と Node の両方のエンドポイントに アクセス可能な環境で実行
- 29. Sanity Tester 以外のテスト ▌Sanity Testerだけでは全てのテストをカバーしているわけではない。 ▌実際にストレージが使えるかのE2Eテストを行っていない。 ⚫ Cybozuで開発しているCSIドライバ (TopoLVM) では、 kindを利用したE2E テストを別途実施している。 ▌個々のCSIドライバの実装に関する単体テストも必要に応じて追加する。 29
- 30. オプション機能の拡張方法 30
- 31. Volume Expansion 機能を提供する ▌定義するCapabilities ⚫ EXPAND_VOLUME (ControllerCapabilities) ⚫ EXPAND_VOLUME (NodeCapabilities) ▌実装するメソッド ⚫ ControllerExpandVolume (Controllerサービス) ⚫ NodeExpandVolume (Nodeサービス) ▌Sidecarとして external-resizer を追加 ▌StorageClass に allowVolumeExpansion を定義 31
- 32. ControllerExpandVolumeの例 ▌サイズの変更が可能かどうかを判定する。 requestGb, err := convertRequestCapacity(req.GetCapacityRange().GetRequiredBytes(), req.GetCapacityRange().GetLimitBytes()) ... if requestGb <= currentGb { return &csi.ControllerExpandVolumeResponse{ CapacityBytes: currentGb << 30, NodeExpansionRequired: true, }, nil } ... if capacity < (requestGb<<30 - currentGb<<30) { return nil, status.Error(codes.Internal, "not enough space") } ... return &csi.ControllerExpandVolumeResponse{ CapacityBytes: requestGb << 30, NodeExpansionRequired: true, }, nil 領域の縮小が要求される場合もある 領域の拡張を許容する場合 NodeExpansionRequired が true の場合、 Node の NodeExpandVolume (次スライド) が呼ばれる https://github.com/cybozu-go/topolvm/blob/v0.4.8/driver/controller.go#L310-L376 32
- 33. NodeExpandVolumeの例 ▌各ノード上で、サイズ変更後のVolumeを利用可能にする。 ⚫ TopoLVMではlvmd (Kubernetes node 上の daemon) でlvを拡張してい るため、NodeExpandVolume ではファイルシステムの拡張のみを行う。 33 vpath := req.GetVolumePath() ... err = fs.Resize(vpath) ... return &csi.NodeExpandVolumeResponse{}, nil https://github.com/cybozu-go/topolvm/blob/v0.4.8/driver/node.go#L414-L498
- 34. Dynamic Provisioning 機能を提供する ▌定義するCapabilities ⚫ CREATE_DELETE_VOLUME (ControllerCapabilities) ▌実装するメソッド ⚫ CreateVolume (Controllerサービス) ⚫ DeleteVolume (Controllerサービス) ▌Sidecarとして external-provisioner を追加 ▌StorageClass の provisioner と、GetPluginInfo で戻すnameの 値を同じにしておく。 34 詳しい実装はTopoLVMを参照
- 35. ドキュメント・参考情報 35
- 36. CSIのバージョンについて ▌CSIのバージョンはKubernetesと 独立している。 ▌Kubernetes v1.13 のタイミン グで CSIはGAとなりバージョンが 1.0になった。 36https://github.com/container-storage-interface/spec/releases
- 37. CSI sidecarのバージョンについて ▌各sidecarのバージョンはspecか ら独立して管理される ⚫ CSIがGAになった後に追加された機 能もあり、機能ごとにalpha, beta, GAの状況は異なる ▌Kubernetes, spec, sidecar のバージョンの対応については、各 sidecarのReleasesに記載があ る。 37https://github.com/kubernetes-csi/external-provisioner/releases
- 38. 参考となるCSIドライバ ▌sig-storage でCSIドライバのサンプルを公開している。 ▌https://github.com/kubernetes-csi/ ⚫ csi-driver-host-path ⚫ csi-driver-nfs ⚫ csi-driver-smb 38
- 39. 既存のCSIドライバ ▌以下のページより既存のCSIドライバ一覧が探すことが可能。 ⚫ https://kubernetes-csi.github.io/docs/drivers.html ▌サイボウズでもTopoLVMというCSIドライバを開発・公開している。 ⚫ 各NodeのLVM領域を動的に提供する。 ⚫ Topologyを考慮し、ストレージ容量の空きが多いNodeにPodが優先配置され る。 ⚫ https://blog.cybozu.io/entry/2019/11/08/090000 39
- 40. ドキュメント ▌Container Storage Interface (CSI) のspec https://github.com/container-storage-interface/spec/ ▌CSI Volume Plugins in Kubernetes Design Doc https://github.com/kubernetes/community/blob/master/contribut ors/design-proposals/storage/container-storage-interface.md ▌Kubernetes CSI Developer Documentation https://kubernetes-csi.github.io/docs/introduction.html ▌各sidecarのREADME.mdにオプションなどが記載されている 40
- 41. まとめ ▌シンプルなCSIドライバを例に、実装方法ついて説明した。 ⚫ まだたくさんのドキュメントを読む必要がある。 ⚫ 特にCSIのspecは、詳細まで記述してある。 ▌実装時の注意点・Tipについて説明した。 ⚫ CSIドライバで提供したい機能に合わせて利用するsidecarや実装するプロシー ジャが変わる。 ⚫ CSIドライバのプロシージャは冪等性を満たす必要がある。 ⚫ 開発初期からSanity Testerを利用し、手戻りを防ぐ。 41