ine.api.model.4.4.31.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 Examples
The examples in this section show you how to use the REST API to set up
a basic {product-name} environment and to create a virtual machine.
In addition to the standard prerequisites, these examples require the
following:
* A networked and configured {product-name} installation.
* An ISO file containing the virtual machine operating system you want to
install. This chapter uses link:https://www.centos.org[CentOS] 7 for the
installation ISO example.
The API examples use link:https://curl.haxx.se[`curl`] to demonstrate API
requests with a client application. You can use any application that sends
HTTP requests.
[IMPORTANT]
====
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}.
The `curl` examples use `admin@internal` for the user
name, `mypassword` for the password, `/etc/pki/ovirt-engine/ca.pem` for the
certificate location, and `myengine.example.com` for the host name. You must
replace them with the correct values for your environment.
====
{product-name} generates a unique identifier for the `id`
attribute for each resource. Identifier codes in this example will
differ from the identifier codes in your {product-name}
environment.
In many examples, some attributes of the results returned by the
API have been omitted, for brevity. See, for example, the
<> reference for a complete list of attributes.
=== Access API entry point
The following request retrieves a representation of the main entry point
for version 4 of the API:
....
GET /ovirt-engine/api HTTP/1.1
Version: 4
Accept: application/xml
....
The same request, but using the `/v4` URL prefix instead of the `Version`
header:
....
GET /ovirt-engine/api/v4 HTTP/1.1
Accept: application/xml
....
The 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 is 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.
=== List data centers
{product-name} creates a `Default` data center on installation. This
example uses the `Default` data center as the basis for the virtual
environment.
The following request retrieves a representation of the data centers:
....
GET /ovirt-engine/api/datacenters HTTP/1.1
Accept: application/xml
....
The 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.
=== 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
....
The 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 Nehalem 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.
=== 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 the `Default` cluster and is a member of
the `Default` data center. This example uses the `ovirtmgmt` network to
connect the virtual machines.
The following request retrieves the list of logical networks:
....
GET /ovirt-engine/api/networks HTTP/1.1
Accept: application/xml
....
The 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.
=== 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
....
The 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.
=== 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
----
=== 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
----
=== 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
----
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
' \
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
----
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
' \
https://myengine.example.com/ovirt-engine/api/datacenters/001/storagedomains
....
=== 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
----
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 '
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
----
=== 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
----
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 '
mynic
My network interface card
' \
https://myengine.example.com/ovirt-engine/api/vms/007/nics
....
=== 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
----
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 '
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.
=== Attach ISO image to virtual machine
The boot media for the following virtual machine example requires a CD-ROM or DVD
ISO image for an operating system installation. This example uses a
CentOS 7 image.
ISO images must be available in the `myisos` ISO domain for the virtual
machines to use. You can use <> to create an
image transfer and <> to upload the ISO
image.
Once the ISO image 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
....
The 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 the 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]
----
----
The 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.
=== 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
----
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 '
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.