VirtualMachine

Virtual Machine resource for managing KubeVirt virtual machines

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

Basic VM creation

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}")

Related Resources

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.