virtctl 命令介绍-谢先斌的博客

virtctl 命令介绍

发布时间： 2026-01-02 更新时间： 2026-01-18 总字数：1225 阅读时间：3m 作者：谢先斌 IP上海

virtctl 是 KubeVirt 项目提供的命令行工具。虽然可以使用 kubectl 来管理 KubeVirt 的资源（如创建 Pod、修改 YAML），但 virtctl 提供了专门针对虚拟化操作的高级功能，例如串行控制台访问、VNC 连接、虚拟机电源管理（启动/停止/重启）、实时迁移以及镜像上传等。

简单理解

Kubernetes 的 kubectl + 传统虚拟化的 virsh = virtctl

virtctl 安装

export VERSION=$(curl -s https://api.github.com/repos/kubevirt/kubevirt/releases | grep tag_name | grep -v -- '-rc' | head -1 | awk -F': ' '{print $2}' | sed 's/,//' | xargs)
curl -L -o /usr/local/bin/virtctl https://github.com/kubevirt/kubevirt/releases/download/$VERSION/virtctl-$VERSION-linux-amd64
mv /usr/local/bin/virtctl-$VERSION-linux-amd64 /usr/local/bin/virtctl
chmod +x /usr/local/bin/virtctl

virtctl 常用命令

电源与状态管理

这些命令直接操作 VirtualMachine (VM) 对象。

命令	说明	示例
start	启动一个处于停止状态的 VM	`virtctl start my-vm`
stop	优雅关闭 VM（向操作系统发送关机信号）	`virtctl stop my-vm`
stop –force	强制断电（相当于拔电源），用于 VM 卡死时	`virtctl stop my-vm --force --grace-period=0`
restart	重启 VM	`virtctl restart my-vm`
pause	暂停 VM（冻结 CPU 指令，不释放内存），类似于挂起	`virtctl pause vm my-vm`
unpause	解除暂停，恢复运行	`virtctl unpause vm my-vm`

访问与连接

这些命令用于与虚拟机的交互。

命令	说明	示例
console	连接到串行控制台（文本模式）。排查启动故障最常用。	`virtctl console my-vm`
vnc	建立 VNC 连接（图形界面）。需要本机安装有 VNC 客户端（如 remote-viewer）。	`virtctl vnc my-vm`
ssh	通过 SSH 连接到 VM（前提是 VM 内开启了 SSH 且网络可达）。	`virtctl ssh user@my-vm`

镜像与数据卷管理

在 KubeVirt 中，将本地的 ISO 或 QCOW2 镜像上传到集群是一个核心需求。

命令	说明	示例
image-upload	将本地镜像文件上传到 DataVolume (PVC)。	见下方详细说明

image-upload 示例：

virtctl image-upload dv my-data-volume \
  --size=10Gi \
  --image-path=/home/user/images/centos.qcow2 \
  --storage-class=longhorm-sc-xx

这条命令会自动创建一个 DataVolume，并把本地的 centos.qcow2 上传上去，供后续创建 VM 使用。

高级运维

命令	说明	示例
migrate	触发实时迁移（Live Migration），将 VM 从一个节点移动到另一个节点而不中断服务。	`virtctl migrate my-vm`
migrate-cancel	取消正在进行的迁移。	`virtctl migrate-cancel my-vm`
version	查看客户端和服务端版本。	`virtctl version`

示例：创建并启动一个虚拟机

为了演示 virtctl 的用法，先创建一个简单的 CirrOS（一个微型 Linux 发行版）虚拟机。

准备 YAML 文件

创建一个名为 vm.yaml 的文件。注意这里将 running: false 设置为默认，这样创建后虚拟机不会立即启动，以便我们演示 virtctl start。

apiVersion: kubevirt.io/v1
kind: VirtualMachine
metadata:
  name: my-vm
spec:
  running: false # 创建时不立即启动
  template:
    metadata:
      labels:
        kubevirt.io/vm: my-vm
    spec:
      domain:
        devices:
          disks:
            - name: containerdisk
              disk:
                bus: virtio
          interfaces:
            - name: default
              masquerade: {}
        resources:
          requests:
            memory: 128Mi
      networks:
        - name: default
          pod: {}
      volumes:
        - name: containerdisk
          containerDisk:
            # 使用官方提供的演示镜像
            image: quay.io/containerdisks/cirros:0.5.2

创建虚拟机对象

使用标准的 kubectl 命令将对象提交给 Kubernetes：

kubectl apply -f vm.yaml

此时，虚拟机对象（VirtualMachine）已创建，但处于停止状态。你可以通过 kubectl get vm 查看，状态应为 Stopped。

使用 virtctl 启动虚拟机

现在使用 virtctl 来启动它：

virtctl start my-vm

输出示例：VM my-vm was scheduled to start

再次查看状态 kubectl get vm，会发现状态变为了 Running。

使用 virtctl 连接控制台

虚拟机启动后，我们需要登录进去。CirrOS 不需要密码（或者在屏幕上会提示）。

virtctl console my-vm

输出示例：

Successfully connected to my-vm console.
The escape sequence is ^]

my-vm login:

在这里你可以输入用户名（通常是 cirros）进行操作。按 Ctrl + ] 退出控制台。

停止虚拟机

测试完毕后，将其关闭：

virtctl stop my-vm

总结

Kubectl 用于定义基础设施（“我要一个虚拟机，配置是 2 核 4G”）。
Virtctl 用于日常操作（“帮我开机”、“帮我插上显示器(Console)"、“帮我上传个系统盘”）。