Chapter 3. Python Examples

3.1. Overview
Copy link

This section provides examples demonstrating the steps to create a virtual machine within a basic Red Hat Virtualization environment, using the Python SDK.

These examples use the ovirtsdk Python library provided by the ovirt-engine-sdk-python package. This package is available to systems attached to a Red Hat Virtualization subscription pool in Red Hat Subscription Manager. See Installing the Software Development Kit for more information on subscribing your system(s) to download the software.

You will also need:

A networked installation of Red Hat Virtualization Manager.
A networked and configured Red Hat Virtualization Host.
An ISO image file containing an operating system for installation on a virtual machine.
A working understanding of both the logical and physical objects that make up a Red Hat Virtualization environment.
A working understanding of the Python programming language.

The examples include placeholders for authentication details (admin@internal for user name, and password for password). Replace the placeholders with the authentication requirements of your environment.

Red Hat Virtualization Manager generates a globally unique identifier (GUID) for the id attribute for each resource. Identifier codes in these examples differ from the identifier codes in your Red Hat Virtualization environment.

The examples contain only basic exception and error handling logic. For more information on the exception handling specific to the SDK, see the pydoc for the ovirtsdk.infrastructure.errors module:

$ pydoc ovirtsdk.infrastructure.errors

3.2. Connecting to the Red Hat Virtualization Manager in Version 4
Copy link

To connect to the Red Hat Virtualization Manager, you must create an instance of the Connection class from the ovirtsdk4.sdk module by importing the class at the start of the script:

import ovirtsdk4 as sdk

The constructor of the Connection class takes a number of arguments. Supported arguments are:

url: A string containing the base URL of the Manager, such as https://server.example.com/ovirt-engine/api.
username: Specifies the user name to connect, such as admin@internal. This parameter is mandatory.
password: Specifies the password for the user name provided by the username parameter. This parameter is mandatory.
token: An optional token to access the API, instead of a user name and password. If the token parameter is not specified, the SDK will create one automatically.
insecure: A Boolean flag that indicates whether the server’s TLS certificate and host name should be checked.
ca_file: A PEM file containing the trusted CA certificates. The certificate presented by the server will be verified using these CA certificates. If ca_file parameter is not set, the system-wide CA certificate store is used.
debug: A Boolean flag indicating whether debug output should be generated. If the value is True and the log parameter is not None, the data sent to and received from the server will be written to the log.
Note
User names and passwords are written to the debug log, so handle it with care.
Compression is disabled in debug mode, which means that debug messages are sent as plain text.
log: The logger where the log messages will be written.
kerberos: A Boolean flag indicating whether Kerberos authentication should be used instead of the default basic authentication.
timeout: The maximum total time to wait for the response, in seconds. A value of 0 (default) means to wait forever. If the timeout expires before the response is received, an exception is raised.
compress: A Boolean flag indicating whether the SDK should ask the server to send compressed responses. The default is True. This is a hint for the server, which may return uncompressed data even when this parameter is set to True. Compression is disabled in debug mode, which means that debug messages are sent as plain text.
sso_url: A string containing the base SSO URL of the server. The default SSO URL is computed from the url if no sso_url is provided.
sso_revoke_url: A string containing the base URL of the SSO revoke service. This needs to be specified only when using an external authentication service. By default, this URL is automatically calculated from the value of the url parameter, so that SSO token revoke will be performed using the SSO service, which is part of the Manager.
sso_token_name: The token name in the JSON SSO response returned from the SSO server. Default value is access_token.
headers: A dictionary with headers, which should be sent with every request.
connections: The maximum number of connections to open to the host. If the value is 0 (default), the number of connections is unlimited.
pipeline: The maximum number of requests to put in an HTTP pipeline without waiting for the response. If the value is 0 (default), pipelining is disabled.

import ovirtsdk4 as sdk

# Create a connection to the server:
connection = sdk.Connection(
    url='https://engine.example.com/ovirt-engine/api',
    username='admin@internal',
    password='password',
    ca_file='ca.pem',
)

connection.test()

print("Connected successfully!")

connection.close()

For a full list of supported methods, you can generate the documentation for the ovirtsdk.api module on the Manager machine:

$ pydoc ovirtsdk.api

3.3. Listing Data Centers
Copy link

The datacenters collection contains all the data centers in the environment.

Example 3.1. Listing data centers

This example lists the data centers in the datacenters collection and output some basic information about each data center in the collection.

import ovirtsdk4 as sdk
import ovirtsdk4.types as types

connection = sdk.Connection(
    url='https://engine.example.com/ovirt-engine/api',
    username='admin@internal',
    password='password',
    ca_file='ca.pem',
)

dcs_service = connection.system_service().dcs_service()

dcs = dcs_service.list()

for dc in dcs:
    print("%s (%s)" % (dc.name, dc.id))

connection.close()

In an environment where only the Default data center exists, and it is not activated, the examples output the text:

Default (00000000-0000-0000-0000-000000000000)

3.4. Listing Clusters
Copy link

The clusters collection contains all clusters in the environment.

Example 3.2. Listing clusters

This example lists the clusters in the clusters collection and output some basic information about each cluster in the collection.

import ovirtsdk4 as sdk
import ovirtsdk4.types as types

connection = sdk.Connection(
    url='https://engine.example.com/ovirt-engine/api',
    username='admin@internal',
    password='password',
    ca_file='ca.pem',
)

cls_service = connection.system_service().clusters_service()

cls = cls_service.list()

for cl in cls:
    print("%s (%s)" % (cl.name, cl.id))

connection.close()

In an environment where only the Default cluster exists, the examples output the text:

Default (00000000-0000-0000-0000-000000000000)

3.5. Listing Hosts
Copy link

The hosts collection contains all hosts in the environment.

Example 3.3. Listing hosts

This example lists the hosts in the hosts collection and their IDs.

import ovirtsdk4 as sdk
import ovirtsdk4.types as types

connection = sdk.Connection(
    url='https://engine.example.com/ovirt-engine/api',
    username='admin@internal',
    password='password',
    ca_file='ca.pem',
)

host_service = connection.system_service().hosts_service()

hosts = host_service.list()

for host in hosts:
    print("%s (%s)" % (host.name, host.id))

connection.close()

In an environment where only one host, MyHost, has been attached, the examples output the text:

MyHost (00000000-0000-0000-0000-000000000000)

3.6. Listing Logical Networks
Copy link

The networks collection contains all logical networks in the environment.

Example 3.4. Listing logical networks

This example lists the logical networks in the networks collection and outputs some basic information about each network in the collection.

import ovirtsdk4 as sdk
import ovirtsdk4.types as types

connection = sdk.Connection(
    url='https://engine.example.com/ovirt-engine/api',
    username='admin@internal',
    password='password',
    ca_file='ca.pem',
)

nws_service = connection.system_service().networks_service()

nws = nws_service.list()

for nw in nws:
    print("%s (%s)" % (nw.name, nw.id))

connection.close()

In an environment where only the default management network exists, the examples output the text:

ovirtmgmt (00000000-0000-0000-0000-000000000000)

3.7. Listing Virtual Machines and Total Disk Size
Copy link

The vms collection contains a disks collection that describes the details of each disk attached to a virtual machine.

Example 3.5. Listing virtual machines and total disk size

This example prints a list of virtual machines and their total disk size in bytes:

import ovirtsdk4 as sdk
import ovirtsdk4.types as types

connection = sdk.Connection(
    url='https://engine.example.com/ovirt-engine/api',
    username='admin@internal',
    password='password',
    ca_file='ca.pem',
)

vms_service = connection.system_service().vms_service()

virtual_machines = vms_service.list()

if len(virtual_machines) > 0:

    print("%-30s  %s" % ("Name", "Disk Size"))
    print("==================================================")

    for virtual_machine in virtual_machines:
        vm_service = vms_service.vm_service(virtual_machine.id)
        disk_attachments = vm_service.disk_attachments_service().list()
        disk_size = 0
        for disk_attachment in disk_attachments:
            disk = connection.follow_link(disk_attachment.disk)
            disk_size += disk.provisioned_size

            print("%-30s: %d" % (virtual_machine.name, disk_size))

The examples output the virtual machine names and their disk sizes:

Name                          Disk Size
==================================================
vm1                           50000000000

3.8. Creating NFS Data Storage
Copy link

When a Red Hat Virtualization environment is first created, it is necessary to define at least a data storage domain and an ISO storage domain. The data storage domain stores virtual disks while the ISO storage domain stores the installation media for guest operating systems.

The storagedomains collection contains all the storage domains in the environment and can be used to add and remove storage domains.

Note

The code provided in this example assumes that the remote NFS share has been pre-configured for use with Red Hat Virtualization. See the Administration Guide for more information on preparing NFS shares.

Example 3.6. Creating NFS data storage

This example adds an NFS data domain to the storagedomains collection.

For V4, the add method is used to add the new storage domain and the types class is used to pass the following parameters:

A name for the storage domain.
The data center object that was retrieved from the datacenters collection.
The host object that was retrieved from the hosts collection.
The type of storage domain being added (data, iso, or export).
The storage format to use (v1, v2, or v3).

import ovirtsdk4 as sdk
import ovirtsdk4.types as types

# Create the connection to the server:
connection = sdk.Connection(
    url='https://engine.example.com/ovirt-engine/api',
    username='admin@internal',
    password='password',
    ca_file='ca.pem',
)

# Get the reference to the storage domains service:
sds_service = connection.system_service().storage_domains_service()

# Create a new NFS storage domain:
sd = sds_service.add(
    types.StorageDomain(
        name='mydata',
        description='My data',
        type=types.StorageDomainType.DATA,
        host=types.Host(
            name='myhost',
        ),
        storage=types.HostStorage(
            type=types.StorageType.NFS,
            address='_FQDN_',
            path='/nfs/ovirt/path/to/mydata',
        ),
    ),
)

# Wait until the storage domain is unattached:
sd_service = sds_service.storage_domain_service(sd.id)
while True:
    time.sleep(5)
    sd = sd_service.get()
    if sd.status == types.StorageDomainStatus.UNATTACHED:
        break

print("Storage Domain '%s' added (%s)." % (sd.name(), sd.id()))

connection.close()

If the add method call is successful, the examples output the text:

Storage Domain 'mydata' added (00000000-0000-0000-0000-000000000000).

3.9. Creating NFS ISO Storage
Copy link

To create a virtual machine, you need installation media for the guest operating system. The installation media are stored in an ISO storage domain.

Note

Example 3.7. Creating NFS ISO storage

This example adds an NFS ISO domain to the storagedomains collection.

For V4, the add method is used to add the new storage domain and the types class is used to pass the following parameters:

A name for the storage domain.
The data center object that was retrieved from the datacenters collection.
The host object that was retrieved from the hosts collection.
The type of storage domain being added (data, iso, or export).
The storage format to use (v1, v2, or v3).

import ovirtsdk4 as sdk
import ovirtsdk4.types as types

connection = sdk.Connection(
    url='https://engine.example.com/ovirt-engine/api',
    username='admin@internal',
    password='password',
    ca_file='ca.pem',
)

# Get the reference to the storage domains service:
sds_service = connection.system_service().storage_domains_service()

# Use the "add" method to create a new NFS storage domain:
sd = sds_service.add(
    types.StorageDomain(
        name='myiso',
        description='My ISO',
        type=types.StorageDomainType.ISO,
        host=types.Host(
            name='myhost',
        ),
        storage=types.HostStorage(
            type=types.StorageType.NFS,
            address='FQDN',
            path='/nfs/ovirt/path/to/myiso',
        ),
    ),
)

# Wait until the storage domain is unattached:
sd_service = sds_service.storage_domain_service(sd.id)
while True:
    time.sleep(5)
    sd = sd_service.get()
    if sd.status == types.StorageDomainStatus.UNATTACHED:
        break

print("Storage Domain '%s' added (%s)." % (sd.name(), sd.id()))

# Close the connection to the server:
connection.close()

If the add method call is successful, the examples output the text:

Storage Domain 'myiso' added (00000000-0000-0000-0000-000000000000).

3.10. Attaching a Storage Domain to a Data Center
Copy link

Once you have added a storage domain to Red Hat Virtualization, you must attach it to a data center and activate it before it will be ready for use.

Example 3.8. Attaching a storage domain to a data center

This example attaches an existing NFS storage domain, mydata, to the an existing data center, Default. The attach action is facilitated by the add method of the data center’s storagedomains collection. These examples may be used to attach both data and ISO storage domains.

import ovirtsdk4 as sdk
import ovirtsdk4.types as types

# Create the connection to the server:
connection = sdk.Connection(
    url='https://engine.example.com/ovirt-engine/api',
    username='admin@internal',
    password='password',
    ca_file='ca.pem',
)

# Locate the service that manages the storage domains and use it to
# search for the storage domain:
sds_service = connection.system_service().storage_domains_service()
sd = sds_service.list(search='name=mydata')[0]

# Locate the service that manages the data centers and use it to
# search for the data center:
dcs_service = connection.system_service().data_centers_service()
dc = dcs_service.list(search='name=Default')[0]

# Locate the service that manages the data center where we want to
# attach the storage domain:
dc_service = dcs_service.data_center_service(dc.id)

# Locate the service that manages the storage domains that are attached
# to the data centers:
attached_sds_service = dc_service.storage_domains_service()

# Use the "add" method of service that manages the attached storage
# domains to attach it:
attached_sds_service.add(
    types.StorageDomain(
        id=sd.id,
    ),
)

# Wait until the storage domain is active:
attached_sd_service = attached_sds_service.storage_domain_service(sd.id)
while True:
    time.sleep(5)
    sd = attached_sd_service.get()
    if sd.status == types.StorageDomainStatus.ACTIVE:
        break

print("Attached data storage domain '%s' to data center '%s' (Status: %s)." %
  (sd.name(), dc.name(), sd.status.state()))

# Close the connection to the server:
connection.close()

If the calls to the add methods are successful, the examples output the following text:

Attached data storage domain 'data1' to data center 'Default' (Status: maintenance).

Status: maintenance indicates that the storage domains still need to be activated.

3.11. Activating a Storage Domain
Copy link

Once you have added a storage domain to Red Hat Virtualization and attached it to a data center, you must activate it before it will be ready for use.

Example 3.9. Activating a storage domain

This example activates an NFS storage domain, mydata, attached to the data center, Default. The activate action is facilitated by the activate method of the storage domain.

import ovirtsdk4 as sdk

connection = sdk.Connection
    url='https://engine.example.com/ovirt-engine/api',
    username='admin@internal',
    password='password',
    ca_file='ca.pem',
)

# Locate the service that manages the storage domains and use it to
# search for the storage domain:
sds_service = connection.system_service().storage_domains_service()
sd = sds_service.list(search='name=mydata')[0]

# Locate the service that manages the data centers and use it to
# search for the data center:
dcs_service = connection.system_service().data_centers_service()
dc = dcs_service.list(search='name=Default')[0]

# Locate the service that manages the data center where we want to
# attach the storage domain:
dc_service = dcs_service.data_center_service(dc.id)

# Locate the service that manages the storage domains that are attached
# to the data centers:
attached_sds_service = dc_service.storage_domains_service()

# Activate storage domain:
attached_sd_service = attached_sds_service.storage_domain_service(sd.id)
attached_sd_service.activate()

# Wait until the storage domain is active:
while True:
    time.sleep(5)
    sd = attached_sd_service.get()
    if sd.status == types.StorageDomainStatus.ACTIVE:
        break

print("Attached data storage domain '%s' to data center '%s' (Status: %s)." %
  (sd.name(), dc.name(), sd.status.state()))

# Close the connection to the server:
connection.close()

If the activate requests are successful, the examples output the text:

Activated storage domain 'mydata' in data center 'Default' (Status: active).

Status: active indicates that the storage domains have been activated.

3.12. Listing Files in an ISO Storage Domain
Copy link

The storagedomains collection contains a files collection that describes the files in a storage domain.

Example 3.10. Listing Files in an ISO Storage Domain

This example prints a list of the ISO files in each ISO storage domain:

import ovirtsdk4 as sdk
import ovirtsdk4.types as types

connection = sdk.Connection(
    url='https://engine.example.com/ovirt-engine/api',
    username='admin@internal',
    password='password',
    ca_file='ca.pem',
)

storage_domains_service = connection.system_service().storage_domains_service()

storage_domains = storage_domains_service.list()

for storage_domain in storage_domains:
    if(storage_domain.type == types.StorageDomainType.ISO):
        print(storage_domain.name + ":\n")
        files = storage_domain.files_service().list()

        for file in files:
            print("%s" % file.name + "\n")

connection.close()

The examples output the text:

ISO_storage_domain:
file1
file2

3.13. Creating a Virtual Machine
Copy link

Virtual machine creation is performed in several steps. The first step, covered here, is to create the virtual machine object itself.

Example 3.11. Creating a virtual machine

This example creates a virtual machine, vm1, with the following requirements:

512 MB of memory, expressed in bytes.
Attached to the Default cluster, and therefore the Default data center.
Based on the default Blank template.
Boots from the virtual hard disk drive.

In V4, the options are added as types, using the add method.

import ovirtsdk4 as sdk
import ovirtsdk4.types as types

connection = sdk.Connection(
    url='https://engine.example.com/ovirt-engine/api',
    username='admin@internal',
    password='password',
    ca_file='ca.pem',
)

# Get the reference to the "vms" service:
vms_service = connection.system_service().vms_service()

# Use the "add" method to create a new virtual machine:
vms_service.add(
    types.Vm(
        name='vm1',
        memory = 512*1024*1024
        cluster=types.Cluster(
            name='Default',
        ),
        template=types.Template(
            name='Blank',
        ),
        os=types.OperatingSystem(boot=types.Boot(devices=[types.BootDevice.HD)]
    ),
)

print("Virtual machine '%s' added." % vm.name)

# Close the connection to the server:
connection.close()

If the add request is successful, the examples output the text:

Virtual machine 'vm1' added.

3.14. Creating a Virtual NIC
Copy link

To ensure that a newly created virtual machine has network access, you must create and attach a virtual NIC.

Example 3.12. Creating a virtual NIC

This example creates a NIC, nic1, and attach it to a virtual machine, vm1. The NIC in this example is a virtio network device and attached to the ovirtmgmt management network.

import ovirtsdk4 as sdk
import ovirtsdk4.types as types

connection = sdk.Connection(
    url='https://engine.example.com/ovirt-engine/api',
    username='admin@internal',
    password='password',
    ca_file='ca.pem',
)

# Locate the virtual machines service and use it to find the virtual
# machine:
vms_service = connection.system_service().vms_service()
vm = vms_service.list(search='name=vm1')[0]

# Locate the service that manages the network interface cards of the
# virtual machine:
nics_service = vms_service.vm_service(vm.id).nics_service()

# Locate the vnic profiles service and use it to find the ovirmgmt
# network's profile id:
profiles_service = connection.system_service().vnic_profiles_service()
profile_id = None
for profile in profiles_service.list():
    if profile.name == 'ovirtmgmt':
        profile_id = profile.id
        break

# Use the "add" method of the network interface cards service to add the
# new network interface card:

nic = nics_service.add(
    types.Nic(
        name='nic1',
        interface=types.NicInterface.VIRTIO,
        vnic_profile=types.VnicProfile(id=profile_id),
    ),
)

print("Network interface '%s' added to '%s'." % (nic.name, vm.name))

connection.close()

If the add request is successful, the examples output the text:

Network interface 'nic1' added to 'vm1'.

3.15. Creating a Virtual Machine Disk
Copy link

To ensure that a newly created virtual machine has access to persistent storage, you must create and attach a disk.

Example 3.13. Creating a virtual machine disk

This example creates an 8 GB virtio disk and attach it to a virtual machine, vm1. The disk has the following requirements:

Stored on the storage domain named data1.
8 GB in size.
system type disk (as opposed to data).
virtio storage device.
COW format.
Marked as a usable boot device.

import ovirtsdk4 as sdk
import ovirtsdk4.types as types

connection = sdk.Connection(
    url='https://engine.example.com/ovirt-engine/api',
    username='admin@internal',
    password='password',
    ca_file='ca.pem',
)

# Locate the virtual machines service and use it to find the virtual
# machine:
vms_service = connection.system_service().vms_service()
vm = vms_service.list(search='name=vm1')[0]

# Locate the service that manages the disk attachments of the virtual
# machine:
disk_attachments_service = vms_service.vm_service(vm.id).disk_attachments_service()

# Use the "add" method of the disk attachments service to add the disk.
# Note that the size of the disk, the `provisioned_size` attribute, is
# specified in bytes, so to create a disk of 10 GiB the value should
# be 10 * 2^30.
disk_attachment = disk_attachments_service.add(
    types.DiskAttachment(
        disk=types.Disk(
            format=types.DiskFormat.COW,
            provisioned_size=8*1024*1024,
            storage_domains=[
                types.StorageDomain(
                    name='data1',
                ),
            ],
        ),
        interface=types.DiskInterface.VIRTIO,
        bootable=True,
        active=True,
    ),
)

# Wait until the disk status is OK:
disks_service = connection.system_service().disks_service()
disk_service = disks_service.disk_service(disk_attachment.disk.id)
while True:
    time.sleep(5)
    disk = disk_service.get()
    if disk.status == types.DiskStatus.OK:
        break

print("Disk '%s' added to '%s'." % (disk.name(), vm.name()))

# Close the connection to the server:
connection.close()

If the add request is successful, the examples output the text:

Disk 'vm1_Disk1' added to 'vm1'.

3.16. Attaching an ISO Image to a Virtual Machine
Copy link

To install a guest operating system on a newly created virtual machine, you must attach an ISO file containing the operating system installation media. To locate the ISO file, see Listing Files in an ISO Storage Domain.

Example 3.14. Attaching an ISO image to a virtual machine

This example attaches my_iso_file.iso to the vm1 virtual machine, using the add method of the virtual machine’s cdroms collection.

import ovirtsdk4 as sdk
import ovirtsdk4.types as types

connection = sdk.Connection(
    url='https://engine.example.com/ovirt-engine/api',
    username='admin@internal',
    password='password',
    ca_file='ca.pem',
)

# Get the reference to the "vms" service:
vms_service = connection.system_service().vms_service()

# Find the virtual machine:
vm = vms_service.list(search='name=vm1')[0]

# Locate the service that manages the virtual machine:
vm_service = vms_service.vm_service(vm.id)

# Locate the service that manages the CDROM devices of the virtual machine:
cdroms_service = vm_service.cdroms_service()

# Get the first CDROM:
cdrom = cdroms_service.list()[0]

# Locate the service that manages the CDROM device found in previous step:
cdrom_service = cdroms_service.cdrom_service(cdrom.id)

# Change the CD of the VM to 'my_iso_file.iso'. By default the
# operation permanently changes the disk that is visible to the
# virtual machine after the next boot, but has no effect
# on the currently running virtual machine. If you want to change the
# disk that is visible to the current running virtual machine, change
# the `current` parameter's value to `True`.
cdrom_service.update(
    cdrom=types.Cdrom(
        file=types.File(
            id='my_iso_file.iso'
        ),
    ),
    current=False,
)

print("Attached CD to '%s'." % vm.name())

# Close the connection to the server:
connection.close()

If the add request is successful, the examples output the text:

Attached CD to 'vm1'.

Example 3.15. Ejecting a cdrom from a virtual machine

This example ejects an ISO image from a virtual machine’s cdrom collection.

import ovirtsdk4 as sdk
import ovirtsdk4.types as types

connection = sdk.Connection(
    url='https://engine.example.com/ovirt-engine/api',
    username='admin@internal',
    password='password',
    ca_file='ca.pem',
)

# Get the reference to the "vms" service:
vms_service = connection.system_service().vms_service()

# Find the virtual machine:
vm = vms_service.list(search='name=vm1')[0]

# Locate the service that manages the virtual machine:
vm_service = vms_service.vm_service(vm.id)

# Locate the service that manages the CDROM devices of the VM:
cdroms_service = vm_service.cdroms_service()

# Get the first found CDROM:
cdrom = cdroms_service.list()[0]

# Locate the service that manages the CDROM device found in previous step
# of the VM:
cdrom_service = cdroms_service.cdrom_service(cdrom.id)

cdrom_service.remove()

print("Removed CD from '%s'." % vm.name())

connection.close()

If the delete or remove request is successful, the examples output the text:

Removed CD from 'vm1'.

3.17. Detaching a Disk
Copy link

You can detach a disk from a virtual machine.

Detaching a disk

import ovirtsdk4 as sdk
import ovirtsdk4.types as types

connection = sdk.Connection(
    url='https://engine.example.com/ovirt-engine/api',
    username='admin@internal',
    password='password',
    ca_file='ca.pem',
)

# Get the reference to the "vms" service:
vms_service = connection.system_service().vms_service()

# Find the virtual machine:
vm = vms_service.list(search='name=vm1')[0]

# Locate the service that manages the virtual machine:
vm_service = vms_service.vm_service(vm.id)

attachments_service = vm_service.disk_attachments_service()
attachment = next(
    (a for a in disk_attachments if a.disk.id == disk.id), None
)

# Remove the attachment. The default behavior is that the disk is detached
# from the virtual machine, but not deleted from the system. If you wish to
# delete the disk, change the detach_only parameter to "False".
attachment.remove(detach_only=True)

print("Detached disk %s successfully!" % attachment)

# Close the connection to the server:
connection.close()

If the delete or remove request is successful, the examples output the text:

Detached disk vm1_disk1 successfully!

3.18. Starting a Virtual Machine
Copy link

You can start a virtual machine.

Example 3.16. Starting a virtual machine

This example starts the virtual machine using the start method.

import time
import ovirtsdk4 as sdk
import ovirtsdk4.types as types

connection = sdk.Connection(
    url='https://engine.example.com/ovirt-engine/api',
    username='admin@internal',
    password='password',
    ca_file='ca.pem',
)

# Get the reference to the "vms" service:
vms_service = connection.system_service().vms_service()

# Find the virtual machine:
vm = vms_service.list(search='name=vm1')[0]

# Locate the service that manages the virtual machine, as that is where
# the action methods are defined:
vm_service = vms_service.vm_service(vm.id)

# Call the "start" method of the service to start it:
vm_service.start()

# Wait until the virtual machine is up:
while True:
    time.sleep(5)
    vm = vm_service.get()
    if vm.status == types.VmStatus.UP:
        break

print("Started '%s'." % vm.name())

# Close the connection to the server:
connection.close()

If the start request is successful, the examples output the text:

Started 'vm1'.

The UP status indicates that the virtual machine is running.

3.19. Starting a Virtual Machine with Overridden Parameters
Copy link

You can start a virtual machine, overriding its default parameters.

Example 3.17. Starting a virtual machine with overridden parameters

This example boots a virtual machine with a Windows ISO and attach the virtio-win_x86.vfd floppy disk, which contains Windows drivers. This action is equivalent to using the Run Once window in the Administration Portal to start a virtual machine.

import time
import ovirtsdk4 as sdk
import ovirtsdk4.types as types

connection = sdk.Connection(
    url='https://engine.example.com/ovirt-engine/api',
    username='admin@internal',
    password='password',
    ca_file='ca.pem',
)

# Get the reference to the "vms" service:
vms_service = connection.system_service().vms_service()

# Find the virtual machine:
vm = vms_service.list(search='name=vm1')[0]

# Locate the service that manages the virtual machine:
vm_service = vms_service.vm_service(vm.id)

# Locate the service that manages the CDROM devices of the virtual machine:
cdroms_service = vm_service.cdroms_service()

# Get the first CDROM:
cdrom = cdroms_service.list()[0]

# Locate the service that manages the CDROM device found in previous step:
cdrom_service = cdroms_service.cdrom_service(cdrom.id)

# Change the CD of the VM to 'windows_example.iso':
cdrom_service.update(
    cdrom=types.Cdrom(
        file=types.File(
            id='windows_example.iso'
        ),
    ),
    current=False,
)

# Call the "start" method of the service to start it:
vm_service.start(
    vm=types.Vm(
        os=types.OperatingSystem(
            boot=types.Boot(
                devices=[
                    types.BootDevice.CDROM,
                ]
            )
        ),
    )
)

# Wait until the virtual machine's status is "UP":
while True:
    time.sleep(5)
    vm = vm_service.get()
    if vm.status == types.VmStatus.UP:
        break

print("Started '%s'." % vm.name())

# Close the connection to the server:
connection.close()

Note

The CD image and floppy disk file must be available to the virtual machine. See Uploading Images to a Data Storage Domain for details.

3.20. Starting a Virtual Machine with Cloud-Init
Copy link

You can start a virtual machine with a specific configuration, using the Cloud-Init tool.

Example 3.18. Starting a virtual machine with Cloud-Init

This example shows you how to start a virtual machine using the Cloud-Init tool to set a host name and a static IP for the eth0 interface.

import ovirtsdk4 as sdk
import ovirtsdk4.types as types

connection = sdk.Connection(
    url='https://engine.example.com/ovirt-engine/api',
    username='admin@internal',
    password='password',
    ca_file='ca.pem',
)

# Find the virtual machine:
vms_service = connection.system_service().vms_service()
vm = vms_service.list(search = 'name=vm1')[0]

# Find the service that manages the virtual machine:
vm_service = vms_service.vm_service(vm.id)

# Start the virtual machine enabling cloud-init and providing the
# password for the `root` user and the network configuration:
vm_service.start(
    use_cloud_init=True,
    vm=types.Vm(
        initialization=types.Initialization(
        user_name='root',
        root_password='password',
        host_name='MyHost.example.com',
        nic_configurations=[
            types.NicConfiguration(
                name='eth0',
                on_boot=True,
                boot_protocol=types.BootProtocol.STATIC,
                ip=types.Ip(
                    version=types.IpVersion.V4,
                    address='10.10.10.1',
                    netmask='255.255.255.0',
                    gateway='10.10.10.1'
                )
            )
        )
    )
)

# Close the connection to the server:
connection.close()

3.21. Checking System Events
Copy link

Red Hat Virtualization Manager records and logs many system events. These event logs are accessible through the user interface, the system log files, and using the API. The ovirtsdk library exposes events using the events collection.

Example 3.19. Checking system events

In this example the events collection is listed.

The query parameter of the list method is used to ensure that all available pages of results are returned. By default the list method returns only the first page of results, which is 100 records in length.

The returned list is sorted in reverse chronological order, to display the events in the order in which they occurred.

import ovirtsdk4 as sdk
import ovirtsdk4.types as types

connection = sdk.Connection(
    url='https://engine.example.com/ovirt-engine/api',
    username='admin@internal',
    password='password',
    ca_file='ca.pem',
)

# Find the service that manages the collection of events:
events_service = connection.system_service().events_service()

page_number = 1
events = events_service.list(search='page %s' % page_number)
while events:
    for event in events:
        print(
            "%s %s CODE %s - %s" % (
                event.time,
                event.severity,
                event.code,
                event.description,
            )
        )
    page_number = page_number + 1
    events = events_service.list(search='page %s' % page_number)

# Close the connection to the server:
connection.close()

These examples output events in the following format:

YYYY-MM-DD_T_HH:MM:SS NORMAL CODE 30 - User admin@internal logged in.
YYYY-MM-DD_T_HH:MM:SS NORMAL CODE 153 - VM vm1 was started by admin@internal (Host: MyHost).
YYYY-MM-DD_T_HH:MM:SS NORMAL CODE 30 - User admin@internal logged in.

Chapter 3. Python Examples

3.1. Overview
Copy link

3.2. Connecting to the Red Hat Virtualization Manager in Version 4
Copy link

3.3. Listing Data Centers
Copy link

3.4. Listing Clusters
Copy link

3.5. Listing Hosts
Copy link

3.6. Listing Logical Networks
Copy link

3.7. Listing Virtual Machines and Total Disk Size
Copy link

3.8. Creating NFS Data Storage
Copy link

3.9. Creating NFS ISO Storage
Copy link

3.10. Attaching a Storage Domain to a Data Center
Copy link

3.11. Activating a Storage Domain
Copy link

3.12. Listing Files in an ISO Storage Domain
Copy link

3.13. Creating a Virtual Machine
Copy link

3.14. Creating a Virtual NIC
Copy link

3.15. Creating a Virtual Machine Disk
Copy link

3.16. Attaching an ISO Image to a Virtual Machine
Copy link

3.17. Detaching a Disk
Copy link

3.18. Starting a Virtual Machine
Copy link

3.19. Starting a Virtual Machine with Overridden Parameters
Copy link

3.20. Starting a Virtual Machine with Cloud-Init
Copy link

3.21. Checking System Events
Copy link

Learn

Try, buy, & sell

Communities

About Red Hat Documentation

Making open source more inclusive

About Red Hat

Theme

Red Hat legal and privacy links

Red Hat legal and privacy links

Chapter 3. Python Examples

3.1. OverviewCopy linkLink copied to clipboard!

3.2. Connecting to the Red Hat Virtualization Manager in Version 4Copy linkLink copied to clipboard!

3.3. Listing Data CentersCopy linkLink copied to clipboard!

3.4. Listing ClustersCopy linkLink copied to clipboard!

3.5. Listing HostsCopy linkLink copied to clipboard!

3.6. Listing Logical NetworksCopy linkLink copied to clipboard!

3.7. Listing Virtual Machines and Total Disk SizeCopy linkLink copied to clipboard!

3.8. Creating NFS Data StorageCopy linkLink copied to clipboard!

3.9. Creating NFS ISO StorageCopy linkLink copied to clipboard!

3.10. Attaching a Storage Domain to a Data CenterCopy linkLink copied to clipboard!

3.11. Activating a Storage DomainCopy linkLink copied to clipboard!

3.12. Listing Files in an ISO Storage DomainCopy linkLink copied to clipboard!

3.13. Creating a Virtual MachineCopy linkLink copied to clipboard!

3.14. Creating a Virtual NICCopy linkLink copied to clipboard!

3.15. Creating a Virtual Machine DiskCopy linkLink copied to clipboard!

3.16. Attaching an ISO Image to a Virtual MachineCopy linkLink copied to clipboard!

3.17. Detaching a DiskCopy linkLink copied to clipboard!

3.18. Starting a Virtual MachineCopy linkLink copied to clipboard!

3.19. Starting a Virtual Machine with Overridden ParametersCopy linkLink copied to clipboard!

3.20. Starting a Virtual Machine with Cloud-InitCopy linkLink copied to clipboard!

3.21. Checking System EventsCopy linkLink copied to clipboard!

Learn

Try, buy, & sell

Communities

About Red Hat Documentation

Making open source more inclusive

About Red Hat

Theme

Red Hat legal and privacy links

Red Hat legal and privacy links

3.1. Overview
Copy link

3.2. Connecting to the Red Hat Virtualization Manager in Version 4
Copy link

3.3. Listing Data Centers
Copy link

3.4. Listing Clusters
Copy link

3.5. Listing Hosts
Copy link

3.6. Listing Logical Networks
Copy link

3.7. Listing Virtual Machines and Total Disk Size
Copy link

3.8. Creating NFS Data Storage
Copy link

3.9. Creating NFS ISO Storage
Copy link

3.10. Attaching a Storage Domain to a Data Center
Copy link

3.11. Activating a Storage Domain
Copy link

3.12. Listing Files in an ISO Storage Domain
Copy link

3.13. Creating a Virtual Machine
Copy link

3.14. Creating a Virtual NIC
Copy link

3.15. Creating a Virtual Machine Disk
Copy link

3.16. Attaching an ISO Image to a Virtual Machine
Copy link

3.17. Detaching a Disk
Copy link

3.18. Starting a Virtual Machine
Copy link

3.19. Starting a Virtual Machine with Overridden Parameters
Copy link

3.20. Starting a Virtual Machine with Cloud-Init
Copy link

3.21. Checking System Events
Copy link