Update 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.


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

In the following example, the service locator method locates the service managing the virtual machine and the update method updates its name:

Updating a Virtual Machine Name

# Find the virtual machine and the service that
# manages it:
vm = vms_service.list(search: 'name=myvm').first
vm_service = vms_service.vm_service(vm.id)

# Update the name:
updated_vm = vms_service.update(
    name: 'newvm'

When you update an object, update only the attributes you want to update:

Updating a Selected Attribute of a Virtual Machine (Recommended)

vm = vm_service.get
vm.name = 'newvm'

Do not update the entire object:

Updating All Attributes of a Virtual Machine (Not Recommended)

# Retrieve the current representation:

Updating all attributes of the virtual machine is a waste of resources and can introduce unexpected bugs on the server side.

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

Updating the Memory of a Virtual Machine at Next Run

vm = vm_service.update(
    memory: 1073741824
  next_run: true

If the update cannot be performed, the SDK will raise an Error exception containing the details of the failure. It will never return nil.