Skip to main content

​
Overview

The VirtualMachine class provides a comprehensive interface for managing KubeVirt virtual machines in OpenShift. It supports lifecycle operations including start, stop, restart, and status monitoring.

​
Class Definition

from ocp_resources.virtual_machine import VirtualMachine

class VirtualMachine(NamespacedResource):
    api_group = NamespacedResource.ApiGroup.KUBEVIRT_IO

​
Constructor

​
name
string
Name of the virtual machine resource.
​
namespace
string
Namespace where the virtual machine will be created.
​
client
DynamicClient
Kubernetes client instance for API communication.
​
body
dict
Dictionary containing the VM specification including template, domain, devices, and volumes configuration.
​
teardown
boolean
default:"true"
Whether to delete the resource during cleanup operations.
​
yaml_file
string
Path to a YAML file containing the VM definition.
​
delete_timeout
int
default:"TIMEOUT_4MINUTES"
Timeout in seconds for deletion operations (default: 240 seconds).

​
Run Strategies

The VirtualMachine.RunStrategy class defines how the VM lifecycle should be managed:
  • MANUAL: VM must be manually started and stopped
  • HALTED: VM should remain stopped
  • ALWAYS: VM should always be running
  • RERUNONFAILURE: VM should restart on failure

​
Status Values

The VirtualMachine.Status class provides constants for VM states:
  • MIGRATING: VM is being migrated to another node
  • PAUSED: VM is paused
  • PROVISIONING: VM resources are being provisioned
  • STARTING: VM is starting up
  • STOPPED: VM is stopped
  • STOPPING: VM is shutting down
  • WAITING_FOR_VOLUME_BINDING: Waiting for volumes to be bound
  • ERROR_UNSCHEDULABLE: VM cannot be scheduled
  • DATAVOLUME_ERROR: Error with associated DataVolume
  • ERROR_PVC_NOT_FOUND: PVC not found
  • IMAGE_PULL_BACK_OFF: Image pull failures
  • ERR_IMAGE_PULL: Image pull error
  • CRASH_LOOPBACK_OFF: VM is crash looping

​
Methods

​
start()

Starts the virtual machine.
​
timeout
int
default:"TIMEOUT_4MINUTES"
Maximum time to wait for the VM to start (in seconds).
​
wait
boolean
default:"false"
Whether to wait for the VM to reach running status.
vm.start(timeout=240, wait=True)

​
stop()

Stops the virtual machine.
​
timeout
int
default:"TIMEOUT_4MINUTES"
Maximum time to wait for the VM to stop (in seconds).
​
vmi_delete_timeout
int
default:"TIMEOUT_4MINUTES"
Maximum time to wait for the VMI to be deleted (in seconds).
​
wait
boolean
default:"false"
Whether to wait for the VM to stop and VMI to be deleted.
vm.stop(timeout=240, wait=True)

​
restart()

Restarts the virtual machine.
​
timeout
int
default:"TIMEOUT_4MINUTES"
Maximum time to wait for the VM to restart (in seconds).
​
wait
boolean
default:"false"
Whether to wait for the VM to complete restart.
vm.restart(timeout=240, wait=True)

​
wait_for_ready_status()

Waits for the VM to reach a specific ready status.
​
status
boolean | None
required
Target status: True for running VM, None for stopped VM.
​
timeout
int
default:"TIMEOUT_4MINUTES"
Maximum time to wait (in seconds).
​
sleep
int
default:"1"
Sleep interval between status checks (in seconds).
vm.wait_for_ready_status(status=True, timeout=300)

​
get_interfaces()

Returns the network interfaces configured for the VM. 
interfaces = vm.get_interfaces()

​
Properties

​
vmi

Returns the associated VirtualMachineInstance object. 
vmi = vm.vmi
vmi.wait_until_running()

​
ready

Returns the VM ready status. Returns: True if VM is running, None otherwise. 
if vm.ready:
    print("VM is running")

​
printable_status

Returns the human-readable status string from status.printableStatus. 
status = vm.printable_status
print(f"VM status: {status}")

​
Usage Example

from ocp_resources.virtual_machine import VirtualMachine
from ocp_resources.resource import get_client

client = get_client()

vm = VirtualMachine(
    client=client,
    name="my-vm",
    namespace="default",
    body={
        "spec": {
            "runStrategy": "Halted",
            "template": {
                "spec": {
                    "domain": {
                        "devices": {
                            "disks": [
                                {"name": "disk0", "disk": {"bus": "virtio"}}
                            ]
                        },
                        "resources": {
                            "requests": {"memory": "1Gi"}
                        }
                    },
                    "volumes": [
                        {
                            "name": "disk0",
                            "containerDisk": {
                                "image": "kubevirt/cirros-container-disk-demo"
                            }
                        }
                    ]
                }
            }
        }
    }
)

vm.create()
vm.start(wait=True)
print(f"VM is ready: {vm.ready}")

Virtual Machines Guide

Complete guide to working with virtual machines

DataVolume

Manages persistent storage for virtual machines

​
Notes

Virtual machines with runStrategy do not have a spec.running attribute. The VM status should be determined from status.ready.
When stopping a VM, ensure you wait for both the VM ready status to be None and the VMI to be deleted to confirm complete shutdown.

Build docs developers (and LLMs) love

Get started for freeTalk to us