從樹狀內儲存體類別移轉至 Azure Kubernetes Service 上的 CSI 驅動程式 (AKS)

發行項
08/02/2024

從 1.21 版開始，Azure Kubernetes Service (AKS) 引進容器儲存體介面 (CSI) 驅動程式的實作。藉由採用 CSI 做為標準，您應該移轉或升級使用樹狀內永續性磁碟區 (PV) 的現有具狀態工作負載，以使用 CSI 驅動程式。

為了讓此流程盡可能簡單，並確保不會遺失任何資料，本文提供不同的移轉選項。這些選項包括指令碼，有助於確保從樹狀內順利移轉至 Azure 磁碟和 Azure 檔案服務 CSI 驅動程式。

開始之前

Azure CLI 版本 2.37.0 或更新版本。執行 az --version 以尋找版本，然後執行 az upgrade 以升級版本。如果您需要安裝或升級，請參閱安裝 Azure CLI。
Kubectl 和叢集系統管理員可以存取建立、取得、列出、刪除對 PVC 或 PV、磁碟區快照集或磁碟區快照集內容的存取權。針對已啟用 Microsoft Entra RBAC 的叢集，您是 Azure Kubernetes Service RBAC 叢集管理員角色的成員。

移轉磁碟區

注意

failure-domain.beta.kubernetes.io/zone 和 failure-domain.beta.kubernetes.io/region 標籤在 AKS 1.24 中已淘汰，並在 1.28 中移除。如果您的現有永續性磁碟區仍在使用符合這兩個標籤的 nodeAffinity，您必須在新的永續性磁碟區設定中將其變更為 topology.kubernetes.io/zone 和 topology.kubernetes.io/region 標籤。

使用兩個移轉選項支援從樹狀內移轉至 CSI：

建立靜態磁碟區
建立動態磁碟區

建立靜態磁碟區

使用此選項時，您會以靜態方式將 claimRef 指派給稍後建立的新 PVC 以建立 PV，並對於 PersistentVolumeClaim 指定 volumeName。

靜態磁碟區工作流程圖表。

此方法的優點包括：

很簡單而且可以自動化。
不需要使用樹狀結構內儲存類別清除原始組態。
低風險，因為您只會執行 Kubernetes PV/PVC 的邏輯刪除，所以不會刪除實際的實體資料。
由於不需要建立其他 Azure 物件，例如磁碟、快照集等，因此不會產生額外費用。

以下是評估的重要考量：

從原始動態樣式磁碟區轉換至靜態磁碟區，需要針對所有選項手動建構和管理 PV 物件。
重新部署參考新 PVC 物件的新應用程式時，會有潛在的應用程式停機時間。

遷移

執行下列命令，將現有的 PV ReclaimPolicy 從「刪除」更新為「保留」：

kubectl patch pv pvName -p '{"spec":{"persistentVolumeReclaimPolicy":"Retain"}}'

將 pvName 取代為您選取的 PersistentVolume 名稱。或者，如果您想要更新多個 PV 的回收原則，請建立名為 patchReclaimPVs.sh 的檔案，並在下列程式碼中複製。

#!/bin/bash
# Patch the Persistent Volume in case ReclaimPolicy is Delete
NAMESPACE=$1
i=1
for PVC in $(kubectl get pvc -n $NAMESPACE | awk '{ print $1}'); do
  # Ignore first record as it contains header
  if [ $i -eq 1 ]; then
    i=$((i + 1))
  else
    PV="$(kubectl get pvc $PVC -n $NAMESPACE -o jsonpath='{.spec.volumeName}')"
    RECLAIMPOLICY="$(kubectl get pv $PV -n $NAMESPACE -o jsonpath='{.spec.persistentVolumeReclaimPolicy}')"
    echo "Reclaim Policy for Persistent Volume $PV is $RECLAIMPOLICY"
    if [[ $RECLAIMPOLICY == "Delete" ]]; then
      echo "Updating ReclaimPolicy for $pv to Retain"
      kubectl patch pv $PV -p '{"spec":{"persistentVolumeReclaimPolicy":"Retain"}}'
    fi
  fi
done

使用 namespace 參數執行指令碼，以指定叢集命名空間 ./PatchReclaimPolicy.sh <namespace>。

執行下列命令，取得以 creationTimestamp 排序的命名空間中全部 PVC 的清單。使用 --namespace 引數以及實際的叢集命名空間來設定命名空間。
```
kubectl get pvc -n <namespace> --sort-by=.metadata.creationTimestamp -o custom-columns=NAME:.metadata.name,CreationTime:.metadata.creationTimestamp,StorageClass:.spec.storageClassName,Size:.spec.resources.requests.storage
```
如果您有大量需要移轉的 PV，而且您想要一次移轉一些，此步驟會很有幫助。執行此命令可讓您識別在指定時間範圍內建立哪些 PVC。您執行 CreatePV.sh 指令碼時，其中兩個參數是開始時間和結束時間，可讓您在該期間只移轉 PVC。

建立名為 CreatePV.sh 的檔案，然後在下列程式碼中複製。指令碼會執行下列作業：

在儲存體類別 storageClassName 的命名空間中，對於全部 PersistentVolume，以名稱 existing-pv-csi 建立新的 PersistentVolume。
將新的 PVC 名稱設定為 existing-pvc-csi。
使用您指定的 PV 名稱建立新的 PVC。

#!/bin/bash
#kubectl get pvc -n <namespace> --sort-by=.metadata.creationTimestamp -o custom-columns=NAME:.metadata.name,CreationTime:.metadata.creationTimestamp,StorageClass:.spec.storageClassName,Size:.spec.resources.requests.storage
# TimeFormat 2022-04-20T13:19:56Z
NAMESPACE=$1
FILENAME=$(date +%Y%m%d%H%M)-$NAMESPACE
EXISTING_STORAGE_CLASS=$2
STORAGE_CLASS_NEW=$3
STARTTIMESTAMP=$4
ENDTIMESTAMP=$5
i=1
for PVC in $(kubectl get pvc -n $NAMESPACE | awk '{ print $1}'); do
  # Ignore first record as it contains header
  if [ $i -eq 1 ]; then
    i=$((i + 1))
  else
    PVC_CREATION_TIME=$(kubectl get pvc  $PVC -n $NAMESPACE -o jsonpath='{.metadata.creationTimestamp}')
    if [[ $PVC_CREATION_TIME >= $STARTTIMESTAMP ]]; then
      if [[ $ENDTIMESTAMP > $PVC_CREATION_TIME ]]; then
        PV="$(kubectl get pvc $PVC -n $NAMESPACE -o jsonpath='{.spec.volumeName}')"
        RECLAIM_POLICY="$(kubectl get pv $PV -n $NAMESPACE -o jsonpath='{.spec.persistentVolumeReclaimPolicy}')"
        STORAGECLASS="$(kubectl get pv $PV -n $NAMESPACE -o jsonpath='{.spec.storageClassName}')"
        echo $PVC
        RECLAIM_POLICY="$(kubectl get pv $PV -n $NAMESPACE -o jsonpath='{.spec.persistentVolumeReclaimPolicy}')"
        if [[ $RECLAIM_POLICY == "Retain" ]]; then
          if [[ $STORAGECLASS == $EXISTING_STORAGE_CLASS ]]; then
            STORAGE_SIZE="$(kubectl get pv $PV -n $NAMESPACE -o jsonpath='{.spec.capacity.storage}')"
            SKU_NAME="$(kubectl get storageClass $STORAGE_CLASS_NEW -o jsonpath='{.parameters.skuname}')"
            DISK_URI="$(kubectl get pv $PV -n $NAMESPACE -o jsonpath='{.spec.azureDisk.diskURI}')"
            PERSISTENT_VOLUME_RECLAIM_POLICY="$(kubectl get pv $PV -n $NAMESPACE -o jsonpath='{.spec.persistentVolumeReclaimPolicy}')"

            cat >$PVC-csi.yaml <<EOF
    apiVersion: v1
    kind: PersistentVolume
    metadata:
      annotations:
        pv.kubernetes.io/provisioned-by: disk.csi.azure.com
      name: $PV-csi
    spec:
      accessModes:
      - ReadWriteOnce
      capacity:
        storage: $STORAGE_SIZE
      claimRef:
        apiVersion: v1
        kind: PersistentVolumeClaim
        name: $PVC-csi
        namespace: $NAMESPACE
      csi:
        driver: disk.csi.azure.com
        volumeAttributes:
          csi.storage.k8s.io/pv/name: $PV-csi
          csi.storage.k8s.io/pvc/name: $PVC-csi
          csi.storage.k8s.io/pvc/namespace: $NAMESPACE
          requestedsizegib: "$STORAGE_SIZE"
          skuname: $SKU_NAME
        volumeHandle: $DISK_URI
      persistentVolumeReclaimPolicy: $PERSISTENT_VOLUME_RECLAIM_POLICY
      storageClassName: $STORAGE_CLASS_NEW
---
apiVersion: v1
kind: PersistentVolumeClaim
metadata:
  name: $PVC-csi
  namespace: $NAMESPACE
spec:
  accessModes:
    - ReadWriteOnce
  storageClassName: $STORAGE_CLASS_NEW
  resources:
    requests:
      storage: $STORAGE_SIZE
  volumeName: $PV-csi
EOF
            kubectl apply -f $PVC-csi.yaml
            LINE="PVC:$PVC,PV:$PV,StorageClassTarget:$STORAGE_CLASS_NEW"
            printf '%s\n' "$LINE" >>$FILENAME
          fi
        fi
      fi
    fi
  fi
done

若要為命名空間中的全部 PersistentVolume 建立新的 PersistentVolume，請使用下列參數執行指令碼 CreatePV.sh：
- namespace - 叢集命名空間
- sourceStorageClass - 樹狀內儲存體驅動程式型 StorageClass
- targetCSIStorageClass - CSI 儲存體驅動程式型 StorageClass，這可以是其中一個預設儲存體類別，其佈建器設定為 disk.csi.azure.com 或 file.csi.azure.com。或者，只要這設定為這兩個佈建器的其中一個，您也可以建立自訂儲存體類別。
- startTimeStamp - 以 yyyy-mm-ddthh:mm:ssz 格式提供 PVC 建立時間之前的開始時間
- endTimeStamp - 以 yyyy-mm-ddthh:mm:ssz 格式提供結束日期。
```
./CreatePV.sh <namespace> <sourceIntreeStorageClass> <targetCSIStorageClass> <startTimestamp> <endTimestamp>
```
更新應用程式以使用新的 PVC。

建立動態磁碟區

您可以使用此選項，從永續性磁碟區宣告動態建立永續性磁碟區。

動態磁碟區工作流程圖表。

此方法的優點包括：

風險較低，因為所有新物件都會建立，同時保留具有快照集的其他複本。
不需要個別建構 PV，並在 PVC 資訊清單中新增磁碟區名稱。

以下是評估的重要考量：

雖然這種方法較不具風險，但是確實會建立多個物件，增加您的儲存體成本。
在建立新磁碟區期間，您的應用程式無法使用。
執行刪除步驟時應該小心謹慎。暫存資源鎖定可以套用於您的資源群組，直到移轉完成且您的應用程式已成功驗證為止。
從快照集建立新磁碟時，執行資料驗證/驗證。

遷移

在繼續之前，先確認下列事項︰

對於將資料寫入磁碟之前寫入記憶體的特定工作負載，應該停止應用程式，並允許記憶體內部資料排清到磁碟。

VolumeSnapshot 類別應該存在，如下列範例 YAML 所示：

apiVersion: snapshot.storage.k8s.io/v1
kind: VolumeSnapshotClass
metadata:
  name: custom-disk-snapshot-sc
driver: disk.csi.azure.com
deletionPolicy: Delete
parameters:
  incremental: "false"

執行下列命令，取得以 creationTimestamp 排序的指定命名空間中全部 PVC 的清單。使用 --namespace 引數以及實際的叢集命名空間來設定命名空間。
```
kubectl get pvc --namespace <namespace> --sort-by=.metadata.creationTimestamp -o custom-columns=NAME:.metadata.name,CreationTime:.metadata.creationTimestamp,StorageClass:.spec.storageClassName,Size:.spec.resources.requests.storage
```
如果您有大量需要移轉的 PV，而且您想要一次移轉一些，此步驟會很有幫助。執行此命令可讓您識別在指定時間範圍內建立哪些 PVC。您執行 MigrateCSI.sh 指令碼時，其中兩個參數是開始時間和結束時間，可讓您在該期間只移轉 PVC。

建立名為 MigrateToCSI.sh 的檔案，然後在下列程式碼中複製。指令碼會執行下列作業：

使用 Azure CLI 建立完整磁碟快照集
建立 VolumesnapshotContent
建立 VolumeSnapshot
從 VolumeSnapshot 建立新的 PVC
使用檔案名稱 <namespace>-timestamp 建立新檔案，其中包含需要清除的全部舊資源清單。

#!/bin/bash
#kubectl get pvc -n <namespace> --sort-by=.metadata.creationTimestamp -o custom-columns=NAME:.metadata.name,CreationTime:.metadata.creationTimestamp,StorageClass:.spec.storageClassName,Size:.spec.resources.requests.storage
# TimeFormat 2022-04-20T13:19:56Z
NAMESPACE=$1
FILENAME=$NAMESPACE-$(date +%Y%m%d%H%M)
EXISTING_STORAGE_CLASS=$2
STORAGE_CLASS_NEW=$3
VOLUME_STORAGE_CLASS=$4
START_TIME_STAMP=$5
END_TIME_STAMP=$6
i=1
for PVC in $(kubectl get pvc -n $NAMESPACE | awk '{ print $1}'); do
  # Ignore first record as it contains header
  if [ $i -eq 1 ]; then
    i=$((i + 1))
  else
    PVC_CREATION_TIME=$(kubectl get pvc $PVC -n $NAMESPACE -o jsonpath='{.metadata.creationTimestamp}')
    if [[ $PVC_CREATION_TIME > $START_TIME_STAMP ]]; then
      if [[ $END_TIME_STAMP > $PVC_CREATION_TIME ]]; then
        PV="$(kubectl get pvc $PVC -n $NAMESPACE -o jsonpath='{.spec.volumeName}')"
        RECLAIM_POLICY="$(kubectl get pv $PV -n $NAMESPACE -o jsonpath='{.spec.persistentVolumeReclaimPolicy}')"
        STORAGE_CLASS="$(kubectl get pv $PV -n $NAMESPACE -o jsonpath='{.spec.storageClassName}')"
        echo $PVC
        RECLAIM_POLICY="$(kubectl get pv $PV -n $NAMESPACE -o jsonpath='{.spec.persistentVolumeReclaimPolicy}')"
        if [[ $STORAGE_CLASS == $EXISTING_STORAGE_CLASS ]]; then
          STORAGE_SIZE="$(kubectl get pv $PV -n $NAMESPACE -o jsonpath='{.spec.capacity.storage}')"
          SKU_NAME="$(kubectl get storageClass $STORAGE_CLASS_NEW -o jsonpath='{.parameters.skuname}')"
          DISK_URI="$(kubectl get pv $PV -n $NAMESPACE -o jsonpath='{.spec.azureDisk.diskURI}')"
          TARGET_RESOURCE_GROUP="$(cut -d'/' -f5 <<<"$DISK_URI")"
          echo $DISK_URI
          SUBSCRIPTION_ID="$(echo $DISK_URI | grep -o 'subscriptions/[^/]*' | sed 's#subscriptions/##g')"
          echo $TARGET_RESOURCE_GROUP
          PERSISTENT_VOLUME_RECLAIM_POLICY="$(kubectl get pv $PV -n $NAMESPACE -o jsonpath='{.spec.persistentVolumeReclaimPolicy}')"
          az snapshot create --resource-group $TARGET_RESOURCE_GROUP --name $PVC-$FILENAME --source "$DISK_URI" --subscription ${SUBSCRIPTION_ID}
          SNAPSHOT_PATH=$(az snapshot list --resource-group $TARGET_RESOURCE_GROUP --query "[?name == '$PVC-$FILENAME'].id | [0]" --subscription ${SUBSCRIPTION_ID})
          SNAPSHOT_HANDLE=$(echo "$SNAPSHOT_PATH" | tr -d '"')
          echo $SNAPSHOT_HANDLE
          sleep 10
          # Create Restore File
          cat <<EOF >$PVC-csi.yml
    apiVersion: snapshot.storage.k8s.io/v1
    kind: VolumeSnapshotContent
    metadata:
      name: $PVC-$FILENAME
    spec:
      deletionPolicy: 'Delete'
      driver: 'disk.csi.azure.com'
      volumeSnapshotClassName: $VOLUME_STORAGE_CLASS
      source:
        snapshotHandle: $SNAPSHOT_HANDLE
      volumeSnapshotRef:
        apiVersion: snapshot.storage.k8s.io/v1
        kind: VolumeSnapshot
        name: $PVC-$FILENAME
        namespace: $1
---
    apiVersion: snapshot.storage.k8s.io/v1
    kind: VolumeSnapshot
    metadata:
      name: $PVC-$FILENAME
      namespace: $1
    spec:
      volumeSnapshotClassName: $VOLUME_STORAGE_CLASS
      source:
        volumeSnapshotContentName: $PVC-$FILENAME
---
    apiVersion: v1
    kind: PersistentVolumeClaim
    metadata:
      name: csi-$PVC
      namespace: $1
    spec:
      accessModes:
      - ReadWriteOnce
      storageClassName: $STORAGE_CLASS_NEW
      resources:
        requests:
          storage: $STORAGE_SIZE
      dataSource:
        name: $PVC-$FILENAME
        kind: VolumeSnapshot
        apiGroup: snapshot.storage.k8s.io

EOF
          kubectl create -f $PVC-csi.yml
          LINE="OLDPVC:$PVC,OLDPV:$PV,VolumeSnapshotContent:volumeSnapshotContent-$FILENAME,VolumeSnapshot:volumesnapshot$FILENAME,OLDdisk:$DISK_URI"
          printf '%s\n' "$LINE" >>$FILENAME
        fi
      fi
    fi
  fi
done

若要移轉磁碟區，請使用下列參數執行指令碼 MigrateToCSI.sh：
- namespace - 叢集命名空間
- sourceStorageClass - 樹狀內儲存體驅動程式型 StorageClass
- targetCSIStorageClass - CSI 儲存體驅動程式型 StorageClass
- volumeSnapshotClass - 磁碟區快照集類別的名稱。例如： custom-disk-snapshot-sc 。
- startTimeStamp - 以 yyyy-mm-ddthh:mm:ssz 格式提供開始時間。
- endTimeStamp - 以 yyyy-mm-ddthh:mm:ssz 格式提供結束日期。
```
./MigrateToCSI.sh <namespace> <sourceStorageClass> <TargetCSIstorageClass> <VolumeSnapshotClass> <startTimestamp> <endTimestamp>
```
更新應用程式以使用新的 PVC。
手動刪除較舊的資源，包括樹狀內 PVC/PV、VolumeSnapshot 和 VolumeSnapshotContent。否則，維護樹狀結構內 PVC/PC 和快照集物件會產生更多成本。

建立靜態磁碟區支援從樹狀內移轉至 CSI：

不需要使用樹狀結構內儲存類別清除原始組態。
低風險，因為您只會執行 Kubernetes PV/PVC 的邏輯刪除，所以不會刪除實際的實體資料。
由於不需要建立其他 Azure 物件，例如檔案共用等，因此不會產生額外費用。

遷移

執行下列命令，將現有的 PV ReclaimPolicy 從「刪除」更新為「保留」：

kubectl patch pv pvName -p '{"spec":{"persistentVolumeReclaimPolicy":"Retain"}}'

#!/bin/bash
# Patch the Persistent Volume in case ReclaimPolicy is Delete
namespace=$1
i=1
for pvc in $(kubectl get pvc -n $namespace | awk '{ print $1}'); do
  # Ignore first record as it contains header
  if [ $i -eq 1 ]; then
    i=$((i + 1))
  else
    pv="$(kubectl get pvc $pvc -n $namespace -o jsonpath='{.spec.volumeName}')"
    reclaimPolicy="$(kubectl get pv $pv -n $namespace -o jsonpath='{.spec.persistentVolumeReclaimPolicy}')"
    echo "Reclaim Policy for Persistent Volume $pv is $reclaimPolicy"
    if [[ $reclaimPolicy == "Delete" ]]; then
      echo "Updating ReclaimPolicy for $pv to Retain"
      kubectl patch pv $pv -p '{"spec":{"persistentVolumeReclaimPolicy":"Retain"}}'
    fi
  fi
done

使用 namespace 參數執行指令碼，以指定叢集命名空間 ./PatchReclaimPolicy.sh <namespace>。

建立新的儲存體類別，並將佈建程式設定為 file.csi.azure.com，或者您可以使用其中一個預設 StorageClass 搭配 CSI 檔案佈建器。
執行下列命令，從現有的 PersistentVolumes 取得 secretName 和 shareName：
```
kubectl describe pv pvName
```

使用新的 StorageClass 建立新的 PV，並從樹狀內 PV 建立 shareName 和 secretName。建立名為 azurefile-mount-pv.yaml 的檔案，並在下列程式碼中複製。在 csi 之下，更新 resourceGroup、volumeHandle 和 shareName。針對掛接選項，fileMode 和 dirMode 的預設值為 0777。

fileMode 和 dirMode 的預設值為 0777。

apiVersion: v1
kind: PersistentVolume
metadata:
  annotations:
    pv.kubernetes.io/provisioned-by: file.csi.azure.com
  name: azurefile
spec:
  capacity:
    storage: 5Gi
  accessModes:
    - ReadWriteMany
  persistentVolumeReclaimPolicy: Retain
  storageClassName: azurefile-csi
  csi:
    driver: file.csi.azure.com
    readOnly: false
    volumeHandle: unique-volumeid  # make sure volumeid is unique for every identical share in the cluster
    volumeAttributes:
      resourceGroup: EXISTING_RESOURCE_GROUP_NAME  # optional, only set this when storage account is not in the same resource group as the cluster nodes
      shareName: aksshare
    nodeStageSecretRef:
      name: azure-secret
      namespace: default
  mountOptions:
    - dir_mode=0777
    - file_mode=0777
    - uid=0
    - gid=0
    - mfsymlinks
    - cache=strict
    - nosharesock
    - nobrl  # disable sending byte range lock requests to the server and for applications which have challenges with posix locks

使用下列程式碼，藉由使用 PersistentVolume 的 PersistentVolumeClaim 建立名為 azurefile-mount-pvc.yaml 的檔案。

apiVersion: v1
kind: PersistentVolumeClaim
metadata:
  name: azurefile
spec:
  accessModes:
    - ReadWriteMany
  storageClassName: azurefile-csi
  volumeName: azurefile
  resources:
    requests:
      storage: 5Gi

使用 kubectl 命令建立 PersistentVolume。
```
kubectl apply -f azurefile-mount-pv.yaml
```
使用 kubectl 命令建立 PersistentVolumeClaim。
```
kubectl apply -f azurefile-mount-pvc.yaml
```

若要驗證 PersistentVolumeClaim 已建立並繫結至 PersistentVolume，請執行下列命令。

kubectl get pvc azurefile

輸出類似下列：

NAME        STATUS   VOLUME      CAPACITY   ACCESS MODES   STORAGECLASS   AGE
azurefile   Bound    azurefile   5Gi        RWX            azurefile      5s

將您的容器規格更新為參考 PersistentVolumeClaim 並更新 Pod。例如，複製下列程式碼，並建立名為 azure-files-pod.yaml 的檔案。
```
...
  volumes:
  - name: azure
    persistentVolumeClaim:
      claimName: azurefile
```
Pod 規格無法就地更新。使用下列 kubectl 命令刪除，然後重新建立 Pod。
```
kubectl delete pod mypod
```
```
kubectl apply -f azure-files-pod.yaml
```

下一步

如需儲存體最佳做法的詳細資訊，請參閱 Azure Kubernetes Service 中的儲存體和備份最佳做法。
使用適用於 AKS 的 Azure 備份進行備份，以保護新移轉的 CSI 驅動程式型 PV。

共用方式為

從樹狀內儲存體類別移轉至 Azure Kubernetes Service 上的 CSI 驅動程式 (AKS)

開始之前

移轉磁碟區

建立靜態磁碟區

遷移

建立動態磁碟區

遷移

遷移

下一步

其他資源

共用方式為

從樹狀內儲存體類別移轉至 Azure Kubernetes Service 上的 CSI 驅動程式 (AKS)

開始之前

移轉磁碟區

建立靜態磁碟區

遷移

建立動態磁碟區

遷移

移轉檔案共用磁碟區

遷移

下一步

其他資源