如何使用FlexVolume2CSI命令行工具批量转换YAML_容器服务 Kubernetes 版 ACK(ACK)-阿里云帮助中心

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.0+f87c834
  BuildDate: 2025-01-06T03:49:37Z
  GitCommit: f87c83459b8407668a04f7e7434cc51439c87508
  GitTreeState: clean
  GoVersion: go1.23.3
  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

预期输出：

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

可选参数	说明
-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文件。
```
flexvolume2csi translate 
```

执行以下命令，查看输出的CSI的PV和PVC的YAML文件。

cat ./outputfile.yaml

预期输出：

---

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

预期输出表明，已成功生成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

预期输出：

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

可选参数	说明
-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"

实现原理

步骤一：安装FlexVolume2CSI命令行工具

步骤二：为FlexVolume2CSI配置集群信息

步骤三：生成Flexvolume PV和PVC对应的CSI YAML文件

可选参数

操作示例

（可选）步骤四：生成带有inline FlexVolume存储的工作负载对应的CSI YAML文件

转换目标

可选参数

操作示例

将未指定volumeId的云盘存储转换为临时卷

将其他类型的存储转换为CSI存储卷

相关文档

将未指定`volumeId`的云盘存储转换为临时卷