ine.api.model.4.1.37.source-code.004-QuickStartExample.adoc Maven / Gradle / Ivy
Go to download
Show more of this group Show more artifacts with this name
Show all versions of model Show documentation
Show all versions of model Show documentation
Model management tools for the oVirt Engine API.
== Quick start example
This chapter provides an example to demonstrate the REST API's ability
to setup a basic {product-name} environment and create a virtual machine.
In addition to the standard prerequisites, this example requires the
following:
* A networked and configured {product-name} installation;
* An ISO file containing a desired virtual machine operating system to
install. This chapter uses https://www.centos.org[CentOS] 7 for our
installation ISO example; and
* {product-name}'s `engine-iso-uploader` tool to upload your chosen
operating system ISO file.
This example uses https://curl.haxx.se[`curl`] to demonstrate API
requests with a client application. Note that any application capable of
HTTP requests can substitute for `curl`.
IMPORTANT: For simplicity, the HTTP request headers in this example omit
the `Host` and `Authorization` headers. However, these fields are mandatory
and require data specific to your installation of {product-name}.
IMPORTANT: All the `curl` examples use `admin@internal` as the user
name, `mypassword` as the password, `/etc/pki/ovirt-engine/ca.pem` as the
certificate location and `myengine.example.com` as the host name. These
are just examples, Make sure to replace them with valid values for your
environment.
NOTE: {product-name} generates an unique identifier for the `id`
attribute for each resource. Identifier codes in this example might
appear different to the identifier codes in your {product-name}
environment.
NOTE: In many examples of this section some of the attributes of results
returned by the API have been omitted, to make them shorter. You can
always use the reference to find the complete list of attributes. For
example, if you want to see the complete list of attributes of the
`Cluster` type, just go <>.
=== Example: Access API entry point
The following request retrieves a representation of the main entry point
for version 4 of of the API:
....
GET /ovirt-engine/api HTTP/1.1
Version: 4
Accept: application/xml
....
Same request, but using the `/v4` URL prefix instead of the `Version`
header:
....
GET /ovirt-engine/api/v4 HTTP/1.1
Accept: application/xml
....
Same request, using the `curl` command:
....
curl \
--cacert '/etc/pki/ovirt-engine/ca.pem' \
--request GET \
--header 'Version: 4' \
--header 'Accept: application/xml' \
--user 'admin@internal:mypassword' \
https://myengine.example.com/ovirt-engine/api
....
The result will be an object of type <>:
[source,xml]
----
...
oVirt Engine
ovirt.org
0
4.0.0-0.0.el7
4
0
0
23
30
5
6
12
102
253
545
----
[IMPORTANT]
====
When neither the header nor the URL prefix are used, the server will
automatically select a version. The default is version `4`. You can change
the default version using the `ENGINE_API_DEFAULT_VERSION` configuration
parameter:
....
# echo "ENGINE_API_DEFAULT_VERSION=3" > \
/etc/ovirt-engine/engine.conf.d/99-set-default-version.conf
# systemctl restart ovirt-engine
....
Changing this parameter affects all users of the API that don't
specify the version explicitly.
====
The entry point provides a user with links to the collections in a
virtualization environment. The `rel` attribute of each collection link
provides a reference point for each link. The next step in this example
examines the data center collection, which is available through the
`datacenters` link.
The entry point also contains other data such as <>, <> and
<>. This data is covered in chapters
outside this example.
=== Example: List data centers
{product-name} creates a `Default` data center on installation. This
example uses the `Default` data center as the basis for our virtual
environment.
The following request retrieves a representation of the data centers:
....
GET /ovirt-engine/api/datacenters HTTP/1.1
Accept: application/xml
....
Same request, using the `curl` command:
....
# curl \
--cacert '/etc/pki/ovirt-engine/ca.pem' \
--request GET \
--header 'Version: 4' \
--header 'Accept: application/xml' \
--user 'admin@internal:mypassword' \
https://myengine.example.com/ovirt-engine/api/datacenters
....
The result will be a list of objects of type <>:
[source,xml]
----
Default
The default Data Center
...
false
disabled
up
4
0
4
0
...
----
Note the `id` of your `Default` data center. It identifies this data
center in relation to other resources of your virtual environment.
The data center also contains a link to the
<> that manages the storage
domains attached to the data center:
....
....
That service is used to attach storage domains from the main
`storagedomains` collection, which this example covers later.
=== Example: List host clusters
{product-name} creates a `Default` hosts cluster on installation. This
example uses the `Default` cluster to group resources in your
{product-name} environment.
The following request retrieves a representation of the cluster
collection:
....
GET /ovirt-engine/api/clusters HTTP/1.1
Accept: application/xml
....
Same request, using the `curl` command:
....
curl \
--cacert '/etc/pki/ovirt-engine/ca.pem' \
--request GET \
--header 'Version: 4' \
--header 'Accept: application/xml' \
--user 'admin@internal:mypassword' \
https://myengine.example.com/ovirt-engine/api/clusters
....
The result will be a list of objects of type <>:
[source,xml]
----
Default
The default server cluster
...
x86_64
Intel Conroe Family
4
0
...
----
Note the `id` of your `Default` host cluster. It identifies this host
cluster in relation to other resources of your virtual environment.
The `Default` cluster is associated with the `Default` data center
through a relationship using the `id` and `href` attributes of the
`data_center` link:
....
> that manages the networks associated to this cluster. The next
section examines the networks collection in more detail.
=== Example: List logical networks
{product-name} creates a default `ovirtmgmt` network on installation.
This network acts as the management network for {engine-name} to access
hosts.
This network is associated with our `Default` cluster and is a member of
the `Default` data center. This example uses the `ovirtmgmt` network to
connect our virtual machines.
The following request retrieves the list of logical networks:
....
GET /ovirt-engine/api/networks HTTP/1.1
Accept: application/xml
....
Same request, using the `curl` command:
....
# curl \
--cacert '/etc/pki/ovirt-engine/ca.pem' \
--request GET \
--header 'Version: 4' \
--header 'Accept: application/xml' \
--user 'admin@internal:mypassword' \
https://myengine.example.com/ovirt-engine/api/networks
....
The result will be a list of objects of type <>:
[source,xml]
----
ovirtmgmt
Management Network
0
false
vm
...
----
The `ovirtmgmt` network is attached to the `Default` data center through a
relationship using the data center's `id`.
The `ovirtmgmt` network is also attached to the `Default` cluster through a
relationship in the cluster's network sub-collection.
=== Example: List hosts
This example retrieves the list of hosts and shows a host named `myhost`
registered with the virtualization environment:
....
GET /ovirt-engine/api/hosts HTTP/1.1
Accept: application/xml
....
Same request, using the `curl` command:
....
# curl \
--cacert '/etc/pki/ovirt-engine/ca.pem' \
--request GET \
--header 'Version: 4' \
--header 'Accept: application/xml' \
--user 'admin@internal:mypassword' \
https://myengine.example.com/ovirt-engine/api/hosts
....
The result will be a list of objects of type <>:
[source,xml]
----
myhost
...
node40.example.com
Intel Core Processor (Haswell, no TSX)
3600
1
2
1
8371830784
RHEL
7 - 2.1511.el7.centos.2.10
7
54321
up
...
----
Note the `id` of your host. It identifies this host in relation to other
resources of your virtual environment.
This host is a member of the `Default` cluster and accessing the `nics`
sub-collection shows this host has a connection to the `ovirtmgmt`
network.
=== Example: Create NFS data storage
An NFS data storage domain is an exported NFS share attached to a data
center and provides storage for virtualized guest images. Creation of a
new storage domain requires a `POST` request, with the storage domain
representation included, sent to the URL of the storage domain
collection.
You can enable the wipe after delete option by default on the storage
domain. To configure this specify `wipe_after_delete` in the POST
request. This option can be edited after the domain is created, but
doing so will not change the wipe after delete property of disks that
already exist.
The request should be like this:
....
POST /ovirt-engine/api/storagedomains HTTP/1.1
Accept: application/xml
Content-type: application/xml
....
And the request body should be like this:
[source,xml]
----
mydata
data
My data
nfs
mynfs.example.com
/exports/mydata
myhost
----
The same request, using the `curl` command:
....
# curl \
--cacert '/etc/pki/ovirt-engine/ca.pem' \
--user 'admin@internal:mypassword' \
--request POST \
--header 'Version: 4' \
--header 'Content-Type: application/xml' \
--header 'Accept: application/xml' \
--data '
mydata
My data
data
nfs
mynfs.example.com
/exports/mydata
myhost
' \
https://myengine.example.com/ovirt-engine/api/storagedomains
....
The server uses host `myhost` to create a NFS data storage domain called
`mydata` with an export path of `mynfs.example.com:/exports/mydata`. The
API also returns the following representation of the newly created
storage domain resource (of type <>):
[source,xml]
----
mydata
My data
42949672960
0
false
unattached
mynfs.example.com
/exports/mydata
nfs
v3
data
9663676416
----
=== Example: Create NFS ISO storage
An NFS ISO storage domain is a mounted NFS share attached to a data
center and provides storage for DVD/CD-ROM ISO and virtual floppy disk
(VFD) image files. Creation of a new storage domain requires a `POST`
request, with the storage domain representation included, sent to the
URL of the storage domain collection:
The request should be like this:
....
POST /ovirt-engine/api/storagedomains HTTP/1.1
Accept: application/xml
Content-type: application/xml
....
And the request body should be like this:
[source,xml]
----
myisos
My ISOs
iso
nfs
mynfs.example.com
/exports/myisos
myhost
----
The same request, using the `curl` command:
....
# curl \
--cacert '/etc/pki/ovirt-engine/ca.pem' \
--user 'admin@internal:mypassword' \
--request POST \
--header 'Version: 4' \
--header 'Content-Type: application/xml' \
--header 'Accept: application/xml' \
--data '
myisos
My ISOs
iso
nfs
mynfs.example.com
/exports/myisos
myhost
' \
https://myengine.example.com/ovirt-engine/api/storagedomains
....
The server uses host `myhost` to create a NFS ISO storage domain called
`myisos` with an export path of `mynfs.example.com:/exports/myisos`. The
API also returns the following representation of the newly created
storage domain resource (of type <>):
[source,xml]
----
myiso
My ISOs
42949672960
0
false
unattached
mynfs.example.com
/exports/myisos
nfs
v1
iso
9663676416
----
=== Example: Attach storage domains to data center
The following example attaches the `mydata` and `myisos` storage domains
to the `Default` data center.
To attach the `mydata` storage domain, send a request like this:
....
POST /ovirt-engine/api/datacenters/001/storagedomains HTTP/1.1
Accept: application/xml
Content-type: application/xml
....
With a request body like this:
[source,xml]
----
mydata
----
Same request, using the `curl` command:
....
# curl \
--cacert '/etc/pki/ovirt-engine/ca.pem' \
--user 'admin@internal:mypassword' \
--request POST \
--header 'Version: 4' \
--header 'Content-Type: application/xml' \
--header 'Accept: application/xml' \
--data '
mydata
' \
https://myengine.example.com/ovirt-engine/api/datacenters/001/storagedomains
....
To attach the `myisos` storage domain, send a request like this:
....
POST /ovirt-engine/api/datacenters/001/storagedomains HTTP/1.1
Accept: application/xml
Content-type: application/xml
....
With a request body like this:
[source,xml]
----
myisos
----
Same request, using the `curl` command:
....
# curl \
--cacert '/etc/pki/ovirt-engine/ca.pem' \
--user 'admin@internal:mypassword' \
--request POST \
--header 'Version: 4' \
--header 'Content-Type: application/xml' \
--header 'Accept: application/xml' \
--data '
myisos
' \
https://myengine.example.com/ovirt-engine/api/datacenters/001/storagedomains
....
=== Example: Create virtual machine
The following example creates a virtual machine called `myvm` on the
`Default` cluster using the virtualization environment's `Blank`
template as a basis. The request also defines the virtual machine's
memory as 512 MiB and sets the boot device to a virtual hard disk.
The request should be contain an object of type <>
describing the virtual machine to create:
[source,xml]
----
POST /ovirt-engine/api/vms HTTP/1.1
Accept: application/xml
Content-type: application/xml
----
And the request body should be like this:
[source,xml]
----
myvm
My VM
Default
Blank
536870912
hd
----
Same request, using the `curl` command:
....
# curl \
--cacert '/etc/pki/ovirt-engine/ca.pem' \
--user 'admin@internal:mypassword' \
--request POST \
--header 'Version: 4' \
--header 'Content-Type: application/xml' \
--header 'Accept: application/xml' \
--data '
myvm
My VM
Default
Blank
536870912
hd
' \
https://myengine.example.com/ovirt-engine/api/vms
....
The response body will be an object of the <> type:
[source,xml]
----
myvm
...
x86_64
1
1
1
1073741824
hd
other
desktop
down
----
=== Example: Create a virtual machine NIC
The following example creates a virtual network interface to connect the
example virtual machine to the `ovirtmgmt` network.
The request should be like this:
....
POST /ovirt-engine/api/vms/007/nics HTTP/1.1
Content-Type: application/xml
Accept: application/xml
....
The request body should contain an object of type <>
describing the NIC to be created:
[source,xml]
----
mynic
My network interface card
----
Same request, using the `curl` command:
....
# curl \
--cacert '/etc/pki/ovirt-engine/ca.pem' \
--user 'admin@internal:mypassword' \
--request POST \
--header 'Version: 4' \
--header 'Content-Type: application/xml' \
--header 'Accept: application/xml' \
--data '
mynic
My network interface card
' \
https://myengine.example.com/ovirt-engine/api/vms/007/nics
....
=== Example: Create virtual machine disk
The following example creates an 8 GiB _copy-on-write_ disk for the
example virtual machine.
The request should be like this:
....
POST /ovirt-engine/api/vms/007/diskattachments HTTP/1.1
Content-Type: application/xml
Accept: application/xml
....
The request body should be an object of type <> describing the disk and how it will be attached to the
virtual machine:
[source,xml]
----
false
virtio
true
My disk
cow
mydisk
8589934592
mydata
----
Same request, using the `curl` command:
....
# curl \
--cacert '/etc/pki/ovirt-engine/ca.pem' \
--user 'admin@internal:mypassword' \
--request POST \
--header 'Version: 4' \
--header 'Content-Type: application/xml' \
--header 'Accept: application/xml' \
--data '
false
virtio
true
My disk
cow
mydisk
8589934592
mydata
' \
https://myengine.example.com/ovirt-engine/api/vms/007/diskattachments
....
The `storage_domains` attribute tells the API to store the disk on the
`mydata` storage domain.
=== Example: Attach ISO image to virtual machine
The boot media for our example virtual machine requires an CD-ROM or DVD
ISO image for an operating system installation. This example uses a
CentOS 7 image for installation.
ISO images must be available in the `myisos` ISO domain for the virtual
machines to use. {product-name} provides an uploader tool that ensures
that the ISO images are uploaded into the correct directory path with
the correct user permissions.
Once the ISO is uploaded, an API can be used to request the list of
files from the ISO storage domain:
....
GET /ovirt-engine/api/storagedomains/006/files HTTP/1.1
Accept: application/xml
....
Same request, using the `curl` command:
....
# curl \
--cacert '/etc/pki/ovirt-engine/ca.pem' \
--user 'admin@internal:mypassword' \
--request GET \
--header 'Version: 4' \
--header 'Accept: application/xml' \
https://myengine.example.com/ovirt-engine/api/storagedomains/006/files
....
The server returns the following list of objects of type <>, one for each available ISO (or floppy) image:
[source,xml]
----
CentOS-7-x86_64-Minimal.iso
...
----
An API user attaches the `CentOS-7-x86_64-Minimal.iso` to our example
virtual machine. Attaching an ISO image is equivalent to using the
_Change CD_ button in the administration or user portal applications.
The request should be like this:
....
PUT /ovirt-engine/api/vms/007/cdroms/00000000-0000-0000-0000-000000000000 HTTP/1.1
Accept: application/xml
Content-type: application/xml
....
The request body should be an object of type <>
containing an inner `file` attribute to indicate the identifier of the
ISO (or floppy) image:
[source,xml]
----
----
Same request, using the `curl` command:
....
# curl \
--cacert '/etc/pki/ovirt-engine/ca.pem' \
--user 'admin@internal:mypassword' \
--request PUT \
--header 'Version: 4' \
--header 'Content-Type: application/xml' \
--header 'Accept: application/xml' \
--data '
' \
https://myengine.example.com/ovirt-engine/api/vms/007/cdroms/00000000-0000-0000-0000-000000000000
....
For more details see the documentation of the <> that manages virtual machine CD-ROMS.
=== Example: Start the virtual machine
The virtual environment is complete and the virtual machine contains all
necessary components to function. This example starts the virtual
machine using the <> method.
The request should be like this:
....
POST /ovirt-engine/api/vms/007/start HTTP/1.1
Accept: application/xml
Content-type: application/xml
....
The request body should be like this:
[source,xml]
----
cdrom
----
Same request, using the `curl` command:
....
# curl \
--cacert '/etc/pki/ovirt-engine/ca.pem' \
--user 'admin@internal:mypassword' \
--request POST \
--header 'Version: 4' \
--header 'Content-Type: application/xml' \
--header 'Accept: application/xml' \
--data '
cdrom
' \
https://myengine.example.com/ovirt-engine/api/vms/007/start
....
The additional request body sets the virtual machine's boot device to
CD-ROM for this boot only. This enables the virtual machine to install
the operating system from the attached ISO image. The boot device
reverts back to disk for all future boots.
© 2015 - 2025 Weber Informatics LLC | Privacy Policy