RubyDoc.info: Class: OvirtSDK4::VmsService – Documentation for ovirt-engine-sdk (4.6.1)

#add(vm, opts = {}) ⇒ `Vm`

Creates a new virtual machine.

The virtual machine can be created in different ways:

From a template. In this case the identifier or name of the template must be provided. For example, using a plain shell script and XML:

#!/bin/sh -ex

url="https://engine.example.com/ovirt-engine/api"
user="admin@internal"
password="..."
curl \
--verbose \
--cacert /etc/pki/ovirt-engine/ca.pem \
--user "${user}:${password}" \
--request POST \
--header "Version: 4" \
--header "Content-Type: application/xml" \
--header "Accept: application/xml" \
--data '
<vm>
  <name>myvm</name>
  <template>
    <name>Blank</name>
  </template>
  <cluster>
    <name>mycluster</name>
  </cluster>
</vm>
' \
"${url}/vms"

From a snapshot. In this case the identifier of the snapshot has to be provided. For example, using a plain shel script and XML:

#!/bin/sh -ex

url="https://engine.example.com/ovirt-engine/api"
user="admin@internal"
password="..."
curl \
--verbose \
--cacert /etc/pki/ovirt-engine/ca.pem \
--user "${user}:${password}" \
--request POST \
--header "Content-Type: application/xml" \
--header "Accept: application/xml" \
--data '
<vm>
  <name>myvm</name>
  <snapshots>
    <snapshot id="266742a5-6a65-483c-816d-d2ce49746680"/>
  </snapshots>
  <cluster>
    <name>mycluster</name>
  </cluster>
</vm>
' \
"${url}/vms"

When creating a virtual machine from a template or from a snapshot it is usually useful to explicitly indicate in what storage domain to create the disks for the virtual machine. If the virtual machine is created from a template then this is achieved passing a set of disk_attachment elements that indicate the mapping:

<vm>
  ...
  <disk_attachments>
    <disk_attachment>
      <disk id="8d4bd566-6c86-4592-a4a7-912dbf93c298">
        <storage_domains>
          <storage_domain id="9cb6cb0a-cf1d-41c2-92ca-5a6d665649c9"/>
        </storage_domains>
      </disk>
    <disk_attachment>
  </disk_attachments>
</vm>

When the virtual machine is created from a snapshot this set of disks is slightly different, it uses the image_id attribute instead of id.

<vm>
  ...
  <disk_attachments>
    <disk_attachment>
      <disk>
        <image_id>8d4bd566-6c86-4592-a4a7-912dbf93c298</image_id>
        <storage_domains>
          <storage_domain id="9cb6cb0a-cf1d-41c2-92ca-5a6d665649c9"/>
        </storage_domains>
      </disk>
    <disk_attachment>
  </disk_attachments>
</vm>

It is possible to specify additional virtual machine parameters in the XML description, e.g. a virtual machine of desktop type, with 2 GiB of RAM and additional description can be added sending a request body like the following:

<vm>
  <name>myvm</name>
  <description>My Desktop Virtual Machine</description>
  <type>desktop</type>
  <memory>2147483648</memory>
  ...
</vm>

A bootable CDROM device can be set like this:

<vm>
  ...
  <os>
    <boot dev="cdrom"/>
  </os>
</vm>

In order to boot from CDROM, you first need to insert a disk, as described in the CDROM service. Then booting from that CDROM can be specified using the os.boot.devices attribute:

<vm>
  ...
  <os>
    <boot>
      <devices>
        <device>cdrom</device>
      </devices>
    </boot>
  </os>
</vm>

In all cases the name or identifier of the cluster where the virtual machine will be created is mandatory.

Parameters:

vm (Vm) —

The vm to add.
opts (Hash) (defaults to: {}) —

Additional options.

Options Hash (opts):

:clone (Boolean) —
Specifies if the virtual machine should be independent of the template.

When a virtual machine is created from a template by default the disks of the virtual machine depend on the disks of the template, they are using the copy on write mechanism so that only the differences from the template take up real storage space. If this parameter is specified and the value is true then the disks of the created virtual machine will be cloned, and independent of the template. For example, to create an independent virtual machine, send a request like this:
```
POST /ovirt-engine/vms?clone=true HTTP/1.1
```
With a request body like this:
```
<vm>
  <name>myvm<name>
  <template>
    <name>mytemplate<name>
  </template>
  <cluster>
    <name>mycluster<name>
  </cluster>
</vm>
```
Note
When this parameter is true the permissions of the template will also be copied, as when using clone_permissions=true.
:clone_permissions (Boolean) —
Specifies if the permissions of the template should be copied to the virtual machine.

If this optional parameter is provided, and its values is true then the permissions of the template (only the direct ones, not the inherited ones) will be copied to the created virtual machine. For example, to create a virtual machine from the mytemplate template copying its permissions, send a request like this:
```
POST /ovirt-engine/api/vms?clone_permissions=true HTTP/1.1
```
With a request body like this:
```
<vm>
  <name>myvm<name>
  <template>
    <name>mytemplate<name>
  </template>
  <cluster>
    <name>mycluster<name>
  </cluster>
</vm>
```

:filter (Boolean) —

Relevant for admin users only. Indicates whether to assign UserVmManager role on the created Virtual Machine for this user. This will enable the user to later access the Virtual Machine as though he were a non-admin user, foregoing his admin permissions (by providing filter=true).

Note	admin-as-user (meaning providing filter=true) POST requests on an existing Virtual Machine will fail unless the Virtual Machine has been previously created by the admin as a user (meaning with filter=true).

:seal (Boolean) —
Specifies if the virtual machine should be sealed after creation.

If this optional parameter is provided, and its value is true, the virtual machine will be sealed after creation. If the value is 'false', the virtual machine will not be sealed. If the parameter is not provided, the virtual machine will be sealed, only if it is created from a sealed template and its guest OS is not set to Windows.

For example, to create a virtual machine from the mytemplate template and to seal it, send a request like this:
```
POST /ovirt-engine/api/vms?seal=true HTTP/1.1
```
With a request body like this:
```
<vm>
  <name>myvm<name>
  <template>
    <name>mytemplate<name>
  </template>
  <cluster>
    <name>mycluster<name>
  </cluster>
</vm>
```
:headers (Hash) — default: {} —

Additional HTTP headers.
:query (Hash) — default: {} —

Additional URL query parameters.
:timeout (Integer) — default: nil —

The timeout for this request, in seconds. If no value is explicitly given then the timeout set globally for the connection will be used.
:wait (Boolean) — default: true —

If true wait for the response.

Returns:

(Vm)



35426
35427
35428

# File 'lib/ovirtsdk4/services.rb', line 35426

def add(vm, opts = {})
  internal_add(vm, Vm, ADD, opts)
end

#add_from_configuration(vm, opts = {}) ⇒ `Vm`

add a virtual machine to the system from a configuration - requires the configuration type and the configuration data

Parameters:

vm (Vm) —

The vm to add.
opts (Hash) (defaults to: {}) —

Additional options.

Options Hash (opts):

:clone (Boolean) —
Specifies if the virtual machine should be independent of the template.

When a virtual machine is created from a template by default the disks of the virtual machine depend on the disks of the template, they are using the copy on write mechanism so that only the differences from the template take up real storage space. If this parameter is specified and the value is true then the disks of the created virtual machine will be cloned, and independent of the template. For example, to create an independent virtual machine, send a request like this:
```
POST /ovirt-engine/vms?clone=true HTTP/1.1
```
With a request body like this:
```
<vm>
  <name>myvm<name>
  <template>
    <name>mytemplate<name>
  </template>
  <cluster>
    <name>mycluster<name>
  </cluster>
</vm>
```
Note
When this parameter is true the permissions of the template will also be copied, as when using clone_permissions=true.
:clone_permissions (Boolean) —
Specifies if the permissions of the template should be copied to the virtual machine.

If this optional parameter is provided, and its values is true then the permissions of the template (only the direct ones, not the inherited ones) will be copied to the created virtual machine. For example, to create a virtual machine from the mytemplate template copying its permissions, send a request like this:
```
POST /ovirt-engine/api/vms?clone_permissions=true HTTP/1.1
```
With a request body like this:
```
<vm>
  <name>myvm<name>
  <template>
    <name>mytemplate<name>
  </template>
  <cluster>
    <name>mycluster<name>
  </cluster>
</vm>
```

:filter (Boolean) —

Relevant for admin users only. Indicates whether to assign UserVmManager role on the created Virtual Machine for this user. This will enable the user to later access the Virtual Machine as though he were a non-admin user, foregoing his admin permissions (by providing filter=true).

Note	admin-as-user (meaning providing filter=true) POST requests on an existing Virtual Machine will fail unless the Virtual Machine has been previously created by the admin as a user (meaning with filter=true).

:seal (Boolean) —
Specifies if the virtual machine should be sealed after creation.

If this optional parameter is provided, and its value is true, the virtual machine will be sealed after creation. If the value is 'false', the virtual machine will not be sealed. If the parameter is not provided, the virtual machine will be sealed, only if it is created from a sealed template and its guest OS is not set to Windows.

For example, to create a virtual machine from the mytemplate template and to seal it, send a request like this:
```
POST /ovirt-engine/api/vms?seal=true HTTP/1.1
```
With a request body like this:
```
<vm>
  <name>myvm<name>
  <template>
    <name>mytemplate<name>
  </template>
  <cluster>
    <name>mycluster<name>
  </cluster>
</vm>
```
:headers (Hash) — default: {} —

Additional HTTP headers.
:query (Hash) — default: {} —

Additional URL query parameters.
:timeout (Integer) — default: nil —

The timeout for this request, in seconds. If no value is explicitly given then the timeout set globally for the connection will be used.
:wait (Boolean) — default: true —

If true wait for the response.

Returns:

(Vm)



35547
35548
35549

# File 'lib/ovirtsdk4/services.rb', line 35547

def add_from_configuration(vm, opts = {})
  internal_add(vm, Vm, ADD_FROM_CONFIGURATION, opts)
end

#add_from_scratch(vm, opts = {}) ⇒ `Vm`

add a virtual machine to the system from scratch

Parameters:

vm (Vm) —

The vm to add.
opts (Hash) (defaults to: {}) —

Additional options.

Options Hash (opts):

:clone (Boolean) —
Specifies if the virtual machine should be independent of the template.

When a virtual machine is created from a template by default the disks of the virtual machine depend on the disks of the template, they are using the copy on write mechanism so that only the differences from the template take up real storage space. If this parameter is specified and the value is true then the disks of the created virtual machine will be cloned, and independent of the template. For example, to create an independent virtual machine, send a request like this:
```
POST /ovirt-engine/vms?clone=true HTTP/1.1
```
With a request body like this:
```
<vm>
  <name>myvm<name>
  <template>
    <name>mytemplate<name>
  </template>
  <cluster>
    <name>mycluster<name>
  </cluster>
</vm>
```
Note
When this parameter is true the permissions of the template will also be copied, as when using clone_permissions=true.
:clone_permissions (Boolean) —
Specifies if the permissions of the template should be copied to the virtual machine.

If this optional parameter is provided, and its values is true then the permissions of the template (only the direct ones, not the inherited ones) will be copied to the created virtual machine. For example, to create a virtual machine from the mytemplate template copying its permissions, send a request like this:
```
POST /ovirt-engine/api/vms?clone_permissions=true HTTP/1.1
```
With a request body like this:
```
<vm>
  <name>myvm<name>
  <template>
    <name>mytemplate<name>
  </template>
  <cluster>
    <name>mycluster<name>
  </cluster>
</vm>
```

:filter (Boolean) —

Relevant for admin users only. Indicates whether to assign UserVmManager role on the created Virtual Machine for this user. This will enable the user to later access the Virtual Machine as though he were a non-admin user, foregoing his admin permissions (by providing filter=true).

Note	admin-as-user (meaning providing filter=true) POST requests on an existing Virtual Machine will fail unless the Virtual Machine has been previously created by the admin as a user (meaning with filter=true).

:seal (Boolean) —
Specifies if the virtual machine should be sealed after creation.

If this optional parameter is provided, and its value is true, the virtual machine will be sealed after creation. If the value is 'false', the virtual machine will not be sealed. If the parameter is not provided, the virtual machine will be sealed, only if it is created from a sealed template and its guest OS is not set to Windows.

For example, to create a virtual machine from the mytemplate template and to seal it, send a request like this:
```
POST /ovirt-engine/api/vms?seal=true HTTP/1.1
```
With a request body like this:
```
<vm>
  <name>myvm<name>
  <template>
    <name>mytemplate<name>
  </template>
  <cluster>
    <name>mycluster<name>
  </cluster>
</vm>
```
:headers (Hash) — default: {} —

Additional HTTP headers.
:query (Hash) — default: {} —

Additional URL query parameters.
:timeout (Integer) — default: nil —

The timeout for this request, in seconds. If no value is explicitly given then the timeout set globally for the connection will be used.
:wait (Boolean) — default: true —

If true wait for the response.

Returns:

(Vm)



35668
35669
35670

# File 'lib/ovirtsdk4/services.rb', line 35668

def add_from_scratch(vm, opts = {})
  internal_add(vm, Vm, ADD_FROM_SCRATCH, opts)
end

#add_from_snapshot(vm, opts = {}) ⇒ `Vm`

add a virtual machine to the system by cloning from a snapshot

Parameters:

vm (Vm) —

The vm to add.
opts (Hash) (defaults to: {}) —

Additional options.

Options Hash (opts):

:clone (Boolean) —
Specifies if the virtual machine should be independent of the template.

When a virtual machine is created from a template by default the disks of the virtual machine depend on the disks of the template, they are using the copy on write mechanism so that only the differences from the template take up real storage space. If this parameter is specified and the value is true then the disks of the created virtual machine will be cloned, and independent of the template. For example, to create an independent virtual machine, send a request like this:
```
POST /ovirt-engine/vms?clone=true HTTP/1.1
```
With a request body like this:
```
<vm>
  <name>myvm<name>
  <template>
    <name>mytemplate<name>
  </template>
  <cluster>
    <name>mycluster<name>
  </cluster>
</vm>
```
Note
When this parameter is true the permissions of the template will also be copied, as when using clone_permissions=true.
:clone_permissions (Boolean) —
Specifies if the permissions of the template should be copied to the virtual machine.

If this optional parameter is provided, and its values is true then the permissions of the template (only the direct ones, not the inherited ones) will be copied to the created virtual machine. For example, to create a virtual machine from the mytemplate template copying its permissions, send a request like this:
```
POST /ovirt-engine/api/vms?clone_permissions=true HTTP/1.1
```
With a request body like this:
```
<vm>
  <name>myvm<name>
  <template>
    <name>mytemplate<name>
  </template>
  <cluster>
    <name>mycluster<name>
  </cluster>
</vm>
```

:filter (Boolean) —

Relevant for admin users only. Indicates whether to assign UserVmManager role on the created Virtual Machine for this user. This will enable the user to later access the Virtual Machine as though he were a non-admin user, foregoing his admin permissions (by providing filter=true).

Note	admin-as-user (meaning providing filter=true) POST requests on an existing Virtual Machine will fail unless the Virtual Machine has been previously created by the admin as a user (meaning with filter=true).

:seal (Boolean) —
Specifies if the virtual machine should be sealed after creation.

If this optional parameter is provided, and its value is true, the virtual machine will be sealed after creation. If the value is 'false', the virtual machine will not be sealed. If the parameter is not provided, the virtual machine will be sealed, only if it is created from a sealed template and its guest OS is not set to Windows.

For example, to create a virtual machine from the mytemplate template and to seal it, send a request like this:
```
POST /ovirt-engine/api/vms?seal=true HTTP/1.1
```
With a request body like this:
```
<vm>
  <name>myvm<name>
  <template>
    <name>mytemplate<name>
  </template>
  <cluster>
    <name>mycluster<name>
  </cluster>
</vm>
```
:headers (Hash) — default: {} —

Additional HTTP headers.
:query (Hash) — default: {} —

Additional URL query parameters.
:timeout (Integer) — default: nil —

The timeout for this request, in seconds. If no value is explicitly given then the timeout set globally for the connection will be used.
:wait (Boolean) — default: true —

If true wait for the response.

Returns:

(Vm)



35789
35790
35791

# File 'lib/ovirtsdk4/services.rb', line 35789

def add_from_snapshot(vm, opts = {})
  internal_add(vm, Vm, ADD_FROM_SNAPSHOT, opts)
end

#list(opts = {}) ⇒ `Array<Vm>`

Returns the list of virtual machines of the system.

The order of the returned list of virtual machines is guaranteed only if the sortby clause is included in the search parameter.

Parameters:

opts (Hash) (defaults to: {}) —

Additional options.

Options Hash (opts):

:all_content (Boolean) —

Indicates if all the attributes of the virtual machines should be included in the response.

By default the following attributes are excluded:

console
initialization.configuration.data - The OVF document describing the virtual machine.
rng_source
soundcard
virtio_scsi

For example, to retrieve the complete representation of the virtual machines send a request like this:

GET /ovirt-engine/api/vms?all_content=true HTTP/1.1

Note	The reason for not including these attributes is performance: they are seldom used and they require additional queries to the database. So try to use the this parameter only when it is really needed.

:case_sensitive (Boolean) —

Indicates if the search performed using the search parameter should be performed taking case into account. The default value is true, which means that case is taken into account. If you want to search ignoring case set it to false.
:filter (Boolean) —

Indicates if the results should be filtered according to the permissions of the user.
:follow (String) —

Indicates which inner links should be followed. The objects referenced by these links will be fetched as part of the current request. See here for details.
:max (Integer) —

The maximum number of results to return.
:ovf_as_ova (Boolean) —
Indicates if the results should expose the OVF as it appears in OVA files of that VM. The OVF document describing the virtual machine. This parameter will work only when all_content=True is set. The OVF will be presented in initialization.configuration.data.

For example:
```
GET /vms?all_content=true&ovf_as_ova=true HTTP/1.1
```
:search (String) —

A query string used to restrict the returned virtual machines.
:headers (Hash) — default: {} —

Additional HTTP headers.
:query (Hash) — default: {} —

Additional URL query parameters.
:timeout (Integer) — default: nil —

The timeout for this request, in seconds. If no value is explicitly given then the timeout set globally for the connection will be used.
:wait (Boolean) — default: true —

If true wait for the response.

Returns:

(Array<Vm>)



35866
35867
35868

# File 'lib/ovirtsdk4/services.rb', line 35866

def list(opts = {})
  internal_get(LIST, opts)
end

#service(path) ⇒ `Service`

Locates the service corresponding to the given path.

Parameters:

path (String) —

The path of the service.

Returns:

(Service) —

A reference to the service.

# File 'lib/ovirtsdk4/services.rb', line 35888

def service(path)
  if path.nil? || path == ''
    return self
  end
  index = path.index('/')
  if index.nil?
    return vm_service(path)
  end
  return vm_service(path[0..(index - 1)]).service(path[(index + 1)..-1])
end

#vm_service(id) ⇒ `VmService`

Locates the vm service.

Parameters:

id (String) —

The identifier of the vm.

Returns:

(VmService) —

A reference to the vm service.



35877
35878
35879

# File 'lib/ovirtsdk4/services.rb', line 35877

def vm_service(id)
  VmService.new(self, id)
end

Class: OvirtSDK4::VmsService

Instance Method Summary collapse

Methods inherited from Service

Instance Method Details

#add(vm, opts = {}) ⇒ `Vm`

#add_from_configuration(vm, opts = {}) ⇒ `Vm`

#add_from_scratch(vm, opts = {}) ⇒ `Vm`

#add_from_snapshot(vm, opts = {}) ⇒ `Vm`

#list(opts = {}) ⇒ `Array<Vm>`

#service(path) ⇒ `Service`

#vm_service(id) ⇒ `VmService`

Class: OvirtSDK4::VmsService

Instance Method Summary collapse

Methods inherited from Service

Instance Method Details

#add(vm, opts = {}) ⇒ Vm

#add_from_configuration(vm, opts = {}) ⇒ Vm

#add_from_scratch(vm, opts = {}) ⇒ Vm

#add_from_snapshot(vm, opts = {}) ⇒ Vm

#list(opts = {}) ⇒ Array<Vm>

#service(path) ⇒ Service

#vm_service(id) ⇒ VmService

#add(vm, opts = {}) ⇒ `Vm`

#add_from_configuration(vm, opts = {}) ⇒ `Vm`

#add_from_scratch(vm, opts = {}) ⇒ `Vm`

#add_from_snapshot(vm, opts = {}) ⇒ `Vm`

#list(opts = {}) ⇒ `Array<Vm>`

#service(path) ⇒ `Service`

#vm_service(id) ⇒ `VmService`