你当前正在访问 Microsoft Azure Global Edition 技术文档网站。 如果需要访问由世纪互联运营的 Microsoft Azure 中国技术文档网站，请访问 https://docs.azure.cn。

在 Azure Kubernetes 服务 (AKS) 上从树内存储类迁移到 CSI 驱动程序

从版本 1.21 开始，Azure Kubernetes 服务 (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 服务 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 对象重新部署新应用程序时潜在的应用程序停机时间。

迁移

1. 运行以下命令，将现有 PV ReclaimPolicy 从“删除”更新为“保留”：

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

   将“pvName”替换为所选 PersistentVolume 的名称。 或者，如果要更新多个 PV 的 reclaimPolicy，请创建一个名为 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>。

2. 运行以下命令，获取命名空间中按 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，并且想要一次迁移几个 PV，则此步骤非常有用。 运行此命令可以确定在给定时间范围内创建了哪些 PVC。 运行 CreatePV.sh 脚本时，其中两个参数是开始时间和结束时间，使你能够仅在该时间段内迁移 PVC。

3. 创建一个名为 CreatePV.sh 的文件并将以下 YAML 复制到其中。 此脚本执行以下任务：

   • 为存储类 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
   

4. 若要为命名空间中的所有 PersistentVolumes 创建新的 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>
   

5. 更新应用程序以使用新 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"
  

1. 运行以下命令，获取特定命名空间中按 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，并且想要一次迁移几个 PV，则此步骤非常有用。 运行此命令可以确定在给定时间范围内创建了哪些 PVC。 运行 MigrateCSI.sh 脚本时，其中两个参数是开始时间和结束时间，使你能够仅在该时间段内迁移 PVC。

2. 创建一个名为 MigrateCSI.sh 的文件并将以下 YAML 复制到其中。 此脚本执行以下任务：

   • 使用 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
   

3. 若要迁移磁盘卷，请使用以下参数执行脚本 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>
   

4. 更新应用程序以使用新 PVC。

5. 手动删除较旧的资源，包括树内 PVC/PV、VolumeSnapshot 和 VolumeSnapshotContent。 否则，维护树内 PVC/PC 和快照对象会产生更多成本。

迁移文件共享卷

通过创建静态卷，可以从树内迁移到 CSI：

• 无需使用树内存储类清理原始配置。
• 风险低，因为仅执行 Kubernetes PV/PVC 的逻辑删除，不会删除实际的物理数据。
• 无额外费用，因为不需要创建额外的 Azure 对象，如文件共享等。

迁移

1. 运行以下命令，将现有 PV ReclaimPolicy 从“删除”更新为“保留”：

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

   将“pvName”替换为所选 PersistentVolume 的名称。 或者，如果要更新多个 PV 的 reclaimPolicy，请创建一个名为 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>。

2. 创建一个新的存储类并将预配器设置为 file.csi.azure.com，或者将其中一个默认 StorageClasses 与 CSI 文件预配器配合使用。

3. 通过运行以下命令，从现有 PersistentVolumes 中获取 secretName 和 shareName：

   kubectl describe pv pvName
   

4. 使用新的 StorageClass、shareName 和 secretName 从树内 PV 创建新的 PV。 创建一个名为 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
   

5. 使用以下代码创建一个名为 azurefile-mount-pvc.yaml 的文件，其中包含使用 PersistentVolumeClaim 的 PersistentVolume。

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

6. 使用 kubectl 命令创建 PersistentVolume。

   kubectl apply -f azurefile-mount-pv.yaml
   

7. 使用 kubectl 命令创建 PersistentVolumeClaim。

   kubectl apply -f azurefile-mount-pvc.yaml
   

8. 通过运行以下命令，验证 PersistentVolumeClaim 是否已创建并绑定到 PersistentVolume。

   kubectl get pvc azurefile
   

   输出如下所示：

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

9. 更新容器规范以引用 PersistentVolumeClaim并更新 Pod。 例如，复制以下代码并创建名为 azure-files-pod.yaml 的文件。

   ...
     volumes:
     - name: azure
       persistentVolumeClaim:
         claimName: azurefile
   

10. 无法及时更新 Pod 规范。 使用以下 kubectl 命令删除 Pod，然后再重新创建 Pod。

    kubectl delete pod mypod
    

    kubectl apply -f azure-files-pod.yaml
    

后续步骤

• 有关存储最佳做法的详细信息，请参阅有关 Azure Kubernetes 服务中存储和备份的最佳做法。
• 通过使用 Azure Backup for AKS 进行备份，保护新迁移的基于 CSI 驱动程序的 PV。