Exposing downward metrics for virtual machines

As an administrator, you can expose a limited set of host and virtual machine (VM) metrics to a guest VM by first enabling a downwardMetrics feature gate and then configuring a downwardMetrics device.

Users can view the metrics results by using the command line or the vm-dump-metrics tool.

Note

On Red Hat Enterprise Linux (RHEL) 9, use the command line to view downward metrics. See Viewing downward metrics by using the command line.

The vm-dump-metrics tool is not supported on the Red Hat Enterprise Linux (RHEL) 9 platform.

Enabling or disabling the downwardMetrics feature gate

You can enable or disable the downwardMetrics feature gate by performing either of the following actions:

Editing the HyperConverged custom resource (CR) in your default editor
Using the command line

Enabling or disabling the downward metrics feature gate in a YAML file

To expose downward metrics for a host virtual machine, you can enable the downwardMetrics feature gate by editing a YAML file.

Prerequisites

You must have administrator privileges to enable the feature gate.
You have installed the OpenShift CLI (oc).

Procedure

Open the HyperConverged custom resource (CR) in your default editor by running the following command:
```
$ oc edit hyperconverged kubevirt-hyperconverged -n openshift-cnv
```

Choose to enable or disable the downwardMetrics feature gate as follows:

To enable the downwardMetrics feature gate, add and then set spec.featureGates.downwardMetrics to true. For example:

apiVersion: hco.kubevirt.io/v1beta1
kind: HyperConverged
metadata:
  name: kubevirt-hyperconverged
  namespace: openshift-cnv
spec:
    featureGates:
      downwardMetrics: true
# ...

To disable the downwardMetrics feature gate, set spec.featureGates.downwardMetrics to false. For example:

apiVersion: hco.kubevirt.io/v1beta1
kind: HyperConverged
metadata:
  name: kubevirt-hyperconverged
  namespace: openshift-cnv
spec:
    featureGates:
      downwardMetrics: false
# ...

Enabling or disabling the downward metrics feature gate from the CLI

To expose downward metrics for a host virtual machine, you can enable the downwardMetrics feature gate by using the command line.

Prerequisites

You must have administrator privileges to enable the feature gate.
You have installed the OpenShift CLI (oc).

Procedure

Choose to enable or disable the downwardMetrics feature gate as follows:

Enable the downwardMetrics feature gate by running the command shown in the following example:

$ oc patch hco kubevirt-hyperconverged -n openshift-cnv \
  --type json -p '[{"op": "replace", "path": \
  "/spec/featureGates/downwardMetrics", \
  "value": true}]'

Disable the downwardMetrics feature gate by running the command shown in the following example:

$ oc patch hco kubevirt-hyperconverged -n openshift-cnv \
  --type json -p '[{"op": "replace", "path": \
  "/spec/featureGates/downwardMetrics", \
  "value": false}]'

Configuring a downward metrics device

You can enable the capturing of downward metrics for a host VM by creating a configuration file that includes a downwardMetrics device. Adding this device establishes that the metrics are exposed through a virtio-serial port.

Prerequisites

You must first enable the downwardMetrics feature gate.

Procedure

Edit or create a YAML file that includes a downwardMetrics device, as shown in the following example:

apiVersion: kubevirt.io/v1
kind: VirtualMachine
metadata:
  name: fedora
  namespace: default
spec:
  dataVolumeTemplates:
    - metadata:
        name: fedora-volume
      spec:
        sourceRef:
          kind: DataSource
          name: fedora
          namespace: openshift-virtualization-os-images
        storage:
          resources: {}
  instancetype:
    name: u1.medium
  runStrategy: Always
  template:
    metadata:
      labels:
        app.kubernetes.io/name: headless
    spec:
      domain:
        devices:
          downwardMetrics: {} 
      subdomain: headless
      volumes:
        - dataVolume:
            name: fedora-volume
          name: rootdisk
        - cloudInitNoCloud:
            userData: |
              #cloud-config
              chpasswd:
                expire: false
              password: '<password>' 
              user: fedora
          name: cloudinitdisk

The downwardMetrics device.
The password for the fedora user.

Viewing downward metrics

You can view downward metrics by using either the command-line interface (CLI), or the vm-dump-metrics tool.

Note

On Red Hat Enterprise Linux (RHEL) 9, use the command line to view downward metrics. The vm-dump-metrics tool is not supported on the Red Hat Enterprise Linux (RHEL) 9 platform.

Viewing downward metrics by using the CLI

You can view downward metrics by entering a command from inside a guest virtual machine (VM).

Procedure

Run the following commands:

$ sudo sh -c 'printf "GET /metrics/XML\n\n" > /dev/virtio-ports/org.github.vhostmd.1'

$ sudo cat /dev/virtio-ports/org.github.vhostmd.1

Viewing downward metrics by using the vm-dump-metrics tool

To view downward metrics, install the vm-dump-metrics tool and then use the tool to expose the metrics results.

Note

On Red Hat Enterprise Linux (RHEL) 9, use the command line to view downward metrics. The vm-dump-metrics tool is not supported on the Red Hat Enterprise Linux (RHEL) 9 platform.

Procedure

Install the vm-dump-metrics tool by running the following command:
```
$ sudo dnf install -y vm-dump-metrics
```

Retrieve the metrics results by running the following command:

$ sudo vm-dump-metrics

Example output:

<metrics>
  <metric type="string" context="host">
    <name>HostName</name>
    <value>node01</value>
[...]
  <metric type="int64" context="host" unit="s">
    <name>Time</name>
    <value>1619008605</value>
  </metric>
  <metric type="string" context="host">
    <name>VirtualizationVendor</name>
    <value>kubevirt.io</value>
  </metric>
</metrics>