FlexVolume2CSI CLI を使用して YAML を一括変換する方法 - Container Service for Kubernetes

FlexVolume2CSI コマンドラインインターフェイス (CLI) は、FlexVolume またはインラインボリュームを使用するワークロードの YAML ファイルを変換し、FlexVolume クラスターから Container Storage Interface (CSI) クラスターへの移行を簡素化します。このトピックでは、CLI を使用してこの変換を一括で実行する方法について説明します。

仕組み

FlexVolume2CSI ツールは、クラスターまたは特定の名前空間内のすべて、または特定のボリュームやワークロードリソースを一覧表示します。FlexVolume のフィールドを CSI 形式に変換し、結果の YAML をデプロイ用のファイルに書き込みます。

重要

この変換は、Apsara File Storage NAS、Object Storage Service (OSS)、およびクラウドディスクの標準的な PersistentVolume (PV)、PersistentVolumeClaim (PVC)、およびインラインボリュームのみをサポートします。デプロイする前に、生成された CSI YAML ファイルを確認してください。

ステップ1：FlexVolume2CSI CLI のインストール

次のコマンドを実行して、FlexVolume2CSI CLI をインストールします。
このツールは、macOS および Linux システムにインストールできます。
```
curl https://ack-csiplugin.oss-cn-hangzhou.aliyuncs.com/flexvolume2csi/get-translator.sh | bash
```

次のコマンドを実行して、インストールを検証します。

flexvolume2csi version

予想される出力：

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

この出力は、FlexVolume2CSI CLI が正常にインストールされたことを示します。

ステップ2：FlexVolume2CSI CLI の設定

次のコマンドを実行して、クラスター情報を設定します。
```
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 クラスターの ID。
Kubeconfig Path
FlexVolume クラスターの Kubeconfig ファイルパス。デフォルトは ~/.kube/config です。

ステップ3：PersistentVolume と PersistentVolumeClaim の CSI YAML の生成

オプションのパラメーター

次のコマンドを実行して、利用可能なパラメーターを表示します。

flexvolume2csi translate help

予想される出力：

スタンドアロンの PersistentVolumeClaim および PersistentVolume リソースを FlexVolume から CSI 形式に変換

Usage:
  flexvolume2csi translate [-n namespace] [-c pvc] [-o outputfile] [-p prefix] [-s suffix] [-b backupfile] [-t storageclass] [flags]

Examples:
  # すべての名前空間内の PersistentVolumeClaim と関連 PersistentVolume を変換
  flexvolume2csi translate -o output.txt

  # default 名前空間内の PersistentVolumeClaim と関連 PersistentVolume を変換
  flexvolume2csi translate -n default -o output.txt

  # default 名前空間内の PersistentVolumeClaim test-pvc と関連 PersistentVolume を変換
  flexvolume2csi translate -n default -p test-pvc -o output.txt


Flags:
  -b, --backupfile string     バックアップ (flexvolume) ファイルへのパス (デフォルト： "./backupfile.txt")
  -h, --help                  translate のヘルプ
  -n, --namespace string      指定された名前空間
  -o, --outputfile string     出力 (CSI) ファイルへのパス (デフォルト： "./outputfile.txt")
  -p, --prefix string         PersistentVolume/PersistentVolumeClaim 名を prefix-xxx に変更
  -c, --pvc string            指定された PersistentVolumeClaim
  -t, --storageclass string   ストレージクラス名でフィルター
  -s, --suffix string         PersistentVolume/PersistentVolumeClaim 名を xxx-suffix に変更

パラメーター	説明
`-o`	生成された CSI PersistentVolume および PersistentVolumeClaim の YAML ファイルへのパス。デフォルトは現在のディレクトリの `outputfile.txt` です。空の値を渡すと、出力は標準出力に出力されます。
`-b`	元の FlexVolume の PersistentVolume および PersistentVolumeClaim の YAML ファイルのバックアップパス。デフォルトは現在のディレクトリの `backupfile.txt` です。空の値を指定した場合、バックアップは実行されません。
`-n`	処理するリソースを含む名前空間。デフォルトでは、すべての名前空間が処理されます。
`-c`	PersistentVolumeClaim の名前を指定して、その PersistentVolumeClaim と対応する PersistentVolume のみを処理します。このパラメーターは `-n` パラメーターと一緒に使用する必要があります。デフォルトでは、選択した名前空間内のすべての PersistentVolume と PersistentVolumeClaim が処理されます。
`-p`	生成された CSI PersistentVolume および PersistentVolumeClaim の名前にプレフィックスを追加します。デフォルトでは、プレフィックスは追加されません。たとえば、元の FlexVolume PersistentVolumeClaim の名前が pvc-test で、-p csi を指定した場合、対応する CSI PersistentVolumeClaim の名前は csi-pvc-test になります。
`-s`	生成された CSI PersistentVolume および PersistentVolumeClaim の名前にサフィックスを追加します。デフォルトでは、サフィックスは追加されません。たとえば、元の FlexVolume PersistentVolumeClaim の名前が pvc-test で、-s csi を指定した場合、対応する CSI PersistentVolumeClaim の名前は 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 クラスターにサンプルの PersistentVolume をデプロイします。
```
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 クラスターにサンプルの PersistentVolumeClaim をデプロイします。
```
kubectl apply -f pvc.yaml
```
次のコマンドを実行して、PersistentVolume と PersistentVolumeClaim が Bound 状態であることを確認します。
```
kubectl get pvc | grep pvc-nas
```
予想される出力：
```
pvc-nas   Bound    pv-nas   5Gi       RWX            nas       10s
```
次のコマンドを実行して、PersistentVolume と PersistentVolumeClaim の YAML ファイルを変換します。
重要
FlexVolume の PersistentVolumeClaim および PersistentVolume リソースは、kubectl apply などのコマンドで直接 CSI タイプに変換できず、再デプロイする必要があります。完全な移行プロセスについては、「FlexVolume から CSI への移行」の関連シナリオをご参照ください。
csi-compatible-controller コンポーネントを使用して FlexVolume と CSI タイプの PersistentVolumeClaim および PersistentVolume リソースを一時的に共存させるには、リソース名の競合を避けるために -p または -s パラメーターを使用する必要があります。
```
flexvolume2csi translate -s csi
```

次のコマンドを実行して、PersistentVolume と PersistentVolumeClaim の出力 CSI YAML を表示します。

cat ./outputfile.txt

予想される出力：

---

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

この出力は、PersistentVolume と PersistentVolumeClaim の CSI YAML が正常に生成されたことを示します。

(オプション) ステップ4：インラインボリュームの CSI YAML の生成

初期バージョンの ACK マネージドクラスターおよび ACK Serverless クラスターでは、FlexVolume ストレージをインラインボリュームとしてワークロードにマウントできます。クラスターでこのようなワークロードを実行している場合は、それらの YAML ファイルも変換する必要があります。

インラインマウント方式では、対応する PersistentVolumeClaim および PersistentVolume リソースは必要ありません。以下は、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 という名前のボリュームは、インラインの FlexVolume クラウドディスクボリュームです。

説明

volumeClaimTemplates 内のストレージはコントローラーによって動的にプロビジョニングされ、関連する PersistentVolumeClaim および PersistentVolume リソースが自動的に作成されます。生成された PersistentVolumeClaim および PersistentVolume リソースは、ステップ3で CSI に変換できます。

コントローラーに CSI PersistentVolumeClaim および PersistentVolume リソースを再作成させるには、関連する FlexVolume PersistentVolumeClaim および PersistentVolume リソースを削除し (データが不要になったことを確認した後)、volumeClaimTemplates 内の storageClassName フィールドの値を CSI ストレージクラスに変更します。

変換ターゲット

インライン FlexVolume ボリュームを変換する場合：

volumeId が指定されていないクラウドディスクボリュームは、インラインのエフェメラルボリュームに変換されます。
その他のボリュームタイプは、スタンドアロンの CSI PersistentVolume および PersistentVolumeClaim に変換されます。生成される YAML には、PersistentVolume、PersistentVolumeClaim、および元のワークロードリソースが含まれます。

オプションのパラメーター

次のコマンドを実行して、利用可能なパラメーターを表示します。

flexvolume2csi inline-translate help

予想される出力：

ワークロード内のインラインストレージボリュームをスタンドアロンの CSI PersistentVolumeClaim および PersistentVolume リソースに変換

Usage:
  flexvolume2csi inline-translate [-n namespace] [-k kind] [-i item] [-f inputfile] [-o outputfile] [-b backupfile] [-t storageclass] [-c capacity] [flags]

Examples:
  # すべての名前空間内のすべての種類のワークロード (StatefulSet、Deployment など) のインライン FlexVolume ボリュームを変換
  # 注1：ワークロードの種類が指定されていない場合、Pod は変換されません。必要な場合は "-k pod" を使用してください。
  # 注2：StatefulSet の VolumeClaimTemplates は変換されません。"storageClassName" フィールドを手動で変更してください。
  flexvolume2csi inline-translate -o output.txt

  # default 名前空間内のすべての種類のワークロード (StatefulSet、Deployment など) のインライン FlexVolume ボリュームを変換
  flexvolume2csi inline-translate -n default -o output.txt

  # default 名前空間内の StatefulSet のインライン FlexVolume ボリュームを変換
  flexvolume2csi inline-translate -n default -k sts -o output.txt

  # default 名前空間内の StatefulSet test-sts のインライン FlexVolume ボリュームを変換
  flexvolume2csi inline-translate -n default -k sts -i test-sts -o output.txt

  # 入力ファイル内の各アイテムのインライン FlexVolume ボリュームを変換 ("---\n" でアイテムを区切る)
  flexvolume2csi inline-translate -i input.txt -o output.txt

Flags:
  -b, --backupfile string     バックアップ (flexvolume) ファイルへのパス (デフォルト： "./backupfile.txt")
  -c, --capacity string       容量の変更
  -h, --help                  inline-translate のヘルプ
  -f, --inputfile string      入力 (flexvolume) ファイルへのパス
  -i, --item string           指定されたアイテム名
  -k, --kind string           指定されたワークロードの種類
  -n, --namespace string      指定された名前空間
  -o, --outputfile string     出力 (CSI) ファイルへのパス (デフォルト： "./outputfile.txt")
  -t, --storageclass string   ストレージクラス名でフィルター

パラメーター	説明
`-o`	生成された CSI YAML ファイルのパス。デフォルトは現在のディレクトリの `outputfile.txt` です。空の値を渡すと、出力は標準出力に出力されます。
`-b`	FlexVolume ストレージを使用するワークロードの YAML ファイルのバックアップパス。デフォルトは現在のディレクトリの `backupfile.txt` です。空の値を指定した場合、バックアップは実行されません。
`-n`	処理するワークロードを含む名前空間。デフォルトでは、すべての名前空間が処理されます。
`-k`	`StatefulSet` や `Deployment` など、処理するワークロードの種類。デフォルトでは、すべての種類が処理されます。
`-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 CLI を使用してデプロイされたワークロードを変換します。
```
flexvolume2csi inline-translate -k deploy -n default -i nginx 
```

次のコマンドを実行して、出力された CSI YAML ファイルを表示します。

cat ./outputfile.txt

予想される出力：

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

インライン FlexVolume ボリュームが、対応するエフェメラルボリュームに変換されます。

必要に応じて、生成された YAML コンテンツを調整します。エフェメラルボリュームに変換する場合、通常、次の変更を行う必要があります。
1. 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 CLI を使用してファイルに記述されたステートフルアプリケーションを変換します。
```
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

インライン FlexVolume ボリュームは、対応する CSI PersistentVolume と PersistentVolumeClaim に変換されます。StatefulSet のボリューム定義は、新しい PersistentVolumeClaim を参照するように更新されます。volumeClaimTemplates セクションは変更されません。

必要に応じて、生成された YAML コンテンツを調整します。CSI PersistentVolume および PersistentVolumeClaim に変換する場合、通常、次の変更を行う必要があります。

CSI PersistentVolume と PersistentVolumeClaim に必要なストレージ容量を指定します。たとえば、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****

volumeClaimTemplates で指定されたストレージクラスは、CSI クラスに変更する必要があります。フィールドの値を直接変更できます。

これらの変更は、変換中に -t および -c パラメーターを使用して適用することもできます。変更はすべてのリソースに適用されます。

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

ステップ5：CSI YAML の確認とデプロイ

FlexVolume2CSI CLI は YAML を生成するだけで、リソースはデプロイしません。YAML コンテンツを確認した後、手動でクラスターにデプロイします。完全な移行ワークフローについては、「FlexVolume から CSI への移行」のシナリオをご参照ください。

PersistentVolumeClaim および PersistentVolume リソースの名前の競合を避けるため、デプロイ中に kubectl create -f コマンドを使用することを推奨します。

Container Service for Kubernetes:FlexVolume2CSI CLI を使用した YAML の一括変換

仕組み

ステップ1：FlexVolume2CSI CLI のインストール

ステップ2：FlexVolume2CSI CLI の設定

ステップ3：PersistentVolume と PersistentVolumeClaim の CSI YAML の生成

オプションのパラメーター

例

(オプション) ステップ4：インラインボリュームの CSI YAML の生成

変換ターゲット

オプションのパラメーター

例

`volumeId` が指定されていないクラウドディスクストレージをエフェメラルボリュームに変換

その他のボリュームタイプを CSI ボリュームに変換

ステップ5：CSI YAML の確認とデプロイ

関連トピック

パラメーター	説明
Cluster Id	FlexVolume クラスターの ID。
Kubeconfig Path	FlexVolume クラスターの Kubeconfig ファイルパス。デフォルトは ~/.kube/config です。

仕組み

ステップ1：FlexVolume2CSI CLI のインストール

ステップ2：FlexVolume2CSI CLI の設定

ステップ3：PersistentVolume と PersistentVolumeClaim の CSI YAML の生成

オプションのパラメーター

例

(オプション) ステップ4：インラインボリュームの CSI YAML の生成

変換ターゲット

オプションのパラメーター

例

volumeId が指定されていないクラウドディスクストレージをエフェメラルボリュームに変換

その他のボリュームタイプを CSI ボリュームに変換

ステップ5：CSI YAML の確認とデプロイ

関連トピック

`volumeId` が指定されていないクラウドディスクストレージをエフェメラルボリュームに変換