From 9dfac329594933864aceaeb3be28457afd13f6ca Mon Sep 17 00:00:00 2001 From: Stephen Finucane Date: Mon, 22 Feb 2021 18:58:41 +0000 Subject: [PATCH] docs: Add libvirt misc doc A new dumping ground for libvirt'y things that can't easily be categorized or placed elsewhere. Change-Id: I6999b9d66e12e1df7970aff6ce63e5323de6be45 Signed-off-by: Stephen Finucane Related-Bug: #1843542 --- .../admin/configuration/hypervisor-kvm.rst | 12 -- doc/source/admin/index.rst | 1 + doc/source/admin/libvirt-misc.rst | 140 ++++++++++++++++++ doc/source/user/flavors.rst | 97 ------------ 4 files changed, 141 insertions(+), 109 deletions(-) create mode 100644 doc/source/admin/libvirt-misc.rst diff --git a/doc/source/admin/configuration/hypervisor-kvm.rst b/doc/source/admin/configuration/hypervisor-kvm.rst index 5a453f4c4468..fdadde32f9a0 100644 --- a/doc/source/admin/configuration/hypervisor-kvm.rst +++ b/doc/source/admin/configuration/hypervisor-kvm.rst @@ -384,18 +384,6 @@ See `the KVM documentation information on these limitations. -Guest agent support -------------------- - -Use guest agents to enable optional access between compute nodes and guests -through a socket, using the QMP protocol. - -To enable this feature, you must set ``hw_qemu_guest_agent=yes`` as a metadata -parameter on the image you wish to use to create the guest-agent-capable -instances from. You can explicitly disable the feature by setting -``hw_qemu_guest_agent=no`` in the image metadata. - - KVM performance tweaks ---------------------- diff --git a/doc/source/admin/index.rst b/doc/source/admin/index.rst index 39dc76ace7d5..5d51803e2c1b 100644 --- a/doc/source/admin/index.rst +++ b/doc/source/admin/index.rst @@ -120,6 +120,7 @@ instance for these kind of workloads. managing-resource-providers resource-limits cpu-models + libvirt-misc Additional guides diff --git a/doc/source/admin/libvirt-misc.rst b/doc/source/admin/libvirt-misc.rst new file mode 100644 index 000000000000..87dbe18ea47f --- /dev/null +++ b/doc/source/admin/libvirt-misc.rst @@ -0,0 +1,140 @@ +====================== +Other libvirt features +====================== + +The libvirt driver supports a large number of additional features that don't +warrant their own section. These are gathered here. + + +Guest agent support +------------------- + +Guest agents enable optional access between compute nodes and guests through a +socket, using the QMP protocol. + +To enable this feature, you must set ``hw_qemu_guest_agent=yes`` as a metadata +parameter on the image you wish to use to create the guest-agent-capable +instances from. You can explicitly disable the feature by setting +``hw_qemu_guest_agent=no`` in the image metadata. + + +.. _extra-specs-watchdog-behavior: + +Watchdog behavior +----------------- + +.. versionchanged:: 15.0.0 (Ocata) + + Add support for the ``disabled`` option. + +A virtual watchdog device can be used to keep an eye on the guest server and +carry out a configured action if the server hangs. The watchdog uses the +i6300esb device (emulating a PCI Intel 6300ESB). Watchdog behavior can be +configured using the :nova:extra-spec:`hw:watchdog_action` flavor extra spec or +equivalent image metadata property. If neither the extra spec not the image +metadata property are specified, the watchdog is disabled. + +For example, to enable the watchdog and configure it to forcefully reset the +guest in the event of a hang, run: + +.. code-block:: console + + $ openstack flavor set $FLAVOR --property hw:watchdog_action=reset + +.. note:: + + Watchdog behavior set using the image metadata property will override + behavior set using the flavor extra spec. + + +.. _extra-specs-random-number-generator: + +Random number generator +----------------------- + +.. versionchanged:: 21.0.0 (Ussuri) + + Random number generators are now enabled by default for instances. + +Operating systems require good sources of entropy for things like cryptographic +software. If a random-number generator device has been added to the instance +through its image properties, the device can be enabled and configured using +the :nova:extra-spec:`hw_rng:allowed`, :nova:extra-spec:`hw_rng:rate_bytes` and +:nova:extra-spec:`hw_rng:rate_period` flavor extra specs. + +To configure for example a byte rate of 5 bytes per period and a period of 1000 +mSec (1 second), run: + +.. code-block:: console + + $ openstack flavor set $FLAVOR \ + --property hw_rng:rate_bytes=5 \ + --property hw_rng:rate_period=1000 + +Alternatively, to disable the random number generator, run: + +.. code-block:: console + + $ openstack flavor set $FLAVOR --property hw_rng:allowed=false + +The presence of separate byte rate and rate period configurables is +intentional. As noted in the `QEMU docs`__, a smaller rate and larger period +minimizes the opportunity for malicious guests to starve other guests of +entropy but at the cost of responsiveness. Conversely, larger rates and smaller +periods will increase the burst rate but at the potential cost of warping +resource consumption in favour of a greedy guest. + +.. __: https://wiki.qemu.org/Features/VirtIORNG#Effect_of_the_period_parameter + + +.. _extra-specs-performance-monitoring-unit: + +Performance Monitoring Unit (vPMU) +---------------------------------- + +.. versionadded:: 20.0.0 (Train) + +If nova is deployed with the libvirt virt driver and +:oslo.config:option:`libvirt.virt_type` is set to ``qemu`` or ``kvm``, a +virtual performance monitoring unit (vPMU) can be enabled or disabled for an +instance using the :nova:extra-spec:`hw:pmu` flavor extra spec or ``hw_pmu`` +image metadata property. +If the vPMU is not explicitly enabled or disabled via +the flavor or image, its presence is left to QEMU to decide. + +For example, to explicitly disable the vPMU, run: + +.. code-block:: console + + $ openstack flavor set FLAVOR-NAME --property hw:pmu=false + +The vPMU is used by tools like ``perf`` in the guest to provide more accurate +information for profiling application and monitoring guest performance. +For :doc:`real time ` workloads, the emulation of a vPMU can +introduce additional latency which would be undesirable. If the telemetry it +provides is not required, the vPMU can be disabled. For most workloads the +default of unset (enabled) will be correct. + + +.. _extra-specs-hiding-hypervisor-signature: + +Hiding hypervisor signature +--------------------------- + +.. versionadded:: 18.0.0 (Rocky) + +.. versionchanged:: 21.0.0 (Ussuri) + + Prior to the Ussuri release, this was called ``hide_hypervisor_id``. An + alias is provided to provide backwards compatibility. + +Some hypervisors add a signature to their guests. While the presence of the +signature can enable some paravirtualization features on the guest, it can also +have the effect of preventing some drivers from loading. You can hide this +signature by setting the :nova:extra-spec:`hw:hide_hypervisor_id` to true. + +For example, to hide your signature from the guest OS, run: + +.. code:: console + + $ openstack flavor set $FLAVOR --property hw:hide_hypervisor_id=true diff --git a/doc/source/user/flavors.rst b/doc/source/user/flavors.rst index 83e322861f50..a36cfc38e425 100644 --- a/doc/source/user/flavors.rst +++ b/doc/source/user/flavors.rst @@ -115,103 +115,6 @@ Hardware video RAM for more information on how this is used to set the ``videoRamSizeInKB`` attribute with the vmware driver. -.. _extra-specs-watchdog-behavior: - -Watchdog behavior - For the libvirt driver, you can enable and set the behavior of a virtual - hardware watchdog device for each flavor. Watchdog devices keep an eye on the - guest server, and carry out the configured action, if the server hangs. The - watchdog uses the i6300esb device (emulating a PCI Intel 6300ESB). If - ``hw:watchdog_action`` is not specified, the watchdog is disabled. - - To set the behavior, use: - - .. code-block:: console - - $ openstack flavor set FLAVOR-NAME --property hw:watchdog_action=ACTION - - Valid ACTION values are: - - - ``disabled``: (default) The device is not attached. - - ``reset``: Forcefully reset the guest. - - ``poweroff``: Forcefully power off the guest. - - ``pause``: Pause the guest. - - ``none``: Only enable the watchdog; do nothing if the server hangs. - - .. note:: - - Watchdog behavior set using a specific image's properties will override - behavior set using flavors. - -.. _extra-specs-random-number-generator: - -Random-number generator - If a random-number generator device has been added to the instance through - its image properties, the device can be enabled and configured using: - - .. code-block:: console - - $ openstack flavor set FLAVOR-NAME \ - --property hw_rng:allowed=True \ - --property hw_rng:rate_bytes=RATE-BYTES \ - --property hw_rng:rate_period=RATE-PERIOD - - Where: - - - RATE-BYTES: (integer) Allowed amount of bytes that the guest can read from - the host's entropy per period. - - RATE-PERIOD: (integer) Duration of the read period in milliseconds. - -.. _extra-specs-performance-monitoring-unit: - -Performance Monitoring Unit (vPMU) - If nova is deployed with the libvirt virt driver and - :oslo.config:option:`libvirt.virt_type` is set to ``qemu`` or ``kvm``, a - vPMU can be enabled or disabled for an instance using the ``hw:pmu`` - extra_spec or the ``hw_pmu`` image property. - The supported values are ``True`` or ``False``. If the vPMU is not - explicitly enabled or disabled via the flavor or image, its presence is left - to QEMU to decide. - - .. code-block:: console - - $ openstack flavor set FLAVOR-NAME --property hw:pmu=True|False - - The vPMU is used by tools like ``perf`` in the guest to provide more accurate - information for profiling application and monitoring guest performance. - For realtime workloads, the emulation of a vPMU can introduce additional - latency which may be undesirable. If the telemetry it provides is not - required, such workloads should set ``hw:pmu=False``. For most workloads - the default of unset or enabling the vPMU ``hw:pmu=True`` will be correct. - -.. _extra-specs-hiding-hypervisor-signature: - -Hiding hypervisor signature - Some hypervisors add a signature to their guests. While the presence - of the signature can enable some paravirtualization features on the - guest, it can also have the effect of preventing some drivers from - loading. Hiding the signature by setting this property to true may - allow such drivers to load and work. - - .. note:: - - As of the 18.0.0 Rocky release, this is only supported by the libvirt - driver. - - Prior to the 21.0.0 Ussuri release, this was called - ``hide_hypervisor_id``. An alias is provided to provide backwards - compatibility. - - .. code:: console - - $ openstack flavor set FLAVOR-NAME \ - --property hw:hide_hypervisor_id=VALUE - - Where: - - - VALUE: (string) 'true' or 'false'. 'false' is equivalent to the - property not existing. - .. _extra-specs-secure-boot: Secure Boot