OpenShift 文档正在迁移，很快将仅在 docs.redhat.com（所有 Red Hat 产品文档的中心）提供。立即体验 新的文档体验。
  1. 文档
    2. history bug_report picture_as_pdf
×

使用 CLI 工具

安装 virtctl

要在 Red Hat Enterprise Linux (RHEL) 9、Linux、Windows 和 macOS 操作系统上安装virtctl，请下载并安装virtctl 二进制文件。

要在 RHEL 8 上安装virtctl，请启用 OpenShift Virtualization 仓库，然后安装kubevirt-virtctl 包。

在 RHEL 9、Linux、Windows 或 macOS 上安装 virtctl 二进制文件

您可以从 OpenShift Container Platform Web 控制台下载适合您操作系统的virtctl 二进制文件，然后安装它。

步骤

  1. 在 Web 控制台中导航到**虚拟化 → 概述**页面。

  2. 单击**下载 virtctl**链接以下载适合您操作系统的virtctl 二进制文件。

  3. 安装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

在 RHEL 8 上安装 virtctl RPM 包

您可以通过启用 OpenShift Virtualization 仓库并安装kubevirt-virtctl包来在 Red Hat Enterprise Linux (RHEL) 8 上安装virtctl RPM 包。

先决条件

  • 集群中的每个主机都必须注册到 Red Hat Subscription Manager (RHSM) 并拥有活动的 OpenShift Container Platform 订阅。

步骤

  1. 使用subscription-manager CLI 工具运行以下命令来启用 OpenShift Virtualization 仓库：

    # subscription-manager repos --enable cnv-4.17-for-rhel-8-x86_64-rpms

  2. 运行以下命令安装kubevirt-virtctl包：

    # yum install kubevirt-virtctl

virtctl 命令

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

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

virtctl 信息命令

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

表 1. 信息命令
命令 描述

virtctl version

查看virtctl客户端和服务器版本。

virtctl help

查看virtctl命令列表。

virtctl <command> -h|--help

查看特定命令的选项列表。

virtctl options

查看任何virtctl命令的全局命令选项列表。

虚拟机信息命令

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

表 2. 虚拟机信息命令
命令 描述

virtctl fslist <vm_name>

查看访客机上可用的文件系统。

virtctl guestosinfo <vm_name>

查看访客机上操作系统的相关信息。

virtctl userlist <vm_name>

查看访客机上已登录的用户。

虚拟机清单创建命令

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

表 3. 虚拟机清单创建命令
命令 描述
virtctl create vm

创建VirtualMachine (VM) 清单。

virtctl create vm --name <vm_name>

创建 VM 清单，并为 VM 指定名称。

virtctl create vm --instancetype <instancetype_name>

创建一个使用现有集群范围实例类型的 VM 清单。

virtctl create vm --instancetype=virtualmachineinstancetype/<instancetype_name>

创建一个使用现有命名空间实例类型的 VM 清单。

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>

为集群范围的 VM 首选项创建一个清单，并为首选项指定一个名称。

virtctl create preference --namespace <namespace_value>

为命名空间 VM 首选项创建一个清单。

虚拟机管理命令

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

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

重启虚拟机。

虚拟机连接命令

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

表 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 连接手动连接到虚拟机。

virtctl vnc --port=<port-number> <vm_name>

如果指定端口可用，则指定一个端口号在该端口上运行代理。

如果未指定端口号，则代理将在随机端口上运行。

虚拟机导出命令

使用virtctl vmexport命令创建、下载或删除从虚拟机、虚拟机快照或持久卷声明 (PVC) 导出的卷。某些清单还包含一个 header secret，它允许访问端点以导入 OpenShift Virtualization 可以使用的格式的磁盘映像。

表 6. 虚拟机导出命令
命令 描述

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

检索现有导出的清单。清单不包含 header secret。

virtctl vmexport download export --manifest --vm=example

为虚拟机 example 创建虚拟机导出，并检索清单。清单不包含 header secret。

virtctl vmexport download export --manifest --snap=example

为虚拟机快照 example 创建虚拟机导出，并检索清单。清单不包含 header secret。

virtctl vmexport download export --manifest --include-secret

检索现有导出的清单。清单包含 header secret。

virtctl vmexport download export --manifest --manifest-output-format=json

以 json 格式检索现有导出的清单。清单不包含 header secret。

virtctl vmexport download export --manifest --include-secret --output=manifest.yaml

检索现有导出的清单。清单包含 header secret 并将其写入指定的文件。

虚拟机内存转储命令

您可以使用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>
表 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，则必须手动删除内存转储。

此命令删除虚拟机和 PVC 之间的关联，以便内存转储不会显示在VirtualMachine资源的status部分。PVC 不受影响。

热插拔和热拔出命令

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

表 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 桥接网络接口。

镜像上传命令

您可以使用virtctl image-upload命令将虚拟机镜像上传到数据卷。

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

将虚拟机镜像上传到指定请求大小的新数据卷。

使用 virtctl 部署 libguestfs

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

步骤

  • 要部署包含libguestfs-tools的容器，挂载 PVC 并附加 shell，请运行以下命令

    $ virtctl guestfs -n <namespace> <pvc_name> (1)
    1 PVC 名称是必需的参数。如果您不包含它，则会出现错误消息。

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:<公钥示例>

将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的帮助信息。

带有<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选项来覆盖镜像的拉取策略。

该命令还会检查另一个pod是否正在使用PVC，如果是，则会出现错误消息。但是，一旦libguestfs-tools进程启动，设置就无法避免新的pod使用相同的PVC。在启动访问相同PVC的虚拟机之前，必须验证没有活动的virtctl guestfs pod。

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

使用Ansible

要使用OpenShift Virtualization的Ansible集合，请参见Red Hat Ansible Automation Hub（Red Hat混合云控制台）。