Chapter 2. Using the Software Development Kit

These service methods are used to retrieve the representation of a single object. The following example retrieves the representation of the virtual machine with identifier 123:

# Find the service that manages the virtual machine:
vms_service = system_service.vms_service()
vm_service = vms_service.vm_service('123')

# Retrieve the representation of the virtual machine:
vm = vm_service.get()

The response is an instance of the corresponding type, in this case an instance of the Python class ovirtsdk4.types.Vm.

The get methods of some services support additional parameters that control how to retrieve the representation of the object or what representation to retrieve if there is more than one. For example, you may want to retrieve either the current state of a virtual machine or its state the next time it is started, as they may be different. The get method of the service that manages a virtual machine supports a next_run Boolean parameter:

# Retrieve the representation of the virtual machine, not the
# current one, but the one that will be used after the next
# boot:
vm = vm_service.get(next_run=True)

See the reference documentation of the SDK for details.

If the object cannot be retrieved for any reason, the SDK raises an ovirtsdk4.Error exception, with details of the failure. This includes the situation when the object does not actually exist. Note that the exception is raised when calling the get service method. The call to the service locator method never fails, even if the object does not exist, because that call does not send a request to the server. For example:

# Call the service that manages a non-existent virtual machine.
# This call will succeed.
vm_service = vms_service.vm_service('junk')

# Retrieve the virtual machine. This call will raise an exception.
vm = vm_service.get()

These service methods retrieve the representations of the objects of a collection. This example retrieves the complete collection of virtual machines of the system:

# Find the service that manages the collection of virtual
# machines:
vms_service = system_service.vms_service()

# List the virtual machines in the collection
vms = vms_service.list()

The result will be a Python list containing the instances of corresponding types. For example, in this case, the result will be a list of instances of the class ovirtsdk4.types.Vm.

The list methods of some services support additional parameters. For example, almost all top-level collections support a search parameter to filter the results or a max parameter to limit the number of results returned by the server. This example retrieves the names of virtual machines starting with my, with an upper limit of 10 results:

vms = vms_service.list(search='name=my*', max=10)

If a list of returned results is empty for any reason, the returned value will be an empty list. It will never be None.

If there is an error while trying to retrieve the result, the SDK will raise an ovirtsdk4.Error exception containing the details of the failure.

These service methods add new elements to a collection. They receive an instance of the relevant type describing the object to add, send the request to add it, and return an instance of the type describing the added object.

This example adds a new virtual machine called vm1:

from ovirtsdk4 import types

# Add the virtual machine:
vm = vms_service.add(
    vm=types.Vm(
        name='vm1',
        cluster=types.Cluster(
            name='Default'
        ),
        template=types.Template(
            name='mytemplate'
        )
    )
)

If the object cannot be created for any reason, the SDK will raise an ovirtsdk4.Error exception containing the details of the failure. It will never return None.

# Add the virtual machine:
vm = vms_service.add(
  ...
)

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

# Start the virtual machine
vm_service.start()

Objects are created asynchronously. When you create a new virtual machine, the add method will return a response before the virtual machine is completely created and ready to be used. It is good practice to poll the status of the object to ensure that it is completely created. For a virtual machine, you should check until its status is DOWN:

# Add the virtual machine:
vm = vms_service.add(
  ...
)

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

# Wait until the virtual machine is down, indicating that it is
# completely created:
while True:
    time.sleep(5)
    vm = vm_service.get()
    if vm.status == types.VmStatus.DOWN:
        break

Using a loop to retrieve the object status, with the get method, ensures that the status attribute is updated.

These service methods update existing objects. They receive an instance of the relevant type describing the update to perform, send the request to update it, and return an instance of the type describing the updated object.

This example updates the name of a virtual machine from vm1 to newvm:

from ovirtsdk4 import types

# Find the virtual machine, and then the service that
# manages it:
vm = vms_service.list(search='name=vm1')[0]
vm_service = vm_service.vm_service(vm.id)

# Update the name:
updated_vm = vm_service.update(
    vm=types.Vm(
        name='newvm'
    )
)

When performing updates, avoid sending the complete representation of the object. Send only the attributes that you want to update. Do not do this:

# Retrieve the complete representation:
vm = vm_service.get()

# Update the representation, in memory, without sending a request
# to the server:
vm.name = 'newvm'

# Send the update. Do *not* do this.
vms_service.update(vm)

Sending the complete representation causes two problems:

The update methods of some services support additional parameters that control how or what to update. For example, you may want to update either the current state of a virtual machine or the state that will be used the next time the virtual machine is started. The update method of the service that manages a virtual machine supports a next_run Boolean parameter:

# Update the memory of the virtual machine to 1 GiB,
# not during the current run, but after next boot:
vm = vm_service.update(
    vm=types.Vm(
        memory=1073741824
    ),
    next_run=True
)

If the update cannot be performed for any reason, the SDK will raise an ovirtsdk4.Error exception containing the details of the failure. It will never return None.

The Python object returned by this update method is an instance of the relevant type. It is not a service, but a container for data. In this particular example, the returned object will be an instance of the ovirtsdk4.types.Vm class.

These service methods remove existing objects. They usually do not take parameters, because they are methods of services that manage single objects. Therefore, the service already knows what object to remove.

This example removes the virtual machine with identifier 123:

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

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

# Remove the virtual machine:
vm_service.remove()

The remove methods of some services support additional parameters that control how or what to remove. For example, it is possible to remove a virtual machine while preserving its disks, using the detach_only Boolean parameter:

# Remove the virtual machine while preserving the disks:
vm_service.remove(detach_only=True)

The remove method returns None if the object is removed successfully. It does not return the removed object. If the object cannot be removed for any reason, the SDK raises an ovirtsdk4.Error exception containing the details of the failure.

There are other service methods that perform miscellaneous operations, such as stopping and starting a virtual machine:

# Start the virtual machine:
vm_service.start()

Many of these methods include parameters that modify the operation. For example, the method that starts a virtual machine supports a use_cloud_init parameter, if you want to start it using cloud-init:

# Start the virtual machine:
vm_service.start(cloud_init=True)

Most action methods return None when they succeed and raise an ovirtsdk4.Error when they fail. A few action methods return values. For example, the service that manages a storage domain has an is_attached action method that checks whether the storage domain is already attached to a data center and returns a Boolean value:

# Check if the storage domain is attached to a data center:
sds_service = system_service.storage_domains_service()
sd_service = sds_service.storage_domain_service('123')
if sd_service.is_attached():
    ...

Check the reference documentation of the SDK to see the action methods supported by each service, the parameters that they take, and the values that they return.