Container Service for Kubernetes:Batch convert YAML with the FlexVolume2CSI CLI

Como funciona

A ferramenta FlexVolume2CSI lista recursos de volume e carga de trabalho em um cluster ou namespace, traduz os campos do FlexVolume para o formato CSI e grava o YAML resultante em um arquivo.

Etapa 1: Instale a CLI FlexVolume2CSI

1. Instale a CLI FlexVolume2CSI.

   Compatível com macOS e Linux.

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

2. Verifique a instalação.

   flexvolume2csi version

   Saída esperada:

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

   Essa saída confirma que a instalação foi bem-sucedida.

Etapa 2: Configure a CLI FlexVolume2CSI

1. Configure as informações do cluster.

   flexvolume2csi configure

   Saída esperada:

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

   Parâmetro	Descrição
   Cluster Id	ID do cluster FlexVolume.
   Kubeconfig Path	Caminho do arquivo kubeconfig do cluster FlexVolume. O padrão é ~/.kube/config.

Etapa 3: Gerar YAML CSI para PVs e PVCs

Parâmetros opcionais

Visualize os parâmetros disponíveis.

flexvolume2csi translate help

Saída esperada:

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

Exemplos

1. Crie um arquivo pv.yaml com o seguinte conteúdo.

   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. Implante o PV de exemplo no cluster FlexVolume.

   kubectl apply -f pv.yaml

3. Crie um arquivo pvc.yaml com o seguinte conteúdo.

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

4. Implante a PVC de exemplo no cluster FlexVolume.

   kubectl apply -f pvc.yaml

5. Confirme se o PV e a PVC estão no estado Bound.

   kubectl get pvc | grep pvc-nas

   Saída esperada:

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

6. Converta o YAML do PV e da PVC.

   Importante

   Não é possível converter PVCs e PVs FlexVolume para CSI com kubectl apply; eles devem ser reimplantados. Consulte Migrar FlexVolume para CSI.

   Para coexistência temporária de PVC/PV FlexVolume e CSI com csi-compatible-controller, use -p ou -s para evitar conflitos de nomes.

   flexvolume2csi translate -s csi

7. Visualize o YAML CSI de saída.

   cat ./outputfile.txt

   Saída esperada:

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

   O YAML CSI do PV e da PVC foi gerado.

(Opcional) Etapa 4: Gerar YAML CSI para volumes inline

Versões anteriores de clusters gerenciados ACK e clusters ACK Serverless suportam volumes inline FlexVolume para cargas de trabalho. Se o seu cluster tiver essas cargas de trabalho, converta também os arquivos YAML correspondentes.

Volumes inline não exigem recursos PVC ou PV. Exemplo de YAML para uma aplicação com estado usando armazenamento FlexVolume inline:

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

O volume test é um volume Cloud Disk FlexVolume inline.

Alvos de conversão

Ao converter um volume FlexVolume inline:

• Um volume Cloud Disk sem volumeId especificado converte-se em um volume efêmero inline.

• Outros tipos de volume convertem-se em PVs e PVCs CSI independentes. O YAML gerado inclui o PV, a PVC e a carga de trabalho original.

Parâmetros opcionais

Visualize os parâmetros disponíveis.

flexvolume2csi inline-translate help

Saída esperada:

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

Exemplos

**Converter armazenamento Cloud Disk com volumeId não especificado para um volume efêmero**

1. Crie uma carga de trabalho com o seguinte conteúdo.

   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. Converta a carga de trabalho implantada com o FlexVolume2CSI.

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

3. Visualize o YAML CSI de saída.

   cat ./outputfile.txt

   Saída esperada:

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

   O volume FlexVolume inline foi convertido em um volume efêmero.

4. Ajuste o YAML gerado conforme necessário. Para conversão de volume efêmero, faça as seguintes modificações:

   1. Especifique uma classe de armazenamento na seção ephemeral:

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

   Também é possível usar os parâmetros -t e -c durante a conversão. As alterações aplicam-se a todos os recursos.

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

Converter outros tipos de volume para volumes CSI

Use o parâmetro -f para especificar o arquivo YAML a ser convertido.

1. Salve o YAML do StatefulSet do início desta etapa como disk-static-sts.yaml.

2. Converta o YAML da aplicação com estado com o FlexVolume2CSI.

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

3. Visualize o YAML convertido.

   cat ./outputfile.txt

   Saída esperada:

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

   O volume FlexVolume inline converte-se em um PV e uma PVC CSI. A definição de volume do StatefulSet referencia a nova PVC. A seção volumeClaimTemplates permanece inalterada.

4. Ajuste o YAML gerado conforme necessário:

   1. Especifique a capacidade de armazenamento para o PV e a PVC. Por exemplo, para 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. Altere a classe de armazenamento em volumeClaimTemplates para uma classe CSI.

   Também é possível usar os parâmetros -t e -c durante a conversão. As alterações aplicam-se a todos os recursos.

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

Etapa 5: Revisar e implantar o YAML CSI

A CLI gera o YAML, mas não implanta os recursos. Revise e implante a saída manualmente conforme descrito em Migrar FlexVolume para CSI.

Use kubectl create -f para evitar conflitos de nomenclatura de PV e PVC.

Tópicos relacionados

• Migrar FlexVolume para CSI usando csi-compatible-controller

• Migrar FlexVolume para CSI para clusters sem dados

• Migrar volumes NAS provisionados estaticamente de FlexVolume para CSI

• Migrar volumes OSS provisionados estaticamente de FlexVolume para CSI