1. Documentation
×

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.

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.

Procedure

  1. Open the HyperConverged custom resource (CR) in your default editor by running the following command:

    $ oc edit hyperconverged kubevirt-hyperconverged -n openshift-cnv

  2. 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 command line

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.

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 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:

    Example downwardMetrics configuration file
    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: {}
          storageClassName: hostpath-csi-basic
  instancetype:
    name: u1.medium
  preference:
    name: fedora
  running: true
  template:
    metadata:
      labels:
        app.kubernetes.io/name: headless
    spec:
      domain:
        devices:
          downwardMetrics: {} (1)
      subdomain: headless
      volumes:
        - dataVolume:
            name: fedora-volume
          name: rootdisk
        - cloudInitNoCloud:
            userData: |
              #cloud-config
              chpasswd:
                expire: false
              password: '<password>' (2)
              user: fedora
          name: cloudinitdisk
    1 The downwardMetrics device.
    2 The password for the fedora user.

Viewing downward metrics

You can view downward metrics by using either of the following options:

  • The command line interface (CLI)

  • The vm-dump-metrics tool

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 command line

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.

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

  1. Install the vm-dump-metrics tool by running the following command:

    $ sudo dnf install -y vm-dump-metrics

  2. 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>