Skip to content

Commit c5a86ff

Browse files
skopacz1skopacz1
authored
Merge pull request #74920 from aspauldi/CNV-27866
CNV-27866: [Doc] expose the downwardMetrics through a virtio-serial channel
2 parents 99db171 + 96a398e commit c5a86ff

8 files changed

+273
-0
lines changed

‎_topic_maps/_topic_map.yml

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -4202,6 +4202,8 @@ Topics:
42024202
File: virt-prometheus-queries
42034203
- Name: Virtual machine custom metrics
42044204
File: virt-exposing-custom-metrics-for-vms
4205+
- Name: Virtual machine downward metrics
4206+
File: virt-exposing-downward-metrics
42054207
- Name: Virtual machine health checks
42064208
File: virt-monitoring-vm-health
42074209
- Name: Runbooks

‎modules/virt-configuring-downward-metrics.adoc

Lines changed: 67 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,67 @@
1+
// Module included in the following assemblies:
2+
//
3+
// * virt/monitoring/virt-exposing-downward-metrics.adoc
4+
5+
:_mod-docs-content-type: PROCEDURE
6+
[id="virt-configuring-downward-metrics_virt-using-downward-metrics_{context}"]
7+
= Configuring a downward metrics device
8+
9+
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.
10+
11+
.Prerequisites
12+
13+
* You must first enable the `downwardMetrics` feature gate.
14+
15+
.Procedure
16+
17+
* Edit or create a YAML file that includes a `downwardMetrics` device, as shown in the following example:
18+
+
19+
.Example downwardMetrics configuration file
20+
[source,yaml]
21+
----
22+
apiVersion: kubevirt.io/v1
23+
kind: VirtualMachine
24+
metadata:
25+
name: fedora
26+
namespace: default
27+
spec:
28+
dataVolumeTemplates:
29+
- metadata:
30+
name: fedora-volume
31+
spec:
32+
sourceRef:
33+
kind: DataSource
34+
name: fedora
35+
namespace: openshift-virtualization-os-images
36+
storage:
37+
resources: {}
38+
storageClassName: hostpath-csi-basic
39+
instancetype:
40+
name: u1.medium
41+
preference:
42+
name: fedora
43+
running: true
44+
template:
45+
metadata:
46+
labels:
47+
app.kubernetes.io/name: headless
48+
spec:
49+
domain:
50+
devices:
51+
downwardMetrics: {} <1>
52+
subdomain: headless
53+
volumes:
54+
- dataVolume:
55+
name: fedora-volume
56+
name: rootdisk
57+
- cloudInitNoCloud:
58+
userData: |
59+
#cloud-config
60+
chpasswd:
61+
expire: false
62+
password: '<password>' <2>
63+
user: fedora
64+
name: cloudinitdisk
65+
----
66+
<1> The `downwardMetrics` device.
67+
<2> The password for the `fedora` user.

‎modules/virt-enabling-disabling-downward-metrics-feature-gate-cli.adoc

Lines changed: 37 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,37 @@
1+
// Module included in the following assemblies:
2+
//
3+
// * virt/monitoring/virt-exposing-downward-metrics.adoc
4+
5+
:_mod-docs-content-type: PROCEDURE
6+
[id="virt-enabling-disabling-downward-metrics-feature-gate-cli_{context}"]
7+
= Enabling or disabling the downward metrics feature gate from the command line
8+
9+
To expose downward metrics for a host virtual machine, you can enable the `downwardMetrics` feature gate by using the command line.
10+
11+
.Prerequisites
12+
13+
* You must have administrator privileges to enable the feature gate.
14+
15+
.Procedure
16+
17+
* Choose to enable or disable the `downwardMetrics` feature gate as follows:
18+
19+
** Enable the `downwardMetrics` feature gate by running the command shown in the following example:
20+
+
21+
[source,terminal,subs="attributes+"]
22+
----
23+
$ oc patch hco kubevirt-hyperconverged -n openshift-cnv \
24+
--type json -p '[{"op": "replace", "path": \
25+
"/spec/featureGates/downwardMetrics" \
26+
"value": true}]'
27+
----
28+
29+
** Disable the `downwardMetrics` feature gate by running the command shown in the following example:
30+
+
31+
[source,terminal,subs="attributes+"]
32+
----
33+
$ oc patch hco kubevirt-hyperconverged -n openshift-cnv \
34+
--type json -p '[{"op": "replace", "path": \
35+
"/spec/featureGates/downwardMetrics" \
36+
"value": false}]'
37+
----

‎modules/virt-enabling-disabling-downward-metrics-feature-gate-yaml.adoc

Lines changed: 55 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,55 @@
1+
// Module included in the following assemblies:
2+
//
3+
// * virt/monitoring/virt-exposing-downward-metrics.adoc
4+
5+
:_mod-docs-content-type: PROCEDURE
6+
[id="virt-enabling-disabling-downward-metrics-feature-gate-yaml_{context}"]
7+
= Enabling or disabling the downward metrics feature gate in a YAML file
8+
9+
To expose downward metrics for a host virtual machine, you can enable the `downwardMetrics` feature gate by editing a YAML file.
10+
11+
.Prerequisites
12+
13+
* You must have administrator privileges to enable the feature gate.
14+
15+
.Procedure
16+
17+
. Open the HyperConverged custom resource (CR) in your default editor by running the following command:
18+
+
19+
[source,terminal]
20+
----
21+
$ oc edit hyperconverged kubevirt-hyperconverged -n openshift-cnv
22+
----
23+
24+
. Choose to enable or disable the downwardMetrics feature gate as follows:
25+
26+
* To enable the `downwardMetrics` feature gate, add and then set `spec.featureGates.downwardMetrics` to `true`. For example:
27+
+
28+
[source,yaml]
29+
----
30+
apiVersion: hco.kubevirt.io/v1beta1
31+
kind: HyperConverged
32+
metadata:
33+
name: kubevirt-hyperconverged
34+
namespace: openshift-cnv
35+
spec:
36+
featureGates:
37+
downwardMetrics: true
38+
# ...
39+
----
40+
41+
42+
* To disable the `downwardMetrics` feature gate, set `spec.featureGates.downwardMetrics` to `false`. For example:
43+
+
44+
[source,yaml]
45+
----
46+
apiVersion: hco.kubevirt.io/v1beta1
47+
kind: HyperConverged
48+
metadata:
49+
name: kubevirt-hyperconverged
50+
namespace: openshift-cnv
51+
spec:
52+
featureGates:
53+
downwardMetrics: false
54+
# ...
55+
----

‎modules/virt-viewing-downward-metrics-cli.adoc

Lines changed: 23 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,23 @@
1+
// Module included in the following assemblies:
2+
//
3+
// * virt/monitoring/virt-exposing-downward-metrics.adoc
4+
5+
:_mod-docs-content-type: PROCEDURE
6+
[id="virt-viewing-downward-metrics-cli_{context}"]
7+
= Viewing downward metrics by using the command line
8+
9+
You can view downward metrics by entering a command from inside a guest virtual machine (VM).
10+
11+
.Procedure
12+
13+
* Run the following commands:
14+
+
15+
[source,terminal]
16+
----
17+
$ sudo sh -c 'printf "GET /metrics/XML\n\n" > /dev/virtio-ports/org.github.vhostmd.1'
18+
----
19+
+
20+
[source,terminal]
21+
----
22+
$ sudo cat /dev/virtio-ports/org.github.vhostmd.1
23+
----

‎modules/virt-viewing-downward-metrics-tool.adoc

Lines changed: 44 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,44 @@
1+
// Module included in the following assemblies:
2+
//
3+
// * virt/monitoring/virt-exposing-downward-metrics.adoc
4+
5+
:_mod-docs-content-type: PROCEDURE
6+
[id="virt-viewing-downward-metrics-tool_{context}"]
7+
= Viewing downward metrics by using the vm-dump-metrics tool
8+
9+
To view downward metrics, install the `vm-dump-metrics` tool and then use the tool to expose the metrics results.
10+
11+
.Procedure
12+
13+
. Install the `vm-dump-metrics` tool by running the following command:
14+
+
15+
[source,terminal]
16+
----
17+
$ sudo dnf install -y vm-dump-metrics
18+
----
19+
20+
. Retrieve the metrics results by running the following command:
21+
+
22+
[source,terminal]
23+
----
24+
$ sudo vm-dump-metrics
25+
----
26+
+
27+
.Example output
28+
[source,xml]
29+
----
30+
<metrics>
31+
<metric type="string" context="host">
32+
<name>HostName</name>
33+
<value>node01</value>
34+
[...]
35+
<metric type="int64" context="host" unit="s">
36+
<name>Time</name>
37+
<value>1619008605</value>
38+
</metric>
39+
<metric type="string" context="host">
40+
<name>VirtualizationVendor</name>
41+
<value>kubevirt.io</value>
42+
</metric>
43+
</metrics>
44+
----

‎modules/virt-viewing-downward-metrics.adoc

Lines changed: 13 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,13 @@
1+
// Module included in the following assemblies:
2+
//
3+
// * virt/monitoring/virt-using-downward-metrics.adoc
4+
5+
:_mod-docs-content-type: PROCEDURE
6+
[id="virt-viewing-downward-metrics_{context}"]
7+
= Viewing downward metrics
8+
9+
You can view downward metrics by using either of the following options:
10+
11+
* The command line interface (CLI)
12+
* The `vm-dump-metrics` tool
13+

‎virt/monitoring/virt-exposing-downward-metrics.adoc

Lines changed: 32 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,32 @@
1+
:_mod-docs-content-type: ASSEMBLY
2+
[id="virt-exposing-downward-metrics"]
3+
= Exposing downward metrics for virtual machines
4+
include::_attributes/common-attributes.adoc[]
5+
:context: virt-exposing-downward-metrics
6+
7+
toc::[]
8+
9+
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.
10+
11+
Users can view the metrics results by using the command line or the `vm-dump-metrics tool`.
12+
13+
[id="virt-enabling-disabling-feature-gate"]
14+
== Enabling or disabling the downwardMetrics feature gate
15+
16+
You can enable or disable the `downwardMetrics` feature gate by performing either of the following actions:
17+
18+
* Editing the HyperConverged custom resource (CR) in your default editor
19+
* Using the command line
20+
21+
include::modules/virt-enabling-disabling-downward-metrics-feature-gate-yaml.adoc[leveloffset=+2]
22+
23+
include::modules/virt-enabling-disabling-downward-metrics-feature-gate-cli.adoc[leveloffset=+2]
24+
25+
include::modules/virt-configuring-downward-metrics.adoc[leveloffset=+1]
26+
27+
include::modules/virt-viewing-downward-metrics.adoc[leveloffset=+1]
28+
29+
include::modules/virt-viewing-downward-metrics-cli.adoc[leveloffset=+2]
30+
31+
include::modules/virt-viewing-downward-metrics-tool.adoc[leveloffset=+2]
32+

0 commit comments

Comments
 (0)