Batch convert YAML with the FlexVolume2CSI CLI

How it works

FlexVolume2CSI lists volume and workload resources in a cluster or namespace, translates FlexVolume fields to CSI format, and writes the resulting YAML to a file.

Step 1: Install the FlexVolume2CSI CLI

1. Install the FlexVolume2CSI CLI.

   Supported on macOS and Linux.

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

2. Verify the installation.

   flexvolume2csi version

   Expected output:

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

   This confirms a successful installation.

Step 2: Configure the FlexVolume2CSI CLI

1. Configure cluster information.

   flexvolume2csi configure

   Expected output:

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

   Parameter	Description
   Cluster Id	The ID of the FlexVolume cluster.
   Kubeconfig Path	The kubeconfig file path for the FlexVolume cluster. Defaults to ~/.kube/config.

Step 3: Generate CSI YAML for PVs and PVCs

Optional parameters

View available parameters.

flexvolume2csi translate help

Expected output:

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   filter storageclass name
  -s, --suffix string         change pv/pvc name to xxx-suffix

Examples

1. Create a pv.yaml file with the following content.

   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" # Replace this with the mount target of your file storage.
         path: "/k8s"
         vers: "3"
         options: "nolock,tcp,noresvport"

2. Deploy the example PV in the FlexVolume cluster.

   kubectl apply -f pv.yaml

3. Create a pvc.yaml file with the following content.

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

4. Deploy the example PVC in the FlexVolume cluster.

   kubectl apply -f pvc.yaml

5. Confirm that the PV and PVC are in the Bound state.

   kubectl get pvc | grep pvc-nas

   Expected output:

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

6. Convert the PV and PVC YAML.

   Important

   FlexVolume PVCs and PVs cannot be converted to CSI with kubectl apply and must be redeployed. See Migrate FlexVolume to CSI.

   For temporary FlexVolume and CSI PVC/PV coexistence with csi-compatible-controller, use -p or -s to avoid name conflicts.

   flexvolume2csi translate -s csi

7. View the output CSI YAML.

   cat ./outputfile.txt

   Expected output:

   ---
   
   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
   

   The PV and PVC CSI YAML is generated.

(Optional) Step 4: Generate CSI YAML for inline volumes

Early versions of ACK managed clusters and ACK Serverless clusters support FlexVolume inline volumes for workloads. If your cluster has such workloads, convert their YAML files too.

Inline volumes do not require PVC or PV resources. Example YAML for a stateful application with inline FlexVolume storage:

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

Volume test is an inline FlexVolume Cloud Disk volume.

Conversion targets

When converting an inline FlexVolume volume:

• A Cloud Disk volume without a specified volumeId converts to an inline ephemeral volume.

• Other volume types convert to standalone CSI PVs and PVCs. The generated YAML includes the PV, PVC, and the original workload.

Optional parameters

View available parameters.

flexvolume2csi inline-translate help

Expected output:

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   filter storageclass name
  -k, --sts string            specified kind for workloads

Examples

Converting Cloud Disk storage with an unspecified volumeId to an ephemeral volume

1. Create a workload with the following content.

   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"

2. Convert the deployed workload with FlexVolume2CSI.

   flexvolume2csi inline-translate -k deploy -n default -i nginx 

3. View the output CSI YAML.

   cat ./outputfile.txt

   Expected output:

   ---
   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

   The inline FlexVolume volume converts to an ephemeral volume.

4. Adjust the generated YAML as needed. For ephemeral volume conversion, make the following modifications:

   1. Specify a storage class in the ephemeral section:

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

   You can also use the -t and -c parameters during conversion. Changes apply to all resources.

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

Convert other volume types to CSI volumes

Use the -f parameter to specify the YAML file to convert.

1. Save the StatefulSet YAML from the beginning of this step as disk-static-sts.yaml.

2. Convert the stateful application YAML with FlexVolume2CSI.

   flexvolume2csi inline-translate -f disk-static-sts.yaml

3. View the converted YAML.

   cat ./outputfile.txt

   Expected output:

   ---
   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
   

   The inline FlexVolume volume converts to a CSI PV and PVC. The StatefulSet volume definition references the new PVC. The volumeClaimTemplates section remains unchanged.

4. Adjust the generated YAML as needed:

   1. Specify storage capacity for the PV and PVC. For example, for 20 Gi:

      ---
      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****

   2. Change the storage class in volumeClaimTemplates to a CSI class.

   You can also use the -t and -c parameters during conversion. Changes apply to all resources.

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

Step 5: Review and deploy the CSI YAML

The CLI generates YAML but does not deploy resources. Review and deploy the output manually as described in Migrate FlexVolume to CSI.

Use kubectl create -f to avoid PV and PVC naming conflicts.

Related topics

• Migrate FlexVolume to CSI using csi-compatible-controller

• Migrate FlexVolume to CSI for clusters without data

• Migrate statically provisioned NAS volumes from FlexVolume to CSI

• Migrate statically provisioned OSS volumes from FlexVolume to CSI