Use the FlexVolume2CSI CLI to batch convert YAML files

How it works

You can use FlexVolume2CSI to list all or specified volumes or workload resources in a cluster or a specified namespace. Then, use FlexVolume2CSI to convert the YAML files managed by FlexVolume to YAML files managed by CSI, and add the YAML file for convenient deployment.

Step 1: Install FlexVolume2CSI

1. Run the following command to install FlexVolume2CSI.

   FlexVolume2CSI supports MacOS and Linux.

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

2. Run the following command to verify that FlexVolume2CSI is installed:

   flexvolume2csi version

   Expected output:

   flexvolume2csi: v2.0.0+f87c834
     BuildDate: 2025-01-06T03:49:37Z
     GitCommit: f87c83459b8407668a04f7e7434cc51439c87508
     GitTreeState: clean
     GoVersion: go1.23.3
     Compiler: gc
     Platform: darwin/arm64

   The output indicates that FlexVolume2CSI is installed.

Step 2: Configure cluster information for FlexVolume2CSI

1. Run the following command to configure cluster information for FlexVolume2CSI:

   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

   Parameter	Description
   Cluster Id	The ID of the cluster that uses FlexVolume.
   Kubeconfig Path	The path of the kubeconfig file of the cluster that uses FlexVolume. The default is ~/.kube/config.

Step 3: Convert PVs and PVCs managed by FlexVolume in the cluster to PVs and PVCs managed by CSI

Optional parameters

Run the following command to query the optional parameters of FlexVolume2CSI:

flexvolume2csi translate help

Expected output:

flexvolume2csi source add [-n namespace] [-c pvc] [-o outputfile] [-p prefix] [-s suffix] [-b backupfile] [-t storageclass]

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

Procedure

1. Create a file named pv.yaml in a cluster that uses FlexVolume and add the following content to the file:

   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 the value with the actual mount target. 
         path: "/k8s"
         vers: "3"
         options: "nolock,tcp,noresvport"

2. Run the following command to create a PV in the cluster that uses FlexVolume:

   kubectl apply -f pv.yaml

3. Create a file named pvc.yaml in the cluster that uses FlexVolume and add the following content to the file:

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

4. Run the following command to create a PVC in the cluster that uses FlexVolume:

   kubectl apply -f pvc.yaml

5. Run the following command to verify that the PV is bound to the PVC:

   kubectl get pvc | grep pvc-nas

   Expected output:

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

6. Run the following command to use FlexVolume2CSI to convert the PV and PVC in the cluster:

   flexvolume2csi translate 

7. Run the following command to print the content of the YAML files of the PV and PVC managed by CSI:

   cat ./outputfile.yaml

   Expected output:

   ---
   
   apiVersion: v1
   kind: PersistentVolume
   metadata:
     labels:
       alicloud-pvname: pv-nas
     name: pv-nas
   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
     mountOptions:
     - nolock,tcp,noresvport
     - vers=3
     persistentVolumeReclaimPolicy: Retain
     storageClassName: nas
     volumeMode: Filesystem
   
   ---
   
   apiVersion: v1
   kind: PersistentVolumeClaim
   metadata:
     name: pvc-nas
     namespace: default
   spec:
     accessModes:
     - ReadWriteMany
     resources:
       requests:
         storage: 5Gi
     selector:
       matchLabels:
         alicloud-pvname: pv-nas
     storageClassName: nas
     volumeMode: Filesystem
     volumeName: pv-nas
   

   The output indicates that the PV and PVC are converted.

(Optional) Step 4: Generate a CSI YAML file corresponding to the workload with inline FlexVolume volumes

ACK managed clusters that run earlier versions of Kubernetes and ACK Serverless clusters allow you to mount FlexVolume volumes to workloads in the cluster in inline mode. If such workloads are running in your cluster, you must convert their YAML files.

The inline mount method does not require the corresponding PVC and PV resources. The following content is the YAML file for a stateful application that mounts a FlexVolume in inline mode:

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

The volume named test is the FlexVolume volume that is mounted in inline mode.

Conversion

When a FlexVolume volume mounted in inline mode is converted:

• A volume that does not have a specified volumeId is converted to an ephemeral volume in inline mode.

• The other types of volumes are converted to CSI volumes in the form of independent PVCs and PVs. The generated CSI YAML file includes the PV, PVC, and original workload resources.

Optional parameters

Run the following command to query the optional parameters of FlexVolume2CSI:

flexvolume2csi inline-translate help

Expected output:

flexvolume2csi source add [-n namespace] [-k kind] [-i item] [-f inputfile] [-o outputfile] [-b backupfile] [-t storageclass] [-c capacity]

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

Procedure

Convert disks that do not have a specified volumeId into ephemeral volumes

1. Use the following content to create a workload in the cluster that uses 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"

2. Run the following command to use the FlexVolume2CSI CLI to convert the deployed workload:

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

3. Run the following command to print the content of the YAML files of the PV and PVC managed by CSI:

   cat ./outputfile.yaml

   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

   As you can see, the inline FlexVolume volume is converted into the corresponding ephemeral volume.

4. Adjust the generated YAML file as needed when you convert the generated YAML content to a temporary volume.

   1. You must specify the temporary storage class in the ephemeral parameter.

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

   The preceding modifications can also be implemented by specifying the -t and -c parameters during conversion, which take effect on all resources.

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

Convert other types of volumes to CSI volumes

In this example, use the -f parameter to specify the YAML content that needs to be converted.

1. Save the YAML file of the stateful application shown at the beginning of this step as a disk-static-sts.yaml file.

2. Run the following command to use the FlexVolume2CSI CLI to convert the stateful application described in the file:

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

3. Run the following command to view the YAML file of the converted stateful application:

   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 volumes managed by FlexVolume are converted into the PVCs and PVs managed by CSI. The volume type corresponding to the stateful application refers to the PVC managed by CSI. In addition, the contents of volumeClaimTemplates are not changed.

4. Adjust the generated YAML file as needed when you convert the generated YAML file to a storage class managed by CSI.

   1. Declare the required storage capacity for the PVC and PV managed by CSI, such as 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****

   2. The storage class specified in volumeClaimTemplates must be changed to a storage class managed by CSI. You can directly change the value of the field.

   The preceding modifications can also be implemented by specifying the -t and -c parameters during conversion, which take effect on all resources.

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

Reference

• Use csi-compatible-controller to migrate from FlexVolume to CSI

• Upgrade FlexVolume to CSI for clusters that store no data

• Use CSI to take over the statically provisioned NAS volumes that are managed by FlexVolume

• Use CSI to take over the statically provisioned volumes that are managed by FlexVolume