Using virtctl

virtctl is the official KubeVirt client tool for managing and accessing virtual machines in PaaS Cloud. It complements the web dashboard and is useful for console access, image uploads, and VM control.

Installation

Download virtctl from the KubeVirt releases page or install via your package manager:

# macOS (Homebrew)
brew install kubevirt-io/homebrew-tap/virtctl

# Linux (binary)
export KUBEVIRT_VERSION=$(curl -s https://api.github.com/repos/kubevirt/kubevirt/releases/latest | jq -r .tag_name)
wget https://github.com/kubevirt/kubevirt/releases/download/${KUBEVIRT_VERSION}/virtctl-${KUBEVIRT_VERSION}-linux-amd64
chmod +x virtctl-${KUBEVIRT_VERSION}-linux-amd64
sudo mv virtctl-${KUBEVIRT_VERSION}-linux-amd64 /usr/local/bin/virtctl

Connecting to the Cluster

Ensure your kubeconfig is configured for the tenant namespace. If you do not have a kubeconfig yet, see Using kubectl. For access problems, contact the cloud team.

export KUBECONFIG=/path/to/tenant-kubeconfig
kubectl config set-context --current --namespace=<tenant-name>

Common Commands

List VMs

virtctl list

Start / Stop / Restart a VM

virtctl start <vm-name>
virtctl stop <vm-name>
virtctl restart <vm-name>

Serial Console

virtctl console <vm-name>

Press Ctrl+] to exit the console.

VNC

virtctl vnc <vm-name>

This opens a VNC client (requires a local VNC viewer or browser extension).

SSH

virtctl ssh <user>@<vm-name>

Requires the VM to have external network access or a configured jump host.

Upload an Image to a vm-disk

virtctl image-upload dv <disk-name> \
  --image-path=/path/to/image.qcow2 \
  --size=20Gi \
  --storage-class=replicated \
  --access-mode=ReadWriteOnce

See VM Image Upload for detailed upload instructions.

Guest Agent Info

virtctl guest-agent <vm-name>
virtctl guest-osinfo <vm-name>
virtctl guest-fsfreeze <vm-name>

These commands require the QEMU guest agent to be running inside the VM.

Troubleshooting

Problem	Solution
`virtctl` not found	Install `virtctl` from the KubeVirt releases page.
Cannot connect to VM	Verify the VM status is `Running` and the network is configured.
SSH fails	Confirm the VM has external access, the correct SSH key was provided, and the guest OS user exists.
VNC does not open	Ensure a VNC viewer is installed or use the dashboard Console instead.

Tip

For the full list of virtctl commands, run virtctl --help or refer to the KubeVirt User Guide.

Using virtctl

On this page