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 <stephenfin@redhat.com> Related-Bug: #1843542
This commit is contained in:
Stephen Finucane
parent
76549775fe
commit
9dfac32959
@ -384,18 +384,6 @@ See `the KVM documentation
|
|||||||
information on these limitations.
|
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
|
KVM performance tweaks
|
||||||
----------------------
|
----------------------
|
||||||
|
|
||||||
|
|||||||
@ -120,6 +120,7 @@ instance for these kind of workloads.
|
|||||||
managing-resource-providers
|
managing-resource-providers
|
||||||
resource-limits
|
resource-limits
|
||||||
cpu-models
|
cpu-models
|
||||||
|
libvirt-misc
|
||||||
|
|
||||||
|
|
||||||
Additional guides
|
Additional guides
|
||||||
|
|||||||
140
doc/source/admin/libvirt-misc.rst
Normal file
140
doc/source/admin/libvirt-misc.rst
Normal file
@ -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 </admin/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
|
||||||
@ -115,103 +115,6 @@ Hardware video RAM
|
|||||||
for more information on how this is used to set the ``videoRamSizeInKB`` attribute with
|
for more information on how this is used to set the ``videoRamSizeInKB`` attribute with
|
||||||
the vmware driver.
|
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:
|
.. _extra-specs-secure-boot:
|
||||||
|
|
||||||
Secure Boot
|
Secure Boot
|
||||||
|
|||||||
Loading…
Reference in New Issue
Block a user