如何使用FlexVolume2CSI命令列工具批量轉換YAML - Container Service for Kubernetes

FlexVolume2CSI命令列工具可以幫您批量轉換FlexVolume叢集中儲存卷、通過inline方式使用儲存（即內聯儲存卷）的工作負載的YAML，協助您更便捷地由FlexVolume叢集切換至CSI叢集。本文介紹如何在FlexVolume叢集中使用FlexVolume2CSI命令列工具批量轉換YAML。

實現原理

FlexVolume2CSI工具將列出叢集內所有或指定命名空間內的所有或指定的儲存卷或工作負載資源，將標準FlexVolume欄位內容轉譯為對應CSI內容，並將YAML列印至檔案中，以便部署。

重要

轉換處理僅支援處理相對標準的NAS、OSS、阿里雲雲端硬碟類型的PV、PVC或工作負載的inline Volume，建議您在部署前再次檢查產生CSI的相關資源YAML。

步驟一：安裝FlexVolume2CSI命令列工具

執行以下命令，安裝FlexVolume2CSI。

支援macOS和Linux系統安裝。

curl https://ack-csiplugin.oss-cn-hangzhou.aliyuncs.com/flexvolume2csi/get-translator.sh | bash

執行以下命令，驗證FlexVolume2CSI是否安裝成功。

flexvolume2csi version

預期輸出：

flexvolume2csi: v2.0.1+fb3f6ea
  BuildDate: 2025-12-29T11:17:39Z
  GitCommit: fb3f6eaa300e095053c0eabc8943c678534d4805
  GitTreeState: clean
  GoVersion: go1.24.5
  Compiler: gc
  Platform: darwin/arm64

預期輸出表明，FlexVolume2CSI命令列工具已安裝成功。

步驟二：為FlexVolume2CSI配置叢集資訊

執行以下命令，配置FlexVolume2CSI的叢集資訊。

flexvolume2csi configure

預期輸出：

Configuring profile 'default' ...
Default Cluster Id (ClusterId of ACK Flexvolume Cluster) [c4869a2f603ca4e74****************]:
Default Kubeconfig Path (default is ~/.kube/config) []:
Saving profile[default] ...
Done.

參數	說明
Cluster Id	Flexvolume叢集的Cluster ID。
Kubeconfig Path	Flexvolume叢集的KubeConfig路徑，預設為~/.kube/config。

步驟三：產生Flexvolume PV和PVC對應的CSI YAML檔案

選擇性參數

執行以下命令，查詢FlexVolume2CSI支援的可選配置項。

flexvolume2csi translate help

預期輸出：

Translate standalone PVC and PV resources from FlexVolume to CSI format

Usage:
  flexvolume2csi translate [-n namespace] [-c pvc] [-o outputfile] [-p prefix] [-s suffix] [-b backupfile] [-t storageclass] [flags]

Examples:
  # Translate PVCs and related PVs in all namespaces
  flexvolume2csi translate -o output.txt

  # Translate PVCs and related PVs in default namespace
  flexvolume2csi translate -n default -o output.txt

  # Translate PVC test-pvc and related PV in default namespace
  flexvolume2csi translate -n default -p test-pvc -o output.txt


Flags:
  -b, --backupfile string     path to backup (flexvolume) file (default "./backupfile.txt")
  -h, --help                  help for translate
  -n, --namespace string      specified namespace
  -o, --outputfile string     path to output (CSI) file (default "./outputfile.txt")
  -p, --prefix string         change pv/pvc name to prefix-xxx
  -c, --pvc string            specified pvc
  -t, --storageclass string   change storageclass name
  -s, --suffix string         change pv/pvc name to xxx-suffix

選擇性參數	說明
`-o`	產生的CSI的PV和PVC的YAML檔案地址，預設為當前路徑下的`outputfile.txt`。傳空值時列印至標準輸出。
`-b`	備份原FlexVolume的PV和PVC的YAML檔案地址，預設為當前路徑下的`backupfile.txt`。傳空值時不備份。
`-n`	指定命名空間名稱，僅處理該命名空間下的PV和PVC，預設為所有命名空間。
`-c`	指定PVC名稱，僅處理該PVC及其對應的PV，需要配合`-n`參數使用。預設為選中命名空間的所有PV和PVC。
`-p`	產生的CSI的PV和PVC名稱的統一首碼，預設無首碼。如原FlexVolume的PVC名稱為pvc-test，加上-p csi後，CSI對應的PVC名稱為csi-pvc-test。
`-s`	產生的CSI的PV和PVC名稱的統一尾碼，預設無尾碼。如原FlexVolume的PVC名稱為pvc-test，加上-s csi後，CSI對應的PVC名稱為pvc-test-csi。

操作樣本

使用以下內容，在FlexVolume叢集中建立pv.yaml檔案。

apiVersion: v1
kind: PersistentVolume
metadata:
  name: pv-nas
spec:
  capacity:
    storage: 5Gi
  storageClassName: nas
  accessModes:
    - ReadWriteMany
  flexVolume:
    driver: "alicloud/nas"
    options:
      server: "0cd8b4a576-u****.cn-hangzhou.nas.aliyuncs.com" #替換為您隱藏檔的掛載點地址。
      path: "/k8s"
      vers: "3"
      options: "nolock,tcp,noresvport"

執行以下命令，在FlexVolume叢集中部署樣本PV。
```
kubectl apply -f pv.yaml
```

使用以下內容，在FlexVolume叢集中建立pvc.yaml檔案。

apiVersion: v1
kind: PersistentVolumeClaim
metadata:
  name: pvc-nas
spec:
  accessModes:
    - ReadWriteMany
  storageClassName: nas
  resources:
    requests:
      storage: 5Gi

執行以下命令，在FlexVolume叢集中部署樣本PVC。
```
kubectl apply -f pvc.yaml
```

執行以下命令，確認PV和PVC處於Bound狀態。

kubectl get pvc | grep pvc-nas

預期輸出：

pvc-nas   Bound    pv-nas   5Gi       RWO            nas       10s

執行以下命令，使用FlexVolume2CSI命令列工具，轉換叢集內的所有PV和PVC的YAML檔案。
重要
FlexVolume類型的PVC和PV資源無法簡單通過kubectl apply等命令訂正為CSI類型，需重新部署。完整的遷移流程，請參見遷移Flexvolume至CSI中的相關情境文檔。
如需通過csi-compatible-controller組件實現FlexVolume與CSI類型PVC和PV資源的短暫共存，需通過-p或-s參數以避免資源重名衝突。
```
flexvolume2csi translate -s csi
```

執行以下命令，查看輸出的CSI的PV和PVC的YAML檔案。

cat ./outputfile.yaml

預期輸出：

---

apiVersion: v1
kind: PersistentVolume
metadata:
  labels:
    alicloud-pvname: pv-nas-csi
  name: pv-nas-csi
spec:
  accessModes:
  - ReadWriteMany
  capacity:
    storage: 5Gi
  csi:
    driver: nasplugin.csi.alibabacloud.com
    volumeAttributes:
      path: /k8s
      server: 0cd8b4a576-u****.cn-hangzhou.nas.aliyuncs.com
    volumeHandle: pv-nas-csi
  mountOptions:
  - nolock,tcp,noresvport
  - vers=3
  persistentVolumeReclaimPolicy: Retain
  storageClassName: nas
  volumeMode: Filesystem

---

apiVersion: v1
kind: PersistentVolumeClaim
metadata:
  name: pvc-nas-csi
  namespace: default
spec:
  accessModes:
  - ReadWriteMany
  resources:
    requests:
      storage: 5Gi
  selector:
    matchLabels:
      alicloud-pvname: pv-nas-csi
  storageClassName: nas
  volumeMode: Filesystem
  volumeName: pv-nas-csi

預期輸出表明，已成功產生PV和PVC對應的CSI YAML檔案。

（可選）步驟四：產生帶有inline FlexVolume儲存的工作負載對應的CSI YAML檔案

早期的ACK託管叢集、ACK Serverless叢集支援通過inline方式為叢集的工作負載掛載FlexVolume儲存。若您的叢集中正在運行此類工作負載，同樣需要對其YAML進行轉換。

inline掛載方式不需要對應的PVC與PV資源，一個以inline方式掛載了FlexVolume儲存的有狀態應用YAML如下所示：

apiVersion: apps/v1
kind: StatefulSet
metadata:
  name: nginx
spec:
  serviceName: nginx
  replicas: 1
  selector:
    matchLabels:
      app: nginx
  template:
    metadata:
      labels:
        app: nginx
    spec:
      containers:
      - name: nginx
        image: anolis-registry.cn-zhangjiakou.cr.aliyuncs.com/openanolis/nginx:1.14.1-8.6
        volumeMounts:
        - name: test
          mountPath: /data
        ports:
        - containerPort: 80
      volumes:
      - name: test
        flexVolume:
          driver: "alicloud/disk"
          fsType: "ext4"
          options:
            volumeId: "d-bp1f3b5d0b0a8e7e6f****"
  volumeClaimTemplates:
  - metadata:
      name: disk-ssd
    spec:
      accessModes: [ "ReadWriteOnce" ]
      storageClassName: "alicloud-disk-ssd"
      resources:
        requests:
          storage: 20Gi

其中名為test的volume即以inline方式掛載的FlexVolume雲端硬碟儲存。

說明

volumeClaimTemplates中的儲存實際會由控制器以動態方式自動建立相關的PVC與PV資源。由此產生的PVC與PV資源，可由步驟三實現至CSI的轉換。

若您期望用控制器重新建立CSI的PVC與PV資源，可刪除相關FlexVolume的PVC與PV資源後（刪除前請您確認資料已不再需要），修改volumeClaimTemplates中的storageClassName欄位的值為CSI儲存類實現。

轉換目標

以inline方式掛載的FlexVolume儲存卷在轉換時：

無指定volumeId的雲端硬碟儲存卷將轉換為inline方式臨時卷。
其餘類型的儲存卷將轉換為獨立PVC、PV形式的CSI儲存卷。產生的CSI YAML檔案將同時包括PV、PVC及原工作負載資源。

選擇性參數

執行以下命令，查詢FlexVolume2CSI支援的可選配置項。

flexvolume2csi inline-translate help

預期輸出：

Translate inline storage volumes in workloads to standalone CSI PVC and PV resources

Usage:
  flexvolume2csi inline-translate [-n namespace] [-k kind] [-i item] [-f inputfile] [-o outputfile] [-b backupfile] [-t storageclass] [-c capacity] [flags]

Examples:
  # Translate inline FlexVolume Volumes for ALL kinds of workloads (like StatefulSets, Deployments ...) in all namespaces
  # Note1: Pods will not be translated when Kind of workload is not specified, please use "-k pod" if need.
  # Note2: VolumeClaimTemplates will not be translated for StatefulSets, please modified the field \"storageClassName\" by hand.
  flexvolume2csi inline-translate -o output.txt

  # Translate inline FlexVolume Volumes for ALL kinds of workloads (like StatefulSets, Deployments ...) in default namespace 
  flexvolume2csi inline-translate -n default -o output.txt

  # Translate inline FlexVolume Volumes for StatefulSets in default namespace
  flexvolume2csi inline-translate -n default -k sts -o output.txt

  # Translate inline FlexVolume Volumes for StatefulSets test-sts in default namespace
  flexvolume2csi inline-translate -n default -k sts -i test-sts -o output.txt

  # Translate inline FlexVolume Volumes for every Item in the input file with "---\n" to separate items
  flexvolume2csi inline-translate -i input.txt -o output.txt

}



Flags:
  -b, --backupfile string     path to backup (flexvolume) file (default "./backupfile.txt")
  -c, --capacity string       change capacity
  -h, --help                  help for inline-translate
  -f, --inputfile string      path to input (flexvolume) file
  -i, --item string           specified item name
  -n, --namespace string      specified namespace
  -o, --outputfile string     path to output (CSI) file (default "./outputfile.txt")
  -t, --storageclass string   change storageclass name
  -k, --sts string            specified kind for workloads

選擇性參數	說明
`-o`	產生的CSI的YAML檔案地址，預設為當前路徑下的`outputfile.txt`。傳空值時列印至標準輸出。
`-b`	備份使用FlexVolume儲存的工作負載YAML檔案地址，預設為當前路徑下的`backupfile.txt`。傳空值時不備份。
`-n`	指定命名空間名稱，僅處理該命名空間下使用了FlexVolume儲存的工作負載，預設為所有命名空間。
`-k`	指定工作負載類型，如StatefulSet、Deployment等，僅處理指定類型的掛載了FlexVolume儲存的工作負載，預設為所有類型的工作負載。
`-i`	指定工作負載名稱，僅處理該工作負載，需要配合`-n`和`-k`參數使用。
`-f`	從指定的YAML檔案地址中讀取工作負載資源並轉換，不再從叢集中列舉工作負載。不支援同時配置`-n`、`-k`及`-i`參數。

操作樣本

將未指定`volumeId`的雲端硬碟儲存轉換為臨時卷

使用以下內容，在FlexVolume叢集中建立工作負載。

apiVersion: apps/v1
kind: Deployment
metadata:
  name: nginx
spec:
  selector:
    matchLabels:
      app: nginx
  template:
    metadata:
      labels:
        app: nginx
    spec:
      containers:
      - name: nginx
        image: anolis-registry.cn-zhangjiakou.cr.aliyuncs.com/openanolis/nginx:1.14.1-8.6
        volumeMounts:
        - name: test
          mountPath: /data
        ports:
        - containerPort: 80
      volumes:
      - name: test
        flexVolume:
          driver: "alicloud/disk"
          fsType: "ext4"
          options:
            volumeSize: "20"

執行以下命令，使用FlexVolume2CSI命令列工具，轉換部署的工作負載。
```
flexvolume2csi inline-translate -k deploy -n default -i nginx 
```

執行以下命令，查看輸出的CSI的PV和PVC的YAML檔案。

cat ./outputfile.yaml

預期輸出：

---
apiVersion: apps/v1
kind: Deployment
metadata:
  name: nginx
  namespace: default
spec:
  progressDeadlineSeconds: 600
  replicas: 1
  revisionHistoryLimit: 10
  selector:
    matchLabels:
      app: nginx
  strategy:
    rollingUpdate:
      maxSurge: 25%
      maxUnavailable: 25%
    type: RollingUpdate
  template:
    metadata:
      labels:
        app: nginx
    spec:
      containers:
      - image: anolis-registry.cn-zhangjiakou.cr.aliyuncs.com/openanolis/nginx:1.14.1-8.6
        imagePullPolicy: IfNotPresent
        name: nginx
        ports:
        - containerPort: 80
          protocol: TCP
        resources: {}
        terminationMessagePath: /dev/termination-log
        terminationMessagePolicy: File
        volumeMounts:
        - mountPath: /data
          name: test
      dnsPolicy: ClusterFirst
      restartPolicy: Always
      schedulerName: default-scheduler
      securityContext: {}
      terminationGracePeriodSeconds: 30
      volumes:
      - ephemeral:
          volumeClaimTemplate:
            metadata:
            spec:
              accessModes:
              - ReadWriteOnce
              resources:
                requests:
                  storage: 20Gi
        name: test

可見，inline的FlexVolume儲存轉換成對應的臨時卷儲存。

根據實際情況調整產生的YAML內容，轉換成臨時卷儲存時，通常需要修改：

ephemeral中需指定臨時儲存類，調整後

      volumes:
      - ephemeral:
          volumeClaimTemplate:
            metadata:
            spec:
              accessModes:
              - ReadWriteOnce
              resources:
                requests:
                  storage: 20Gi
              storageClassName: ephemeral-disk

以上修改也可以通過在轉換時指定-t和-c參數實現，對所有資源均生效。

flexvolume2csi inline-translate -k deploy -n default -i nginx -t ephemeral-disk

將其他類型的儲存轉換為CSI儲存卷

本樣本展示通過-f參數指定需要轉換的YAML內容。

將本步驟開頭展示的有狀態應用YAML儲存為disk-static-sts.yaml檔案。
執行以下命令，使用FlexVolume2CSI命令列工具，轉換檔內描述的有狀態應用。
```
flexvolume2csi inline-translate -f disk-static-sts.yaml
```

執行以下命令，查看轉換的有狀態應用YAML檔案。

cat ./outputfile.txt

預期輸出：

---
apiVersion: v1
kind: PersistentVolume
metadata:
  name: d-bp1f3b5d0b0a8e7e6f****
spec:
  accessModes:
  - ReadWriteOnce
  claimRef:
    kind: PersistentVolumeClaim
    name: sts-nginx-test
    namespace: default
  csi:
    driver: diskplugin.csi.alibabacloud.com
    fsType: ext4
    volumeAttributes:
      volumeId: d-bp1f3b5d0b0a8e7e6f****
    volumeHandle: d-bp1f3b5d0b0a8e7e6f****
  persistentVolumeReclaimPolicy: Delete

---
apiVersion: v1
kind: PersistentVolumeClaim
metadata:
  name: sts-nginx-test
  namespace: default
spec:
  accessModes:
  - ReadWriteOnce
  resources: {}
  volumeName: d-bp1f3b5d0b0a8e7e6f****

---
apiVersion: apps/v1
kind: StatefulSet
metadata:
  name: nginx
  namespace: default
spec:
  replicas: 1
  selector:
    matchLabels:
      app: nginx
  serviceName: nginx
  template:
    metadata:
      labels:
        app: nginx
    spec:
      containers:
      - image: anolis-registry.cn-zhangjiakou.cr.aliyuncs.com/openanolis/nginx:1.14.1-8.6
        name: nginx
        ports:
        - containerPort: 80
        resources: {}
        volumeMounts:
        - mountPath: /data
          name: test
      volumes:
      - name: test
        persistentVolumeClaim:
          claimName: sts-nginx-test
  updateStrategy: {}
  volumeClaimTemplates:
  - metadata:
      name: disk-ssd
    spec:
      accessModes: [ "ReadWriteOnce" ]
      storageClassName: "alicloud-disk-ssd"
      resources:
        requests:
          storage: 20Gi

可見，inline的FlexVolume儲存轉換成對應的CSI PVC與PV，且在有狀態應用中對應的volume類型轉換為對CSI PVC的引用。此外，volumeClaimTemplates中的內容未發生更改。

根據實際情況調整產生的YAML內容，轉換成CSI儲存類時，通常需要修改：

CSI PVC與PV聲明所需的儲存容量，假設需要20Gi，調整後為：

---
apiVersion: v1
kind: PersistentVolume
metadata:
  name: d-bp1f3b5d0b0a8e7e6f****
spec:
  accessModes:
  - ReadWriteOnce
  capacity:
    storage: 20Gi
  claimRef:
    kind: PersistentVolumeClaim
    name: sts-nginx-test
    namespace: default
  csi:
    driver: diskplugin.csi.alibabacloud.com
    fsType: ext4
    volumeAttributes:
      volumeId: d-bp1f3b5d0b0a8e7e6f****
    volumeHandle: d-bp1f3b5d0b0a8e7e6f****
  persistentVolumeReclaimPolicy: Delete

---
apiVersion: v1
kind: PersistentVolumeClaim
metadata:
  name: sts-nginx-test
  namespace: default
spec:
  accessModes:
  - ReadWriteOnce
  resources:
    requests:
      storage: 20Gi
  volumeName: d-bp1f3b5d0b0a8e7e6f****

volumeClaimTemplates中指定的儲存類需調整為CSI類，直接修改欄位的值即可。

以上修改也可以通過在轉換時指定-t和-c參數實現，對所有資源均生效。

flexvolume2csi inline-translate -f disk-static-sts.yaml -t <csi-storageclass> -c "20Gi"

步驟五：檢查並部署產生的CSI YAML

FlexVolume2CSI僅負責產生YAML檔案。請在確認YAML內容無誤後將其手動部署到叢集中，完整的遷移操作流程，可參見遷移Flexvolume至CSI中的相關情境文檔。

為避免PVC和PV資源重名衝突，建議在部署時使用kubectl create -f命令。

Container Service for Kubernetes：使用FlexVolume2CSI命令列工具批量轉換YAML

實現原理

步驟一：安裝FlexVolume2CSI命令列工具

步驟二：為FlexVolume2CSI配置叢集資訊

步驟三：產生Flexvolume PV和PVC對應的CSI YAML檔案

選擇性參數

操作樣本

（可選）步驟四：產生帶有inline FlexVolume儲存的工作負載對應的CSI YAML檔案

轉換目標

選擇性參數

操作樣本

將未指定`volumeId`的雲端硬碟儲存轉換為臨時卷

將其他類型的儲存轉換為CSI儲存卷

步驟五：檢查並部署產生的CSI YAML

相關文檔

實現原理

步驟一：安裝FlexVolume2CSI命令列工具

步驟二：為FlexVolume2CSI配置叢集資訊

步驟三：產生Flexvolume PV和PVC對應的CSI YAML檔案

選擇性參數

操作樣本

（可選）步驟四：產生帶有inline FlexVolume儲存的工作負載對應的CSI YAML檔案

轉換目標

選擇性參數

操作樣本

將未指定volumeId的雲端硬碟儲存轉換為臨時卷

將其他類型的儲存轉換為CSI儲存卷

步驟五：檢查並部署產生的CSI YAML

相關文檔

將未指定`volumeId`的雲端硬碟儲存轉換為臨時卷