Harvester CSI Driver

警告

Harvester CSI driver v0.1.20 存在一個已知問題，當主機叢集執行的 Harvester 版本早於 v1.4.0 時，會導致磁碟區卡住。

此問題已在 v0.1.21 中修復。如果您的系統受到影響，可以按照建議的解決方法操作。

Harvester CSI Driver 版本	Harvester 版本	受影響
v0.1.21 及更新版本	所有版本	否
v0.1.20	v1.4.0 及更新版本	否
v0.1.20	v1.3.2 及更早版本	是
v0.1.18 及更早版本	所有版本	否

Harvester 容器儲存介面（CSI）Driver 提供標準的 CSI 介面，供 Harvester 中的客體 Kubernetes 叢集使用。它連接到主機叢集並將主機磁碟區熱插拔到虛擬機器（VM），以提供原生儲存效能。

Harvester CSI driver 支援以下功能：

Harvester CSI Driver 版本	Harvester 版本	儲存分層	RWX 磁碟區	線上調整大小	第三方儲存	快照和備份
0.1.15	所有版本	✔	✖	✖	✖	✖
0.1.20	v1.4 及更新版本	✔	✔	✖	✖	✖
0.1.24	v1.6 及更新版本	✔	✔	✔	✔	✖

部署

先決條件

Kubernetes 叢集建構在 Harvester 虛擬機器之上。
作為客體 Kubernetes 節點執行的 Harvester 虛擬機器位於相同的命名空間中。

備註

目前，Harvester CSI driver 僅支援單節點讀寫（RWO）磁碟區。請關注 issue #1992 以獲取未來多節點 唯讀（ROX）和 讀寫（RWX）支援的資訊。

使用 Harvester RKE2 node driver 部署

使用 Rancher RKE2 node driver 啟動 Kubernetes 叢集時，選擇 Harvester cloud provider 後，Harvester CSI driver 將自動部署。

select-harvester-cloud-provider

在 RKE2 叢集中手動安裝 CSI driver

如果您希望在不啟用 Harvester cloud provider 的情況下安裝 Harvester CSI driver，可以參考以下步驟：

手動安裝的先決條件

確保您具備以下先決條件：

您的系統上已安裝 kubectl 和 jq。
您擁有裸機 Harvester 叢集的 kubeconfig 檔案。您可以在其中一個 Harvester 管理節點的 /etc/rancher/rke2/rke2.yaml 路徑中找到 kubeconfig 檔案。
```
export KUBECONFIG=/path/to/your/harvester-kubeconfig
```

執行以下步驟手動部署 Harvester CSI driver：

部署 Harvester CSI driver

產生 cloud-config。您可以使用 generate_addon_csi.sh 腳本產生 cloud-config 檔案。該腳本可在 harvester/harvester-csi-driver 儲存庫中找到。

<serviceaccount name> 通常對應於您的客體叢集名稱，<namespace> 應與機器池的命名空間匹配。

./generate_addon_csi.sh <serviceaccount name> <namespace> RKE2

產生的輸出將類似於以下內容：

########## cloud-config ############
apiVersion: v1
clusters:
- cluster: <token>
    server: https://<YOUR HOST HARVESTER VIP>:6443
  name: default
contexts:
- context:
    cluster: default
    namespace: default
    user: rke2-guest-01-default-default
  name: rke2-guest-01-default-default
current-context: rke2-guest-01-default-default
kind: Config
preferences: {}
users:
- name: rke2-guest-01-default-default
  user:
    token: <token>
########## cloud-init user data ############
write_files:
  - encoding: b64
    content: YXBpVmVyc2lvbjogdjEKY2x1c3RlcnM6Ci0gY2x1c3RlcjoKICAgIGNlcnRpZmljYXRlLWF1dGhvcml0eS1kYXRhOiBMUzB0TFMxQ1JVZEpUaUJEUlZKVVNVWkpRMEZVUlMwdExTMHRDazFKU1VKbFZFTkRRVklyWjBGM1NVSkJaMGxDUVVSQlMwSm5aM0ZvYTJwUFVGRlJSRUZxUVd0TlUwbDNTVUZaUkZaUlVVUkVRbXg1WVRKVmVVeFlUbXdLWTI1YWJHTnBNV3BaVlVGNFRtcG5NVTE2VlhoT1JGRjNUVUkwV0VSVVNYcE5SRlY1VDFSQk5VMVVRVEJOUm05WVJGUk5lazFFVlhsT2FrRTFUVlJCTUFwTlJtOTNTa1JGYVUxRFFVZEJNVlZGUVhkM1dtTnRkR3hOYVRGNldsaEtNbHBZU1hSWk1rWkJUVlJaTkU1VVRURk5WRkV3VFVSQ1drMUNUVWRDZVhGSENsTk5ORGxCWjBWSFEwTnhSMU5OTkRsQmQwVklRVEJKUVVKSmQzRmFZMDVTVjBWU2FsQlVkalJsTUhFMk0ySmxTSEZEZDFWelducGtRa3BsU0VWbFpHTUtOVEJaUTNKTFNISklhbWdyTDJab2VXUklNME5ZVURNeFZXMWxTM1ZaVDBsVGRIVnZVbGx4YVdJMGFFZE5aekpxVVdwQ1FVMUJORWRCTVZWa1JIZEZRZ292ZDFGRlFYZEpRM0JFUVZCQ1owNVdTRkpOUWtGbU9FVkNWRUZFUVZGSUwwMUNNRWRCTVZWa1JHZFJWMEpDVWpaRGEzbEJOSEZqYldKSlVESlFWVW81Q2xacWJWVTNVV2R2WjJwQlMwSm5aM0ZvYTJwUFVGRlJSRUZuVGtsQlJFSkdRV2xCZUZKNU4xUTNRMVpEYVZWTVdFMDRZazVaVWtWek1HSnBZbWxVSzJzS1kwRnhlVmt5Tm5CaGMwcHpMM2RKYUVGTVNsQnFVVzVxZEcwMVptNTZWR3AxUVVsblRuTkdibFozWkZRMldXWXpieTg0ZFRsS05tMWhSR2RXQ2kwdExTMHRSVTVFSUVORlVsUkpSa2xEUVZSRkxTMHRMUzBLCiAgICBzZXJ2ZXI6IGh0dHBzOi8vMTkyLjE2OC4wLjEzMTo2NDQzCiAgbmFtZTogZGVmYXVsdApjb250ZXh0czoKLSBjb250ZXh0OgogICAgY2x1c3RlcjogZGVmYXVsdAogICAgbmFtZXNwYWNlOiBkZWZhdWx0CiAgICB1c2VyOiBya2UyLWd1ZXN0LTAxLWRlZmF1bHQtZGVmYXVsdAogIG5hbWU6IHJrZTItZ3Vlc3QtMDEtZGVmYXVsdC1kZWZhdWx0CmN1cnJlbnQtY29udGV4dDogcmtlMi1ndWVzdC0wMS1kZWZhdWx0LWRlZmF1bHQKa2luZDogQ29uZmlnCnByZWZlcmVuY2VzOiB7fQp1c2VyczoKLSBuYW1lOiBya2UyLWd1ZXN0LTAxLWRlZmF1bHQtZGVmYXVsdAogIHVzZXI6CiAgICB0b2tlbjogZXlKaGJHY2lPaUpTVXpJMU5pSXNJbXRwWkNJNklreGhUazQxUTBsMWFsTnRORE5TVFZKS00waE9UbGszTkV0amNVeEtjM1JSV1RoYVpUbGZVazA0YW1zaWZRLmV5SnBjM01pT2lKcmRXSmxjbTVsZEdWekwzTmxjblpwWTJWaFkyTnZkVzUwSWl3aWEzVmlaWEp1WlhSbGN5NXBieTl6WlhKMmFXTmxZV05qYjNWdWRDOXVZVzFsYzNCaFkyVWlPaUprWldaaGRXeDBJaXdpYTNWaVpYSnVaWFJsY3k1cGJ5NXpaWEoyYVdObFlXTmpiM1Z1ZEM5elpXTnlaWFF1Ym1GdFpTSTZJbkpyWlRJdFozVmxjM1F0TURFdGRHOXJaVzRpTENKcmRXSmxjbTVsZEdWekxtbHZMM05sY25acFkyVmhZMk52ZFc1MEwzTmxjblpwWTJVdFlXTmpiM1Z1ZEM1dVlXMWxJam9pY210bE1pMW5kV1Z6ZEMwd01TSXNJbXQxWW1WeWJtVjBaWE11YVc4dmMyVnlkbWxqWldGalkyOTFiblF2YzJWeWRtbGpaUzFoWTJOdmRXNTBMblZwWkNJNkltTXlZak5sTldGaExUWTBNMlF0TkRkbU1pMDROemt3TFRjeU5qWXpNbVl4Wm1aaU5pSXNJbk4xWWlJNkluTjVjM1JsYlRwelpYSjJhV05sWVdOamIzVnVkRHBrWldaaGRXeDBPbkpyWlRJdFozVmxjM1F0TURFaWZRLmFRZmU1d19ERFRsSWJMYnUzWUVFY3hmR29INGY1VnhVdmpaajJDaWlhcXB6VWI0dUYwLUR0cnRsa3JUM19ZemdXbENRVVVUNzNja1BuQmdTZ2FWNDhhdmlfSjJvdUFVZC04djN5d3M0eXpjLVFsTVV0MV9ScGJkUURzXzd6SDVYeUVIREJ1dVNkaTVrRWMweHk0X0tDQ2IwRHQ0OGFoSVhnNlMwRDdJUzFfVkR3MmdEa24wcDVXUnFFd0xmSjdEbHJDOFEzRkNUdGhpUkVHZkUzcmJGYUdOMjdfamR2cUo4WXlJQVd4RHAtVHVNT1pKZUNObXRtUzVvQXpIN3hOZlhRTlZ2ZU05X29tX3FaVnhuTzFEanllbWdvNG9OSEpzekp1VWliRGxxTVZiMS1oQUxYSjZXR1Z2RURxSTlna1JlSWtkX3JqS2tyY3lYaGhaN3lTZ3o3QQo=
    owner: root:root
    path: /var/lib/rancher/rke2/etc/config-files/cloud-provider-config
    permissions: '0644'

將 cloud-init user data 內容複製並貼上到 Machine Pools > Show Advanced > User Data。

套用上述 cloud-init user data 後，將建立 cloud-provider-config 檔案。您可以在客體 Kubernetes 節點的 /var/lib/rancher/rke2/etc/config-files/cloud-provider-config 路徑中找到它。
將 Cloud Provider 設定為 Default - RKE2 Embedded 或 External。
選擇 Create 以建立您的 RKE2 叢集。
RKE2 叢集準備就緒後，從 Rancher marketplace 安裝 Harvester CSI Driver chart。預設情況下，您不需要變更 cloud-config 路徑。

備註

如果您不想使用 Rancher（Apps > Charts）安裝 Harvester CSI driver，可以改用 Helm。

Harvester CSI driver 以 Helm chart 形式打包。

更多資訊請參閱 https://charts.harvesterhci.io。

按照上述步驟操作後，您應該可以看到這些 CSI driver pod 在 kube-system 命名空間中啟動並執行，您可以透過在 RKE2 叢集上使用預設 StorageClass harvester 佈建新的 PVC 來驗證它。

使用 Harvester K3s node driver 部署

您可以按照 RKE2 部分描述的部署 Harvester CSI Driver 步驟操作。

唯一的區別是在產生 cloud-init 設定時，您需要將提供者類型指定為 k3s：

./generate_addon_csi.sh <serviceaccount name> <namespace> k3s

自訂預設 StorageClass

Harvester CSI driver 提供定義預設 StorageClass 的介面。如果未指定預設 StorageClass，Harvester CSI driver 將使用主機 Harvester 叢集的預設 StorageClass。

您可以使用參數 host-storage-class 來自訂預設 StorageClass。

為主機 Harvester 叢集建立 StorageClass。

範例：
使用參數 host-storage-class 部署 CSI driver。

範例：
驗證 Harvester CSI driver 已準備就緒。
在 PersistentVolumeClaims 畫面上，建立 PVC。選擇 Use a Storage Class to provision a new Persistent Volume 並指定您建立的 StorageClass。

範例：
PVC 建立後，記下佈建磁碟區的名稱並驗證狀態為 Bound。

範例：
在 Volumes 畫面上，驗證磁碟區是使用您建立的 StorageClass 佈建的。

範例：

透通自訂 StorageClass

從 Harvester CSI driver v0.1.15 開始，可以在客體 Kubernetes 叢集上使用不同的 Harvester StorageClass 建立 PersistentVolumeClaim（PVC）。

備註

每個支援的 RKE2 版本都內建了相容的 Harvester CSI driver。

先決條件

將以下先決條件新增到您的 Harvester 叢集，以確保 Harvester CSI driver 正確顯示錯誤訊息。正確的 RBAC 設定對於錯誤訊息的可見性至關重要，特別是在使用不存在的 StorageClass 建立 PVC 時，如下圖所示：

按照以下步驟設定 RBAC 以實現錯誤訊息的可見性：

使用以下清單建立名為 harvesterhci.io:csi-driver 的新 clusterrole。

apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRole
metadata:
  labels:
    app.kubernetes.io/component: apiserver
    app.kubernetes.io/name: harvester
    app.kubernetes.io/part-of: harvester
  name: harvesterhci.io:csi-driver
rules:
- apiGroups:
  - storage.k8s.io
  resources:
  - storageclasses
  verbs:
  - get
  - list
  - watch

使用以下清單建立與上述 clusterrole 關聯的新 clusterrolebinding，並關聯相關的 serviceaccount。

apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRoleBinding
metadata:
  name: <namespace>-<serviceaccount name>
roleRef:
  apiGroup: rbac.authorization.k8s.io
  kind: ClusterRole
  name: harvesterhci.io:csi-driver
subjects:
- kind: ServiceAccount
  name: <serviceaccount name>
  namespace: <namespace>

確保 serviceaccount name 和 namespace 與您的 cloud provider 設定匹配。執行以下步驟以擷取這些詳細資訊。

找到與您的 cloud provider 關聯的 rolebinding：

$ kubectl get rolebinding -A |grep harvesterhci.io:cloudprovider
default                                 default-rke2-guest-01                                ClusterRole/harvesterhci.io:cloudprovider             7d1h

從此 rolebinding 擷取 subjects 資訊：

$ kubectl get rolebinding default-rke2-guest-01 -n default -o yaml |yq -e '.subjects'

識別 ServiceAccount 資訊：

- kind: ServiceAccount
  name: rke2-guest-01
  namespace: default

部署

現在您可以建立打算在客體 Kubernetes 叢集中使用的新 StorageClass。

對於管理員，您可以在裸機 Harvester 叢集中建立所需的 StorageClass（例如，名為 replica-2）。
然後，在客體 Kubernetes 叢集上，建立與 Harvester 叢集中名為 replica-2 的 StorageClass 關聯的新 StorageClass：
備註
- 選擇 Provisioner 時，選擇 Harvester (CSI)。Host StorageClass 參數應與在 Harvester 叢集上建立的 StorageClass 名稱匹配。
- 對於客體 Kubernetes 擁有者，您可以請求 Harvester 叢集管理員建立新的 StorageClass。
- 如果您將 Host StorageClass 欄位留空，將使用 Harvester 叢集的預設 StorageClass。
現在您可以基於這個新 StorageClass 建立 PVC，它利用 Host StorageClass 在裸機 Harvester 叢集上佈建磁碟區。

RWX 磁碟區支援

警告

RWX 磁碟區目前僅適用於專用儲存網路。GitHub issue #7218 追蹤將允許 RWX 磁碟區在客體叢集上使用各種 VLAN 的增強功能。

先決條件

主機叢集已安裝 Harvester v1.4 或更新版本。
Harvester 叢集上已設定儲存網路。使用 exclude 為客體叢集虛擬機器保留一個 IP 位址範圍。
已啟用嵌入式 Longhorn UI 上的 Storage Network for RWX Volume 設定。前往 General，然後選擇 Storage Network for RWX Volume Enabled。

您已在主機 Harvester 叢集上建立 RWX StorageClass。在 Storage Class: Create 畫面上，點擊 Edit as YAML 並指定以下內容：

kind: StorageClass
apiVersion: storage.k8s.io/v1
metadata:
  name: longhorn-rwx
provisioner: driver.longhorn.io
allowVolumeExpansion: true
reclaimPolicy: Delete
volumeBindingMode: Immediate
parameters:
  numberOfReplicas: "3"
  staleReplicaTimeout: "2880"
  fromBackup: ""
  fsType: "ext4"
  nfsOptions: "vers=4.2,noresvport,softerr,timeo=600,retrans=5"

角色型存取控制（RBAC）設定是最新的。 RBAC 授權使用特定的 Kubernetes API 群組來驅動有關存取電腦或網路資源的授權決策。

Harvester CSI driver 需要新的 RBAC 設定來支援 RWX 磁碟區。若要檢查 RBAC 設定，請執行命令 kubectl get clusterrole harvesterhci.io:csi-driver -o yaml。

# kubectl get clusterrole harvesterhci.io:csi-driver -o yaml
apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRole
metadata:
...
  name: harvesterhci.io:csi-driver
...
rules:
- apiGroups:
  - storage.k8s.io
  resources:
  - storageclasses
  verbs:
  - get
  - list
  - watch
- apiGroups:
  - harvesterhci.io
  resources:
  - networkfilesystems
  - networkfilesystems/status
  verbs:
  - '*'
- apiGroups:
  - longhorn.io
  resources:
  - volumes
  - volumes/status
  verbs:
  - get
  - list

networkfs-manager pod 正在執行。若要檢查 networkfs-manager pod 的狀態，請執行命令 kubectl get pods -n harvester-system | grep networkfs-manager。

範例：

# kubectl get pods -n harvester-system | grep networkfs-manager
harvester-networkfs-manager-2pxhm                       1/1     Running     4 (34m ago)    3h41m
harvester-networkfs-manager-8tst2                       1/1     Running     4 (37m ago)    3h41m
harvester-networkfs-manager-xvkgp                       1/1     Running     4 (37m ago)    3h41m

VM 必須有兩個介面。第一個是用於叢集/外部網路的預設網路介面。第二個必須在可以連接到儲存網路的網路中。 NAD default/vlan101 用於儲存網路。
Harvester CSI driver 版本為 v0.1.20 或更新版本。
客體叢集中的每個節點都已安裝 NFS 用戶端。執行以下任一命令以安裝 NFS 用戶端。
- Debian 和 Ubuntu：apt-get install -y nfs-common
- CentOS 和 RHEL：yum install -y nfs-utils
- SUSE 和 OpenSUSE：zypper install -y nfs-client
已手動為儲存網路介面指派 IP。您可以使用以下命令指派任何保留的 IP：
```
$ ip link set <storage network nic> up
$ ip a add <reserved IP> dev <storage network nic>
```
important
使用給定命令指派的 IP 在重新開機後不會保留。若要使 IP 持久化，您必須將其新增到客體作業系統的網路設定檔中。

使用方式

在客體叢集上建立新的 StorageClass。

在 StorageClass: Create 畫面上，新增 Host Storage Class 參數並指定您在主機 Harvester 叢集上建立的 RWX StorageClass。
建立 RWX PersistentVolumeClaim（PVC）。

在 PersistentVolumeClaim: Create 畫面上，設定以下設定：
- Volume Claim 標籤頁：指定新的 StorageClass。
- Customize 標籤頁：選擇 Many Nodes Read-Write。
驗證 RWX PVC 已成功建立。
建立兩個 pod。

在 Pod: Create 畫面上，指定 RWX PVC。

備註

您可以按照相同的步驟在客體叢集上建立 RWX PVC，然後在需要 RWX 磁碟區的 pod 上使用它。

線上磁碟區調整大小

如果底層儲存提供者支援線上磁碟區擴展，您可以在客體叢集中擴展 ReadWriteOnce（RWO）磁碟區，即使它已附加到正在執行的工作負載。

先決條件

Harvester v1.6 或更新版本
Harvester CSI Driver v0.1.24 或更新版本

升級 CSI Driver

升級 RKE2

若要升級 CSI driver，請使用 Rancher UI 升級 RKE2。確保新的 RKE2 版本支援/捆綁了更新的 CSI driver 版本。

前往 ☰ > Cluster Management。
找到您要升級的客體叢集，然後選擇 ⋮ > Edit Config。
選擇 Kubernetes Version。
點擊 Save。

升級 K3s

您可以使用 Rancher UI 升級 K3s。

前往 ☰ > K3s Cluster > Apps > Installed Apps。
找到 CSI driver chart，然後選擇 ⋮ > Edit/Upgrade。
選擇 Version。
選擇 Next > Update。

部署​

先決條件​

使用 Harvester RKE2 node driver 部署​

在 RKE2 叢集中手動安裝 CSI driver​

手動安裝的先決條件​

部署 Harvester CSI driver​

使用 Harvester K3s node driver 部署​

自訂預設 StorageClass​

透通自訂 StorageClass​

先決條件​

部署​

RWX 磁碟區支援​

先決條件​

使用方式​

線上磁碟區調整大小​

先決條件​

升級 CSI Driver​

升級 RKE2​

升級 K3s​

部署

先決條件

使用 Harvester RKE2 node driver 部署

在 RKE2 叢集中手動安裝 CSI driver

手動安裝的先決條件

部署 Harvester CSI driver

使用 Harvester K3s node driver 部署

自訂預設 StorageClass

透通自訂 StorageClass

先決條件

部署

RWX 磁碟區支援

先決條件

使用方式

線上磁碟區調整大小

先決條件

升級 CSI Driver

升級 RKE2

升級 K3s