3.2. 使用 virtctl 和 libguestfs CLI 工具

您可使用 virtctl 命令行工具管理 OpenShift Virtualization 资源。

您可以使用 libguestfs 命令行工具访问和修改虚拟机(VM)磁盘镜像。您可以使用 virtctl libguestfs 命令部署 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.15-for-rhel-8-x86_64-rpms
```
运行以下命令安装 kubevirt-virtctl 软件包：
```
# yum install kubevirt-virtctl
```

3.2.2. virtctl 命令

virtctl 客户端是用于管理 OpenShift Virtualization 资源的命令行实用程序。

注意

除非另有指定，否则虚拟机(VM)命令也适用于虚拟机实例(VMI)。

3.2.2.1. virtctl 信息命令

您可使用 virtctl 信息命令查看 virtctl 客户端的信息。

表 3.1. 信息命令
命令	描述
`virtctl version`	查看 `virtctl` 客户端和服务器版本。
`virtctl help`	查看 `virtctl` 命令列表。
`virtctl <command> -h\|--help`	查看特定命令的选项列表。
`virtctl 选项`	查看任何 `virtctl` 命令的全局命令选项列表。

3.2.2.2. VM 信息命令

您可使用 virtctl 查看有关虚拟机(VM)和虚拟机实例(VMI)的信息。

表 3.2. VM 信息命令
命令	描述
`virtctl fslist <vm_name>`	查看客户机机器上可用的文件系统。
`virtctl guestosinfo <vm_name>`	查看客户机机器上操作系统的信息。
`virtctl userlist <vm_name>`	查看客户机机器上的登录用户。

3.2.2.3. VM 清单创建命令

您可使用 virtctl create 命令为虚拟机、实例类型和首选项创建清单。

表 3.3. VM 清单创建命令
命令	描述
`virtctl create vm`	创建 `VirtualMachine` (VM) 清单。
`virtctl create vm --name <vm_name>`	创建虚拟机清单，指定虚拟机的名称。
`virtctl create vm --instancetype <instancetype_name>`	创建使用现有集群范围实例类型的虚拟机清单。
`virtctl create vm --instancetype=virtualmachineinstancetype/<instancetype_name>`	创建使用现有命名空间的实例类型的虚拟机清单。
`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>`	为命名空间实例类型创建清单。
`virtctl create preference --name <preference_name>`	为集群范围的虚拟机首选项创建清单，为首选项指定一个名称。
`virtctl create preference --namespace <namespace_value>`	为命名空间虚拟机首选项创建清单。

3.2.2.4. VM 管理命令

您可使用 virtctl 虚拟机(VM)管理命令管理和迁移虚拟机(VM)和虚拟机实例(VMI)。

表 3.4. VM 管理命令
命令	描述
`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. VM 连接命令

您可使用 virtctl connection 命令来公开端口并连接到虚拟机(VM)和虚拟机实例(VMI)。

表 3.5. VM 连接命令
命令	描述
`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 连接手动连接到 VMI。
`virtctl vnc --port=<port-number> <vm_name>`	如果该端口可用，则指定端口号用于在指定端口上运行代理。如果没有指定端口号，代理会在随机端口上运行。

3.2.2.6. VM 导出命令

使用 virtctl vmexport 命令来创建、下载或删除从虚拟机、虚拟机快照或持久性卷声明 (PVC) 导出的卷。某些清单还包含标头 secret，它授予对端点的访问权限，以 OpenShift Virtualization 可以使用的格式导入磁盘镜像。

表 3.6. VM 导出命令
命令	描述
`virtctl vmexport create <vmexport_name> --vm\|snapshot\|pvc=<object_name>`	创建一个 `VirtualMachineExport` 自定义资源 (CR) 来从虚拟机、虚拟机快照或 PVC 导出卷。 `--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` 指定要下载的卷。如果只有一个卷可用，则此标志是可选的。可选： `--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`	检索一个现有导出的清单。清单不包括标头 secret。
`virtctl vmexport download export --manifest --vm=example`	为虚拟机创建虚拟机导出，并检索清单。清单不包括标头 secret。
`virtctl vmexport download export --manifest --snap=example`	为虚拟机快照示例创建虚拟机导出，并检索清单。清单不包括标头 secret。
`virtctl vmexport download export --manifest --include-secret`	检索一个现有导出的清单。清单包括标头 secret。
`virtctl vmexport download export --manifest --manifest-output-format=json`	以 json 格式检索现有导出的清单。清单不包括标头 secret。
`virtctl vmexport download export --manifest --include-secret --output=manifest.yaml`	检索一个现有导出的清单。清单包括标头 secret，并将其写入指定的文件中。

3.2.2.7. VM 内存转储命令

您可使用 virtctl memory-dump 命令在 PVC 上输出虚拟机 (VM) 内存转储。您可以指定现有的 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. VM 内存转储命令
命令	描述
`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，则必须手动删除内存转储。这个命令会删除虚拟机和 PVC 之间的关联，以便在 `VirtualMachine` 资源的 `status` 部分中不会显示内存转储。PVC 不受影响。

3.2.2.8. 热插和热拔命令

您可使用 virtctl 从正在运行的虚拟机(VM)和虚拟机实例(VMI)中添加或删除资源。

表 3.8. 热插和热拔命令
命令	描述
`virtctl addvolume <vm_name> --volume-name=<datavolume_or_PVC> [--persist] [--serial=<label>]`	热插数据卷或持久性卷声明 (PVC)。可选： `--persist` 在虚拟机上永久挂载虚拟磁盘。这个标志不适用于 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 命令将虚拟机镜像上传到数据卷中。

表 3.9. 镜像上传命令
命令	描述
`virtctl image-upload dv <datavolume_name> --image-path=</path/to/image> --no-create`	将虚拟机镜像上传到已存在的数据卷中。
`virtctl image-upload dv <datavolume_name> --size=<datavolume_size> --image-path=</path/to/image>`	将虚拟机镜像上传到指定请求大小的新数据卷中。

3.2.3. 使用 virtctl 部署 libguestfs

您可以使用 virtctl guestfs 命令部署带有 libguestfs-tools 以及附加到它的持久性卷声明 (PVC) 的交互式容器。

流程

要部署一个带有 libguestfs-tools 的容器，挂载 PVC 并为其附加一个 shell，运行以下命令：
```
$ 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 会创建一个会话，其中包含管理 VM 磁盘所需的一切内容。但是，如果想要自定义行为，该命令还支持几个标志选项：

标记选项	描述
`--h` 或 `--help`	为 `guestfs` 提供帮助.
带有 `<pvc_name>` 参数的 `-n <namespace>` 选项	使用特定命名空间中的 PVC。如果不使用 `-n <namespace>` 选项，则使用您的当前项目。要更改项目，请使用 `oc project <namespace>`。如果没有包括 `<pvc_name>` 参数，则会出现错误消息。
`--image string`	列出 `libguestfs-tools` 容器镜像。您可以使用 `--image` 选项，将容器配置为使用自定义镜像。
`--kvm`	代表 `libguestfs-tools` 容器使用 `kvm`。默认情况下，`virtctl guestfs` 为交互式容器设置 `kvm`，这可显著加快 `libguest-tools` 执行，因为它使用了 QEMU。如果群集没有任何 `kvm` 支持节点，您必须通过设置 `--kvm=false` 选项来禁用 `kvm`。如果没有设置，`libguestfs-tools` pod 将保持待处理状态，因为它无法调度到任何节点上。
`--pull-policy string`	显示 `libguestfs` 镜像的拉取策略。您还可以通过设置 `pull-policy` 选项来覆盖镜像的 pull 策略。

这个命令还会检查 PVC 是否被另一个 pod 使用，这时会出现错误消息。但是，libguestfs-tools 进程启动后，设置无法避免使用相同的 PVC 的新 pod。在启动虚拟机访问同一 PVC 前，您必须先验证没有活跃的 virtctl guestfs pod。

注意

virtctl guestfs 命令只接受附加到交互式 pod 的单个 PVC。