oVirt / Red Hat Virtualization

Pull

Synopsis

Director polls one oVirt engine, or one Red Hat Virtualization Manager, through its REST API (version 4, oVirt 4.0 or later), and writes what it reads as ECS documents: the engine's hosts and their processors and network interfaces, its users and storage domains, its virtual machines and their network interfaces, snapshots, and disks, how the hosts and the machines are doing (their status and their statistics), and its events. Nothing is installed on the engine or on its hosts.

What the device reads is decided by the datasets and profiles assigned to it, as for Windows, Linux, and SNMP devices. Each data model is a dataset of its own — see oVirt / Red Hat Virtualization Datasets.

The engine is the device. One device reads every host (hypervisor) and every virtual machine the engine manages.

Nothing it finds is registered as a device. The data centers, clusters, hosts, and virtual machines the device discovers are records of the engine's, and they tag the records of the objects inside them (see Tags), as a vCenter's ESXi hosts tag a VMware vSphere device's records. None of them becomes a device of its own.

The device dials the engine and binds no port, so any number of oVirt devices may use port 443. One Director polls each device: two Directors never read the same events twice.

note

The oVirt / Red Hat Virtualization device needs Director 2.2.3 or later. With no Director or cluster at that version selected, the wizard shows oVirt / Red Hat Virtualization devices are unavailable on directors or clusters below version 2.2.3 and the device cannot be created.

Account

The device logs in through the engine's single sign-on, as the oVirt SDKs do, and sends the access token it gets back with every request. It reads; it changes nothing.

• The username names its profile, as user@profile: admin@internal, svc-virtualmetric@internal, or jdoe@corp.example.com for a user of a directory profile. The single sign-on refuses a name without one, so a username typed as text without a profile is refused on save, and the Director refuses it at start with Configuration error. A username taken from an environment variable or a vault is checked by the engine once it is resolved.
• A user with the ReadOnlyAdmin role on the System object reads every dataset. admin@internal does too, and is more than the device needs.
• A user with a narrower role sees what the engine lets it see.

A dataset the account may not read keeps the device Connected, since the engine answered, and the device's message names each such dataset, and why, until that dataset reads again:

oVirt poller connected to engine01. ovirt_user_collector reads nothing: the engine refused the account /ovirt-engine/api/users (403 Operation Failed [User is not authorized to perform this action.])

Schema

- id: <numeric>
  name: <string>
  description: <string>
  type: ovirt
  tags: <string[]>
  pipelines: <pipeline[]>
  status: <boolean>
  properties:
    address: <string>
    username: <string>
    password: <string>
    port: <numeric>
    timeout: <numeric>
    initial_lookback: <numeric>
    tls:
      status: <boolean>
      insecure_skip_verify: <boolean>
      ca_name: <string>
      server_name: <string>
      min_tls_version: <string>
      max_tls_version: <string>
  definitions: <definition[]>

Configuration

The following fields are used to define the device:

Device

Field	Required	Default	Description
id	Y	-	Unique numeric identifier
name	Y	-	Device name
description	N	-	Optional description
type	Y	-	Must be ovirt
tags	N	-	Optional tags
pipelines	N	-	Optional pre-processor pipelines
status	N	true	Enable/disable the device

Connection

Field	Required	Default	Description
address	Y	-	Host name or IP address of the engine or the Manager, or of the proxy in front of it. A wildcard address, a URL, or host:port is refused. An IPv6 address may be written in one pair of brackets.
port	N	443, or 80 without TLS	The REST API's port
username	Y	-	A user of the engine with its profile, user@profile. See Account.
password	Y	-	The user's password

The username and password take plain text, ${ENV_VAR}, or $secret{...} ($secret{id=...} or $secret{store=...,ref=...}). They are resolved at every login, so a password rotated in the vault is used from the next login on. The configuration keeps the reference, and a changed reference restarts the device.

TLS

Field	Required	Default	Description
tls.status	N	true	The API is called over HTTPS. false calls it over plain HTTP, for an endpoint behind a proxy that terminates TLS.
tls.insecure_skip_verify	N	false	true accepts any certificate. Pin the CA instead where you can.
tls.ca_name	N	the system trust store	A CA to verify the engine's certificate against
tls.server_name	N	address	The name the certificate is verified for, when it is not address
tls.min_tls_version	N	tls1.2	tls1.0, tls1.1, tls1.2, or tls1.3
tls.max_tls_version	N	-	No cap

note

TLS material fields (cert_name, key_name, ca_name, client_ca_name) accept any of the following:

• File name — resolved relative to the service root directory. Nested paths such as certs/prod/server.pem are supported.
• Absolute path — honored only if it resolves inside the service root. Any path that escapes the root is refused.
• Inline PEM content — used verbatim when the value contains -----BEGIN.
• Environment variable — ${ENV_VAR}.
• Vault reference — $secret{id=...} or $secret{store=...,ref=...}.

Pin the engine's CA. An engine's certificate is signed by the engine's own CA, which the engine serves at https://<engine>/ovirt-engine/services/pki-resource?resource=ca-certificate&format=X509-PEM-CA. Set tls.ca_name to that CA rather than turning verification off.

warning

With tls.status set to false, the login's username and password, and every access token, are sent in cleartext, and anyone who reads them can call the engine as the account. Use plain HTTP only where the network between the Director and the proxy that terminates TLS is trusted.

Datasets

The device's definitions are its datasets, each named after its type, ovirt_<dataset>_collector. In the console they are the datasets and profiles assigned to the device. For the dataset types, their intervals, and their fields, see oVirt / Red Hat Virtualization Datasets.

Advanced Configuration

Field	Required	Default	Description
timeout	N	60	Seconds each request may take, the login included, from 1 to 300
initial_lookback	N	86400	Seconds before its first reading where the event dataset starts when it has no checkpoint. 0 starts at the first reading. The dataset's own initial_lookback wins. The engine keeps its events for 30 days by default.

Connection States

• A configuration error — no address, no username, a username written without its profile, a reference that does not resolve, a CA that cannot be read — stops the device at start with Configuration error. The message names the property but never its value.
• At start the device logs in and reads the API's root, which names the product, its vendor, and its version. A login the single sign-on refuses sets Authentication error and stops the device, with the single sign-on's own reason in the device's log; the Director starts it again later.
• An engine that does not answer, or a gateway in front of it answering 502, 503, or 504, sets Connection error; one whose certificate does not verify, Certificate error.
• The session expires after the engine's idle timeout (thirty minutes by default) and when the engine restarts. A request the engine answers 401 logs in again once and is sent once more; the datasets share the device's session, and one renewal serves them all. A renewed session refused again fails that reading with Authentication error.

The connection state follows the engine: the device is Connected once it logs in, and whenever a reading succeeds.

Requests

• Deadlines. Every request has the device's timeout as its deadline, the login's included, and stopping the device abandons the requests in flight. The session's token is revoked when the device stops.
• Only the configured engine is called. The device builds every request itself on the address it was configured with, and never follows a redirect, so the token never leaves for another host. An answer larger than 256 MiB is not read.
• At most eight at once. A dataset that asks after every host or machine one by one sends at most eight requests at once.
• User agent. The device identifies itself as VirtualMetric Director <version>.

When Things Are Read

• Every dataset on its own interval, all of them at once when the device starts. The hourly inventories do not hold back the status, statistics, and events, which are read every minute.
• A failed reading is read again after 60 seconds when its interval is longer. A reading the engine refused the account waits for its interval, since it would be refused again.
• What goes wrong in a dataset is its own. A refused request, records that cannot be written, or a panic costs that dataset's reading alone. The dataset keeps its checkpoint or its baseline, and the other datasets go on. A panic while one host or machine is read is that object's failure, and the reading goes on with the others.

Tags

Every record carries, as searchable fields, the engine it came through and where its object sits:

Field	On	Holds
observer.vendor	Every record	oVirt, or what the engine says it is (Red Hat)
observer.product	Every record	What the engine says it is: oVirt Engine, Red Hat Virtualization Manager
observer.version	Every record	The engine's version (4.5.4)
observer.name	Every record	The device's name in the console: the engine the record came through
observer.hostname or observer.ip	Every record	The device's address
ovirt.datacenter.id, .name	Every record of a host, a machine, their parts and states; a storage domain attached to one	The data center it sits in
ovirt.cluster.id, .name	Every record of a host, a machine, their parts and states	The cluster it sits in
host.name	Every record of a host or its parts; a running machine's	The host itself, or the host a machine runs on
ovirt.host.id, .name	Every record of a host's parts and states; a running machine's	The host
ovirt.vm.id, .name	Every record of a machine's parts and states	The virtual machine

host.name is always a hypervisor, never a virtual machine: a search for a host finds the host, its parts, its statistics, and the machines on it alike. A machine's own name, and, while its guest agent reports them, its fully qualified name and addresses, are its record's related.hosts and related.ip. Every id is the object's UUID, as the API gives it.

The data centers, clusters, and hosts come from the device's discovery of the engine, which it keeps in memory. The host dataset refreshes it at every reading, and any other dataset when it is an hour old. Nothing is registered from it. A host's and a running machine's own records name their cluster and host, and win over the discovery's.

event.dataset: "ovirt.vm_stats" and ovirt.cluster.name: "Production"
event.dataset: "ovirt.event" and log.level: "error"
host.name: "hv01.example.com"
observer.name: "engine01"

Records

Every record is one ECS 8.11 document:

• event.module is ovirt, and event.dataset is ovirt.<dataset>.
• event.kind is state for an inventory item, metric for a status or statistics record, and event for an event.
• event.category is iam for users, and host for the others, with network for network interfaces.
• Fields ECS has no name for sit under ovirt.<dataset>. Sizes and memory are bytes, speeds bits per second, rates per second, percentages fractions of 1 (0.125 is 12.5%), times are dates in UTC, and a field the engine leaves empty is left out.

Inventory records carry event.action from a dataset's second reading on: added, changed, unchanged, or removed.

Each record also carries its dataset's own definition id. For the fields of each dataset, see oVirt / Red Hat Virtualization Datasets.

Console

In the console, go to Fleet Management > Devices > oVirt / Red Hat Virtualization and click Add new device. The wizard's steps are:

1. General settings, as on every device.
2. Connection settings: Address, Port, Username, and Password; then TLS encryption, and while it is on, Skip certificate verification, CA certificate (Optional), Server name (Optional), Minimum TLS version (Optional), and Maximum TLS version (Optional). Switching TLS off and on moves the port between 80 and 443, unless you typed one. With TLS encryption off, the wizard warns that the login is sent in cleartext.
3. Advanced settings: Timeout and Initial lookback, both in seconds.
4. Data collection: the datasets or profile the device reads. A device receives datasets or a profile, never both.
5. Review and create.

The password is masked where it is typed and on the device page, and the review shows only whether it is set.

Simulation

The oVirt / Red Hat Virtualization device is not simulated. What it writes is decided by its datasets, seventeen record shapes under seventeen definition ids, and one generic sample cannot stand in for them. See Simulation.

Examples

Password in a Vault

Reading an engine's hosts and virtual machines hourly, the hosts' status and the machines' statistics every minute, and the events, with the password kept in a vault...

devices: - id: 512300150 name: engine01 type: ovirt status: true properties: address: "engine.example.com" username: "svc-virtualmetric@internal" password: "$secret{store=corp-vault,ref=ovirt/engine}" definitions: - name: ovirt_host_collector - name: ovirt_vm_collector - name: ovirt_host_status_collector - name: ovirt_vm_stats_collector - name: ovirt_event_collector

Pinned Engine CA

Verifying a Red Hat Virtualization Manager against the engine's own CA, with the credentials in environment variables, and starting the events an hour back...

devices: - id: 512300151 name: rhvm01 type: ovirt status: true properties: address: "rhvm.example.com" username: "${RHV_USER}" password: "${RHV_PASSWORD}" initial_lookback: 3600 tls: ca_name: "rhvm-ca.pem" definitions: - name: ovirt_host_collector - name: ovirt_storage_domain_collector - name: ovirt_vm_status_collector - name: ovirt_event_collector