Container Service for Kubernetes:Use the FlexVolume2CSI command-line interface to batch convert YAML files

How it works

The FlexVolume2CSI tool lists all or specified volume or workload resources within a cluster or a specified namespace. It translates the content of standard FlexVolume fields into the corresponding CSI format and outputs the resulting YAML to a file for deployment.

Step 1: Install the FlexVolume2CSI command-line interface

1. Run the following command to install FlexVolume2CSI.

   You can install it on 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

   This output confirms that the FlexVolume2CSI command-line interface 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
   Cluster Id	The ID of the FlexVolume cluster.
   Kubeconfig Path	The path of the kubeconfig file for the FlexVolume cluster. The default path is ~/.kube/config.

Step 3: Generate CSI YAML files for FlexVolume PVs and PVCs

Optional parameters

Run the following command to query the optional configuration items supported by 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

Example

1. Use the following content to create a pv.yaml file in the FlexVolume cluster.

   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 address of your file storage.
         path: "/k8s"
         vers: "3"
         options: "nolock,tcp,noresvport"

2. Run the following command to deploy the sample PV in the FlexVolume cluster.

   kubectl apply -f pv.yaml

3. Use the following content to create a pvc.yaml file in the FlexVolume cluster.

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

4. Run the following command to deploy the sample PVC in the FlexVolume cluster.

   kubectl apply -f pvc.yaml

5. Run the following command to 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. Run the following command to use the FlexVolume2CSI CLI to convert the YAML files of all PVs and PVCs in the cluster.

   Important

   FlexVolume PVC and PV resources cannot be converted to the CSI type by running commands such as kubectl apply. You must redeploy them. For more information about the complete migration process, see the scenario documents in Migrate from FlexVolume to CSI.

   To allow FlexVolume and CSI PVC and PV resources to temporarily coexist using the csi-compatible-controller component, use the -p or -s parameter to avoid resource name conflicts.

   flexvolume2csi translate -s csi

7. Run the following command to view the output CSI YAML files for the PV and PVC.

   cat ./outputfile.yaml

   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
   

   This output indicates that the CSI YAML files for the PV and PVC were successfully generated.

(Optional) Step 4: Generate a CSI YAML file for a workload with an inline FlexVolume volume

Earlier versions of ACK managed clusters and ACK Serverless clusters support mounting FlexVolume storage to workloads using the inline mode. If your cluster is running such workloads, you must also convert their YAML files.

The inline mount method does not require corresponding PVC and PV resources. The following code provides an example YAML file for a stateful application that has a FlexVolume volume mounted 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 disk volume that is mounted in inline mode.

Conversion targets

When you convert a FlexVolume volume that is mounted in inline mode:

• Disk volumes that do not have a specified volumeId are converted to inline ephemeral volumes.

• Other types of volumes are converted to CSI volumes as independent PVs and PVCs. The generated CSI YAML file includes the PV, PVC, and the original workload resource.

Optional parameters

Run the following command to query the optional configuration items supported by 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

Examples

Convert a disk volume without a specified volumeId to an ephemeral volume

1. Use the following content to create a workload in the FlexVolume cluster.

   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 view the output CSI YAML file for the workload.

   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

   The output shows that the inline FlexVolume volume is converted to a corresponding ephemeral volume.

4. Adjust the generated YAML content as needed. When converting to an ephemeral volume, you usually need to modify the following:

   1. Specify an ephemeral StorageClass in ephemeral. After adjustment:

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

   You can also make these changes by specifying the -t and -c parameters during the conversion. These parameters take effect for all resources.

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

Convert other types of volumes to CSI volumes

This example shows how to use the -f parameter to specify the YAML content to convert.

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 output shows that the inline FlexVolume volume is converted into a corresponding CSI PVC and PV, and the volume type in the stateful application is changed to a reference to the CSI PVC. In addition, the content in volumeClaimTemplates is not changed.

4. Adjust the generated YAML content as needed. When converting to a CSI StorageClass, you usually need to modify the following:

   1. Declare the required storage capacity for the CSI PVC and PV. Assume that 20 GiB is required. After adjustment:

      ---
      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 StorageClass specified in volumeClaimTemplates must be changed to a CSI class. You can modify the value of the field directly.

   You can also make these changes by specifying the -t and -c parameters during the conversion. These parameters take effect for all resources.

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

Step 5: Check and deploy the generated CSI YAML

FlexVolume2CSI only generates YAML files. After you confirm that the YAML content is correct, you must manually deploy it to the cluster. For more information about the complete migration process, see the scenario documents in Migrate from FlexVolume to CSI.

To avoid resource name conflicts for PVCs and PVs, use the kubectl create -f command for deployment.

References

• Migrate from FlexVolume to CSI using the csi-compatible-controller component

• Migrate from FlexVolume to CSI for clusters without storage

• Migrate statically provisioned NAS volumes from FlexVolume to CSI

• Migrate statically provisioned OSS volumes from FlexVolume to CSI