3.2. CLI ツールの使用

virtctl コマンドラインツールを使用して、OpenShift Virtualization リソースを管理できます。

libguestfs コマンドラインツールを使用すると、仮想マシンのディスクイメージにアクセスして変更できます。libguestfs をデプロイするには、virtctl libguestfs コマンドを使用します。

3.2.1. virtctl のインストール

Red Hat Enterprise Linux (RHEL) 9、Linux、Windows、および MacOS オペレーティングシステムに virtctl をインストールするには、virtctl バイナリーファイルをダウンロードしてインストールします。

RHEL 8 に virtctl をインストールするには、OpenShift Virtualization リポジトリーを有効にしてから、kubevirt-virtctl パッケージをインストールします。

3.2.1.1. RHEL 9、Linux、Windows、macOS への virtctl バイナリーのインストール

OpenShift Container Platform Web コンソールからオペレーティングシステムの virtctl バイナリーをダウンロードし、それをインストールできます。

手順

Web コンソールの Virtualization Overview ページに移動します。
Download virtctl リンクをクリックして、オペレーティングシステム用の virtctl バイナリーをダウンロードします。
virtctl をインストールします。
- RHEL 9 およびその他の Linux オペレーティングシステムの場合:
  1. アーカイブファイルを解凍します。
    $ tar -xvf <virtctl-version-distribution.arch>.tar.gz
  2. 次のコマンドを実行して、virtctl バイナリーを実行可能にします。
    $ chmod +x <path/virtctl-file-name>
  3. virtctl バイナリーを PATH 環境変数 にあるディレクトリーに移動します。
    次のコマンドを実行して、パスを確認できます。
    $ echo $PATH
  4. KUBECONFIG 環境変数を設定します。
    $ export KUBECONFIG=/home/<user>/clusters/current/auth/kubeconfig
- Windows の場合:
  1. アーカイブファイルを展開します。
  2. 展開したフォルダー階層に移動し、virtctl 実行可能ファイルをダブルクリックしてクライアントをインストールします。
  3. virtctl バイナリーを PATH 環境変数 にあるディレクトリーに移動します。
    次のコマンドを実行して、パスを確認できます。
    C:\> path
- macOS の場合:
  1. アーカイブファイルを展開します。
  2. virtctl バイナリーを PATH 環境変数 にあるディレクトリーに移動します。
    次のコマンドを実行して、パスを確認できます。
    echo $PATH

3.2.1.2. RHEL 8 への virtctl RPM のインストール

OpenShift Virtualization リポジトリーを有効にし、kubevirt-virtctl パッケージをインストールすることで、Red Hat Enterprise Linux (RHEL) 8 に virtctl RPM をインストールできます。

前提条件

クラスター内の各ホストは Red Hat Subscription Manager (RHSM) に登録されており、アクティブな OpenShift Container Platform サブスクリプションを持つ必要があります。

手順

subscription-manager CLI ツールを使用して次のコマンドを実行し、OpenShift Virtualization リポジトリーを有効にします。
```
# subscription-manager repos --enable cnv-4.16-for-rhel-8-x86_64-rpms
```
次のコマンドを実行して、kubevirt-virtctl パッケージをインストールします。
```
# yum install kubevirt-virtctl
```

3.2.2. virtctl コマンド

virtctl クライアントは、OpenShift Virtualization リソースを管理するためのコマンドラインユーティリティーです。

注記

特に指定がない限り、仮想マシンコマンドは仮想マシンインスタンスにも適用されます。

3.2.2.1. virtctl 情報コマンド

virtctl information コマンドを使用して、virtctl クライアントに関する情報を表示します。

表3.1 情報コマンド
コマンド	説明
`virtctl version`	`virtctl` クライアントとサーバーのバージョンを表示します。
`virtctl help`	`virtctl` コマンドのリストを表示します。
`virtctl <command> -h\|--help`	特定のコマンドのオプションのリストを表示します。
`virtctl オプション`	任意の `virtctl` コマンドのグローバルコマンドオプションのリストを表示します。

3.2.2.2. 仮想マシン情報コマンド

virtctl を使用すると、仮想マシンおよび仮想マシンインスタンス (VMI) に関する情報を表示できます。

表3.2 仮想マシン情報コマンド
コマンド	説明
`virtctl fslist <vm_name>`	ゲストマシンで使用可能なファイルシステムを表示します。
`virtctl guestosinfo <vm_name>`	ゲストマシンのオペレーティングシステムに関する情報を表示します。
`virtctl userlist <vm_name>`	ゲストマシンにログインしているユーザーを表示します。

3.2.2.3. 仮想マシンマニフェスト作成コマンド

virtctl create コマンドを使用して、仮想マシン、インスタンスタイプ、および設定のマニフェストを作成できます。

表3.3 仮想マシンマニフェスト作成コマンド
コマンド	設定
`virtctl create vm`	`VirtualMachine` (VM) マニフェストを作成します。
`virtctl create vm --name <vm_name>`	仮想マシンの名前を指定して、仮想マシンのマニフェストを作成します。
`virtctl create vm --instancetype <instancetype_name>`	既存のクラスター全体のインスタンスの種類を使用する仮想マシンのマニフェストを作成します。
`virtctl create vm --instancetype=virtualmachineinstancetype/<instancetype_name>`	既存の namespaced インスタンスタイプを使用する仮想マシンのマニフェストを作成します。
`virtctl create instancetype --cpu <cpu_value> --memory <memory_value> --name <instancetype_name>`	クラスター全体のインスタンスタイプのマニフェストを作成します。
`virtctl create instancetype --cpu <cpu_value> --memory <memory_value> --name <instancetype_name> --namespace <namespace_value>`	namespaced インスタンスタイプのマニフェストを作成します。
`virtctl create preference --name <preference_name>`	設定の名前を指定して、クラスター全体の仮想マシン設定のマニフェストを作成します。
`virtctl create preference --namespace <namespace_value>`	namespace 付き仮想マシン設定のマニフェストを作成します。

3.2.2.4. 仮想マシン管理コマンド

virtctl 仮想マシン管理コマンドを使用して、仮想マシンおよび仮想マシンインスタンスを管理および移行します。

表3.4 仮想マシン管理コマンド
コマンド	説明
`virtctl start <vm_name>`	仮想マシンを開始します。
`virtctl start --paused <vm_name>`	仮想マシンを一時停止状態で起動します。このオプションを使用すると、VNC コンソールからブートプロセスを中断できます。
`virtctl stop <vm_name>`	仮想マシンを停止します。
`virtctl stop <vm_name> --grace-period 0 --force`	仮想マシンを強制停止します。このオプションは、データの不整合またはデータ損失を引き起こす可能性があります。
`virtctl pause vm <vm_name>`	仮想マシンを一時停止します。マシンの状態がメモリーに保持されます。
`virtctl unpause vm <vm_name>`	仮想マシンの一時停止を解除します。
`virtctl migrate <vm_name>`	仮想マシンを移行します。
`virtctl migrate-cancel <vm_name>`	仮想マシンの移行をキャンセルします。
`virtctl restart <vm_name>`	仮想マシンを再起動します。

3.2.2.5. 仮想マシン接続コマンド

virtctl 接続コマンドを使用してポートを公開し、仮想マシンおよび仮想マシンインスタンスに接続します。

表3.5 仮想マシン接続コマンド
コマンド	説明
`virtctl console <vm_name>`	仮想マシンのシリアルコンソールに接続します。
`virtctl expose vm <vm_name> --name <service_name> --type <ClusterIP\|NodePort\|LoadBalancer> --port <port>`	仮想マシンの指定されたポートを転送するサービスを作成し、ノードの指定されたポートでサービスを公開します。例: `virtctl expose vm rhel9_vm --name rhel9-ssh --type NodePort --port 22`
`virtctl scp -i <ssh_key> <file_name> <user_name>@<vm_name>`	マシンから仮想マシンにファイルをコピーします。このコマンドは、SSH キーペアの秘密キーを使用します。仮想マシンは公開キーを使用して設定する必要があります。
`virtctl scp -i <ssh_key> <user_name@<vm_name>:<file_name> .`	仮想マシンからマシンにファイルをコピーします。このコマンドは、SSH キーペアの秘密キーを使用します。仮想マシンは公開キーを使用して設定する必要があります。
`virtctl ssh -i <ssh_key> <user_name>@<vm_name>`	仮想マシンとの SSH 接続を開きます。このコマンドは、SSH キーペアの秘密キーを使用します。仮想マシンは公開キーを使用して設定する必要があります。
`virtctl vnc <vm_name>`	仮想マシンの VNC コンソールに接続します。 `virt-viewer` がインストールされている必要があります。
`virtctl vnc --proxy-only=true <vm_name>`	ポート番号を表示し、VNC 接続を介してビューアーを使用して手動で VM に接続します。
`virtctl vnc --port=<port-number> <vm_name>`	ポートが利用可能な場合、その指定されたポートでプロキシーを実行するためにポート番号を指定します。ポート番号が指定されていない場合、プロキシーはランダムポートで実行されます。

3.2.2.6. 仮想マシンエクスポートコマンド

virtctl vmexport コマンドを使用して、仮想マシン、仮想マシンスナップショット、または永続ボリューム要求 (PVC) からエクスポートされたボリュームを作成、ダウンロード、または削除できます。特定のマニフェストには、OpenShift Virtualization が使用できる形式でディスクイメージをインポートするためのエンドポイントへのアクセスを許可するヘッダーシークレットも含まれています。

表3.6 仮想マシンエクスポートコマンド
コマンド	説明
`virtctl vmexport create <vmexport_name> --vm\|snapshot\|pvc=<object_name>`	仮想マシン、仮想マシンスナップショット、または PVC からボリュームをエクスポートするには、`VirtualMachineExport` カスタムリソース (CR) を作成します。 `--vm`: 仮想マシンの PVC をエクスポートします。 `--snapshot`: `VirtualMachineSnapshot` CR に含まれる PVC をエクスポートします。 `--pvc`: PVC をエクスポートします。オプション: `--ttl=1h` は存続時間を指定します。デフォルトの期間は 2 時間です。
`virtctl vmexport delete <vmexport_name>`	`VirtualMachineExport` CR を手動で削除します。
`virtctl vmexport download <vmexport_name> --output=<output_file> --volume=<volume_name>`	`VirtualMachineExport` CR で定義されたボリュームをダウンロードします。 `--output` はファイル形式を指定します。例: `disk.img.gz`。 `--volume` は、ダウンロードするボリュームを指定します。使用可能なボリュームが 1 つだけの場合、このフラグはオプションです。オプション: `--keep-vme` は、ダウンロード後に `VirtualMachineExport` CR を保持します。デフォルトの動作では、ダウンロード後に `VirtualMachineExport` CR を削除します。 `--insecure` は、安全でない HTTP 接続を有効にします。
`virtctl vmexport download <vmexport_name> --<vm\|snapshot\|pvc>=<object_name> --output=<output_file> --volume=<volume_name>`	`VirtualMachineExport` CR を作成し、CR で定義されたボリュームをダウンロードします。
`virtctl vmexport download export --manifest`	既存のエクスポートのマニフェストを取得します。マニフェストにはヘッダーシークレットが含まれていません。
`virtctl vmexport download export --manifest --vm=example`	仮想マシンサンプルの仮想マシンエクスポートを作成し、マニフェストを取得します。マニフェストにはヘッダーシークレットが含まれていません。
`virtctl vmexport download export --manifest --snap=example`	仮想マシンスナップショットの例の仮想マシンエクスポートを作成し、マニフェストを取得します。マニフェストにはヘッダーシークレットが含まれていません。
`virtctl vmexport download export --manifest --include-secret`	既存のエクスポートのマニフェストを取得します。マニフェストにはヘッダーシークレットが含まれています。
`virtctl vmexport download export --manifest --manifest-output-format=json`	既存のエクスポートのマニフェストを json 形式で取得します。マニフェストにはヘッダーシークレットが含まれていません。
`virtctl vmexport download export --manifest --include-secret --output=manifest.yaml`	既存のエクスポートのマニフェストを取得します。マニフェストにはヘッダーシークレットが含まれており、指定されたファイルにそれを書き込みます。

3.2.2.7. 仮想マシンメモリーダンプコマンド

virtctl memory-dump コマンドを使用して、PVC に仮想マシンのメモリーダンプを出力できます。既存の PVC を指定するか、--create-claim フラグを使用して新しい PVC を作成できます。

前提条件

PVC ボリュームモードは FileSystem である必要があります。
PVC は、メモリーダンプを格納するのに十分な大きさである必要があります。
PVC サイズを計算する式は (VMMemorySize + 100Mi) * FileSystemOverhead です。ここで、100Mi はメモリーダンプのオーバーヘッドです。

次のコマンドを実行して、HyperConverged カスタムリソースでホットプラグフィーチャーゲートを有効にする必要があります。

$ oc patch hyperconverged kubevirt-hyperconverged -n openshift-cnv \
  --type json -p '[{"op": "add", "path": "/spec/featureGates", \
  "value": "HotplugVolumes"}]'

メモリーダンプのダウンロード

メモリーダンプをダウンロードするには、virtctl vmexport download コマンドを使用する必要があります。

$ virtctl vmexport download <vmexport_name> --vm|pvc=<object_name> \
  --volume=<volume_name> --output=<output_file>

表3.7 仮想マシンメモリーダンプコマンド
コマンド	説明
`virtctl memory-dump get <vm_name> --claim-name=<pvc_name>`	仮想マシンのメモリーダンプを PVC に保存します。メモリーダンプのステータスは、`VirtualMachine` リソースの `status` セクションに表示されます。オプション: `--create-claim` は、適切なサイズで新しい PVC を作成します。このフラグには次のオプションがあります。 `--storage-class=<storage_class>`: PVC のストレージクラスを指定します。 `--access-mode=<access_mode>`: `ReadWriteOnce` または `ReadWriteMany` を指定します。
`virtctl memory-dump get <vm_name>`	同じ PVC で `virtctl memory-dump` コマンドを再実行します。このコマンドは、以前のメモリーダンプを上書きします。
`virtctl memory-dump remove <vm_name>`	メモリーダンプを削除します。ターゲット PVC を変更する場合は、メモリーダンプを手動で削除する必要があります。このコマンドは、`VirtualMachine` リソースの `status` セクションにメモリーダンプが表示されないように、仮想マシンと PVC の間の関連付けを削除します。PVC は影響を受けません。

3.2.2.8. ホットプラグおよびホットアンプラグコマンド

virtctl を使用して、実行中の仮想マシンおよび仮想マシンインスタンス (VMI) にリソースを追加または削除します。

表3.8 ホットプラグおよびホットアンプラグコマンド
コマンド	説明
`virtctl addvolume <vm_name> --volume-name=<datavolume_or_PVC> [--persist] [--serial=<label>]`	データボリュームまたは永続ボリューム要求 (PVC) をホットプラグします。オプション: `--persist` は仮想ディスクを VM に永続的にマウントします。このフラグは VMI には適用されません。 `--serial=<label>` は仮想マシンにラベルを追加します。ラベルを指定しない場合、デフォルトのラベルはデータボリュームまたは PVC 名になります。
`virtctl removevolume <vm_name> --volume-name=<virtual_disk>`	仮想ディスクをホットアンプラグします。
`virtctl addinterface <vm_name> --network-attachment-definition-name <net_attach_def_name> --name <interface_name>`	Linux ブリッジネットワークインターフェイスをホットプラグします。
`virtctl removeinterface <vm_name> --name <interface_name>`	Linux ブリッジネットワークインターフェイスをホットアンプラグします。

3.2.2.9. イメージアップロードコマンド

virtctl image-upload コマンドを使用して、VM イメージをデータボリュームにアップロードできます。

表3.9 イメージアップロードコマンド
コマンド	説明
`virtctl image-upload dv <datavolume_name> --image-path=</path/to/image> --no-create`	VM イメージを既存のデータボリュームにアップロードします。
`virtctl image-upload dv <datavolume_name> --size=<datavolume_size> --image-path=</path/to/image>`	指定された要求されたサイズの新しいデータボリュームに VM イメージをアップロードします。

3.2.3. virtctl を使用した libguestfs のデプロイ

virtctl guestfs コマンドを使用して、libguestfs-tools および永続ボリューム要求 (PVC) がアタッチされた対話型コンテナーをデプロイできます。

手順

libguestfs-tools でコンテナーをデプロイして PVC をマウントし、シェルを割り当てるには、以下のコマンドを実行します。
```
$ virtctl guestfs -n <namespace> <pvc_name> 1
```
1
PVC 名は必須の引数です。この引数を追加しないと、エラーメッセージが表示されます。

3.2.3.1. Libguestfs および virtctl guestfs コマンド

Libguestfs ツールは、仮想マシン (VM) のディスクイメージにアクセスして変更するのに役立ちます。libguestfs ツールを使用して、ゲスト内のファイルの表示および編集、仮想マシンのクローンおよびビルド、およびディスクのフォーマットおよびサイズ変更を実行できます。

virtctl guestfs コマンドおよびそのサブコマンドを使用して、PVC で仮想マシンディスクを変更して検査し、デバッグすることもできます。使用可能なサブコマンドの完全なリストを表示するには、コマンドラインで virt- と入力して Tab を押します。以下に例を示します。

コマンド	説明
`virt-edit -a /dev/vda /etc/motd`	ターミナルでファイルを対話的に編集します。
`virt-customize -a /dev/vda --ssh-inject root:string:<public key example>`	ゲストに ssh キーを挿入し、ログインを作成します。
`virt-df -a /dev/vda -h`	仮想マシンによって使用されるディスク容量を確認します。
`virt-customize -a /dev/vda --run-command 'rpm -qa > /rpm-list'`	詳細のリストを含む出力ファイルを作成して、ゲストにインストールされたすべての RPM の詳細リストを参照してください。
`virt-cat -a /dev/vda /rpm-list`	ターミナルで `virt-customize -a /dev/vda --run-command 'rpm -qa > /rpm-list'` コマンドを使用して作成されたすべての RPM の出力ファイルのリストを表示します。
`virt-sysprep -a /dev/vda`	テンプレートとして使用する仮想マシンディスクイメージをシールします。

デフォルトでは、virtctl guestfs は、仮想ディスク管理に必要な項目を含めてセッションを作成します。ただし、動作をカスタマイズできるように、コマンドは複数のフラグオプションもサポートしています。

フラグオプション	説明
`--h` または `--help`	`guestfs` のヘルプを提供します。
`-n <namespace>` オプションと `<pvc_name>` 引数	特定の namespace から PVC を使用します。 `-n <namespace>` オプションを使用しない場合には、現在のプロジェクトが使用されます。プロジェクトを変更するには、`oc project <namespace>` を使用します。 `<pvc_name>` 引数を追加しないと、エラーメッセージが表示されます。
`--image string`	`libguestfs-tools` コンテナーイメージをリスト表示します。 `--image` オプションを使用して、コンテナーがカスタムイメージを使用するように設定できます。
`--kvm`	`kvm` が `libguestfs-tools` コンテナーによって使用されることを示します。デフォルトでは、`virtctl guestfs` はインタラクティブなコンテナー向けに `kvm` を設定します。これは、QEMU を使用するため、`libguest-tools` の実行が大幅に加速されます。クラスターに `kvm` をサポートするノードがない場合は、オプション `--kvm=false` を設定して `kvm` を無効にする必要があります。設定されていない場合、`libguestfs-tools` Pod はいずれのノードにもスケジュールできないため保留状態のままになります。
`--pull-policy string`	`libguestfs` イメージのプルポリシーを表示します。 `pull-policy` オプションを設定してイメージのプルポリシーを上書きすることもできます。

このコマンドは、PVC が別の Pod によって使用されているかどうかを確認します。使用されている場合には、エラーメッセージが表示されます。ただし、libguestfs-tools プロセスが開始されると、設定では同じ PVC を使用する新規 Pod を回避できません。同じ PVC にアクセスする仮想マシンを起動する前に、アクティブな virtctl guestfs Pod がないことを確認する必要があります。

注記

virtctl guestfs コマンドは、インタラクティブな Pod に割り当てられている PVC 1 つだけを受け入れます。

3.2.4. Ansible の使用

OpenShift Virtualization 用の Ansible コレクションを使用するには、Red Hat Ansible Automation Hub (Red Hat Hybrid Cloud Console) を参照してください。